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)
(doctest does the QC stuff)
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
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/As a library|GHC API]]:
+
Most of these ideas are '''very''' old, but some may still be relevant.
   
* Haddock would get full support for GHC's various syntactic extensions.
 
* Haddock would understand <code>{#- LINE -#}</code> 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 [http://haste.dyndns.org:8080/ Haste] screenshot:
 
[[Image: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.
 
* It would be good to have a recursive flag that would operate on all the .hs and .lhs files under a single directory.
+
* There should be an annotation to include a function's entire definition in the documentation. This would be useful for functions like <hask>(.)</hask> and <hask>mapM</hask> where the definition is the clearest possible documentation.
* 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 <hask>(.)</hask> and <hask>mapM</hask> 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'.
 
* 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 [http://www.haskell.org/pipermail/haskell-cafe/2008-January/038211.html show qualifications of identifiers], that is print <hask>Sequence.map</hask> rather than <hask>map</hask>, <hask>Music.T</hask> rather than just <hask>T</hask>. The option for haddock could be <code>--qualification QUAL</code>
 
* Optionally [http://www.haskell.org/pipermail/haskell-cafe/2008-January/038211.html show qualifications of identifiers], that is print <hask>Sequence.map</hask> rather than <hask>map</hask>, <hask>Music.T</hask> rather than just <hask>T</hask>. The option for haddock could be <code>--qualification QUAL</code>
Line 16: Line 8:
 
** <code>orig</code> show the identifiers as they are written in the module (e.g. <hask>map</hask> or <hask>List.map</hask>)
 
** <code>orig</code> show the identifiers as they are written in the module (e.g. <hask>map</hask> or <hask>List.map</hask>)
 
** <code>full</code> show all identifiers with full qualification (<hask>Data.List.map</hask>)
 
** <code>full</code> show all identifiers with full qualification (<hask>Data.List.map</hask>)
* It should be possible to [http://www.haskell.org/pipermail/haskell-cafe/2007-August/030390.html document parameters of function arguments].
 
<haskell>
 
fix ::
 
( a {- ^ local argument -}
 
-> a {- ^ local output -} )
 
-> a {- ^ global output -}
 
</haskell>
 
: This is also of interest for other type constructors like the pair type constructor <hask>(,)</hask>.
 

Latest revision as of 19:11, 14 March 2014

Most of these ideas are very old, but some may still be relevant.

  • It would be good to have a recursive flag that would operate on all the .hs and .lhs files under a single directory.
  • 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.
  • 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
      )