Personal tools

Haddock/Development ideas

From HaskellWiki

< Haddock(Difference between revisions)
Jump to: navigation, search
(Add an idea to show example implementations of some functions)
(ch haste ln)
Line 5: Line 5:
 
* Haddock would get much better error messages.
 
* Haddock would get much better error messages.
 
* Haddock could infer types for functions with no explicit type signature.
 
* 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 [http://haste.dyndns.org:8080/ Haste] screenshot:
+
* GHCi and IDEs like [[hIDE]] and [[Visual Haskell]] would be able to display API documentation in more convenient ways like in this [[Haste]]] screenshot:
 
[[Image:Haste_screenshot_hovering.png]]
 
[[Image:Haste_screenshot_hovering.png]]
   

Revision as of 02:24, 26 March 2008

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
    (.)
    and
    mapM
    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
    Sequence.map
    rather than
    map
    ,
    Music.T
    rather than just
    T
    . The option for haddock could be --qualification QUAL
    • none (default) strip off qualification (just
      map
      )
    • orig show the identifiers as they are written in the module (e.g.
      map
      or
      List.map
      )
    • full show all identifiers with full qualification (
      Data.List.map
      )
  • 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
(,)
.