Known problems in HDoc:
=======================

- Scanner.x is written for Alex 1.x; it cannot be used with Alex 2.0.

- HDoc's scanner is slow, on some input files _very_ slow (needs
  quadratic time in file length).
  This is a due to a problem in the scanner generator Alex.
  Possible fixes: rewrite HDoc's scanner (without Alex), or rewrite Alex.


- HsParser does not tell the location of the "module" keyword [...]

  Update 2001-12-29: solved by modifying HsParser


- The input files must be parseable by HsParser, i.e. they must contain
  syntactically correct Haskell (i.e. HsParser's idea of correct
  Haskell). The 0.7.1 release of HDoc uses a newer version of HsParser
  (compared to the older releases), so full Haskell '98 should be
  accepted now. As a consequence, HDoc will fail with modules using
  non-standard features like "foreign import" etc.

  Update 2001-12-29: "foreign import", "foreign export",
  functional dependencies, pattern type signatures, and explicit
  quantification ("forall a.") should work with the modified HsParser
  included in the HDoc 0.8.1 distribution.


- As instances aren't explicitly exported from Haskell modules,
  there's no reliable way for HDoc to find out for which instances it
  should generate documentation, consider

    module X(D) where

    data D = ...

    instance Eq D where ...

  Is "Eq D" only used locally or should it be available to the user?
  What shall we do with

    module Y(f) where

    import X

  Should the documentation for module Y include documentation for
  "Eq D" (note that "D" could be visible to the user through a different
  path in the module hierarchy) ?

  HDoc simply emits documentation for every instance declaration which
  is found on the import paths. Unfortunately this can produce
  instance functions without type signatures (when the class isn't
  imported in the affected module). There'll have to be some
  discussion on how to handle instance declarations correctly.