Difference between revisions of "Haddock/Development ideas"
< Haddock
Jump to navigation
Jump to search
MichalPalka (talk | contribs) (Add an idea to show example implementations of some functions) |
Benmachine (talk | contribs) (Removing ideas that are now implemented or irrelevant.) |
||
| (One intermediate revision by one other user 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 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. |
||
| − | |||
* 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 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 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. |
||
| Line 18: | Line 9: | ||
** <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>. |
||
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
(.)andmapMwhere 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.maprather thanmap,Music.Trather than justT. The option for haddock could be--qualification QUALnone(default) strip off qualification (justmap)origshow the identifiers as they are written in the module (e.g.maporList.map)fullshow all identifiers with full qualification (Data.List.map)