Personal tools

Haddock/Development ideas

From HaskellWiki

< Haddock
Revision as of 21:12, 26 February 2008 by MichalPalka (Talk | contribs)

Jump to: navigation, search

There would be a number of benefits if GHC's parser were extended to understand the Haddock documentation markup and then Haddock changed to use the GHC API:

  • Haddock would get full support for GHC's various syntactic extensions.
  • Haddock would understand {#- LINE -#} pragmas which would allow it to generate links to the original source code.
  • Haddock would get much better error messages.
  • Haddock could infer types for functions with no explicit type signature.
  • GHCi and IDEs like hIDE and Visual Haskell would be able to display API documentation in more convenient ways like in this Haste screenshot:

Haste screenshot hovering.png

  • Haddock could accept module parameters with space after "-- #" ("-- #hide" is accepted nowadays, but "-- # hide" not)
  • It would be good to have a recursive flag that would operate on all the .hs and .lhs files under a single directory.
  • Haddock should emit the documentation about instances. For example, it's important to document that the Data.Map instance of Foldable only folds over the values and not the keys.
  • There should be an annotation to include a function's entire definition in the documentation. This would be useful for functions like
    where the definition is the clearest possible documentation, and for QuickCheck properties that specify the behavior of a library.
  • There should be an option to include a simplified implementation of a function that is equivalent to the one in the code. For instance, instead of showing a complex implementation of List.length that makes use of stream fusion we could show a simple one based on foldl'.
  • Optionally show qualifications of identifiers, that is print
    rather than
    rather than just
    . The option for haddock could be --qualification QUAL
    • none (default) strip off qualification (just
    • orig show the identifiers as they are written in the module (e.g.
    • full show all identifiers with full qualification (
  • It should be possible to document parameters of function arguments.
fix ::
  (   a {- ^ local argument -}
   -> a {- ^ local output -} )
      -> a {- ^ global output -}
This is also of interest for other type constructors like the pair type constructor