-- ---------------------------------------------------------------------------
-- Before next release

-----------------------------------------------------------------------------
-- bugs

* HsParser bug: starting the module with '-- | doc' followed by a declaration
  doesn't parse, because the '-- | doc' is interpreted as the module
  documentation (the grammar has an S/R conflict because of this).

* We don't point module references ("..." in doc strings) to the correct
  package, they are always assumed to be modules in the current package.

* For a non-home occurrence of an entity, we should point to the home
  location in the doc somehow.  This would help to distinguish
  multiple functions with the same name (eg. we don't know whether
  Prelude.catch is Control.Exception.catch vs. System.IO.Error.catch).

* The lexer should handle "...." in doc strings, only recognising it if the
  contents looks like a module name.

* Mentioning a qualified identifer in doc loses the qualifier, even when
  it is required?  (see "[Haskell] auto-qualification of identifiers in
  Haddock").

* A module re-export should only reference the target module if the
  target module is imported without hiding any of its exports (otherwise
  we should inline just the exported bits).

* remove the s/r conflicts I added to the grammar

* Support for the rest of GHC extensions in the parser:
  - scoped type variables (return types left to do).
  - template haskell
  - explicit kind annotations
  - infix type constructors

* Be a bit cleaner about error cases: some internal errors can be
  generated by bugs in the Haskell source.  Divide out the proper
  internal error cases and emit proper error messages.

* derived instance support isn't quite right (doing it properly is 
  hard, though).

* The synopsis generated for a module with no docs should not attempt to
  link to the doc for each entity.  We need a different kind of summary
  here: what we really want is just the documentation section but without
  the extra whitespace between decls.

* We don't handle non-ASCII characters in doc comments.  (need to specify
  the encoding in the generated HTML too?).

* There's no way to refer explicitly to either a type/class
  constructor or data constructor When there are more than one of
  these with the same name.  Perhaps introduce a special syntax for
  them?  (eg. ':C' means data constructor C?)

-----------------------------------------------------------------------------
-- features

* Haddock could compare interfaces from multiple versions of a module
  and indicate changes between versions (eg. a small "new!" or
  "changed!" icon, or "stable since 1.0").

* Something equivalent to JavaDoc's @since

* Source code: various people want to get at the source code from the docs.
  * Optionally include source code for a function in its docs?
  * Suggestion from Benjamin Pierce: generat separate HTML pages with the
    source code, with anchors that you can link to from the docs.
    Sounds fairly easy to implement...

* Parse and remember {-# SOURCE #-} imports, possibly do something sensible
  with them?

* nested itemized and enumerated lists.

* There ought to be a way to include some structure in the "description"
  (section headings, etc.) and possibly in other comments.  (suggseted
  by Daan).

* Comments on instance declarations?  (suggested by Daan and Iavor).

* Comments on default method declarations?  (suggested by Satnam).

* Comments on components of a tuple, for argument or return types.

* Add a search feature which just invokes Google?

* attributes for individual declarations, eg.
    -- #abstract
  or targetted to a specific decl:
    -- #T: abstract

  #long, #short, #noinstances (on a type or class)

  #inline, #noinline on a module export

* Allow documentation annotations to explicitly name the entity they
  refer to.

* In the contents page, indicate portability/stability of each module
  somehow.

* Add back-references from the definition to the uses of types/classes
  (perhaps in the index?)

* Add a link to the defining location of a re-exported entity

* fixities

* include file revision info in module headers

* Allow individual function arguments to be documented when the function
  type is a record element?

* hiding instances?

* Add a way to indicate DEPRECATED functions/types/modules?  Perhaps
  parse the GHC DEPRECATED pragma?

-----------------------------------------------------------------------------
-- cosmetic

* Allow more parts of the documentation to be squashed and expanded?

* for a constructor, don't fill its entire cell with a grey background.

* switch to longer rendering form for datatypes when necessary?

* remove extra whitespace from the generated HTML to save space