Difference between revisions of "Haddock/Development ideas"
< Haddock
Jump to navigation
Jump to search
m (typo) |
Benmachine (talk | contribs) (Removing ideas that are now implemented or irrelevant.) |
||
(8 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
+ | Most of these ideas are '''very''' old, but some may still be relevant. |
||
− | 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]]: |
||
⚫ | |||
− | * Haddock would get full support for GHC's various syntactic extensions. |
||
+ | * 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. |
||
− | * Haddock would understand <code>{#- LINE -#}</code> pragmas which would allow it to generate links to the original source code. |
||
+ | * 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. |
||
− | * Haddock would get much better error messages. |
||
+ | * 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'. |
||
− | * Haddock could infer types for functions with no explicit type signature. |
||
+ | * 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> |
||
− | * 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: |
||
+ | ** <code>none</code> (default) strip off qualification (just <hask>map</hask>) |
||
− | [[Image:Haste_screenshot_hovering.png]] |
||
+ | ** <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>) |
||
⚫ | |||
− | |||
− | It would be nice if haddock is able to parse more user defined operators like (#). |
Revision as of 12:19, 17 December 2012
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.
- 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
(.)
andmapM
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 thanmap
,Music.T
rather than justT
. The option for haddock could be--qualification QUAL
none
(default) strip off qualification (justmap
)orig
show the identifiers as they are written in the module (e.g.map
orList.map
)full
show all identifiers with full qualification (Data.List.map
)