1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
-----------------------------------------------------------------------------
-- Small improvements
* When no GHC can be found, give an error message that tells you to use
--with-ghc=<path>
* Instead of receiving the GHC lib dir as input, try to autodetect it with
ghc --print-libdir. Add a --with-ghc flag instead of -B.
* Print an error message when given -optghc=.. instead of --optghc=..
-- ---------------------------------------------------------------------------
-- Before next release
* There should be a --maintainer flag to allow Cabal to pass the maintainer
from the .cabal file to the generated docs.
* The docs don't mention the module header stuff.
-----------------------------------------------------------------------------
-- bugs
* Parser is less liberal than before (pre 2.0.0.0) in respect to doc comments
that aren't attached to anything. Some examples of things people do that
were harmless before:
-- | module header
-- | extra comment describing module
module MyModule where
import Stuff -- ^ we might use this
type MyInt = Int -- ^ comment
* Haddock generates links to hidden modules (e.g. uses of IO point at
GHC.IOBase.IO).
* Haddock fails to process source files containing UNPACK pragmas.
This needs to be fixed in the GHC parser.
* HsParser bug: starting the module with '-- | doc' followed by a declaration
doesn't parse, because the '-- | doc' is interpreted as the module
documentation (the grammar has an S/R conflict because of this).
* We don't point module references ("..." in doc strings) to the correct
package, they are always assumed to be modules in the current package.
* For a non-home occurrence of an entity, we should point to the home
location in the doc somehow. This would help to distinguish
multiple functions with the same name (eg. we don't know whether
Prelude.catch is Control.Exception.catch vs. System.IO.Error.catch).
* The lexer should handle "...." in doc strings, only recognising it if the
contents looks like a module name.
* Mentioning a qualified identifer in doc loses the qualifier, even when
it is required? (see "[Haskell] auto-qualification of identifiers in
Haddock").
* A module re-export should only reference the target module if the
target module is imported without hiding any of its exports (otherwise
we should inline just the exported bits).
* Be a bit cleaner about error cases: some internal errors can be
generated by bugs in the Haskell source. Divide out the proper
internal error cases and emit proper error messages.
* The synopsis generated for a module with no docs should not attempt to
link to the doc for each entity. We need a different kind of summary
here: what we really want is just the documentation section but without
the extra whitespace between decls.
* We don't handle non-ASCII characters in doc comments. (need to specify
the encoding in the generated HTML too?).
* There's no way to refer explicitly to either a type/class
constructor or data constructor When there are more than one of
these with the same name. Perhaps introduce a special syntax for
them? (eg. ':C' means data constructor C?)
-----------------------------------------------------------------------------
-- features
* 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
QUAL=none (default) strip off qualification (just "map")
QUAL=orig show the identifiers as they are written in the module (e.g. "map" or "List.map")
QUAL=full show all identifiers with full qualification (Data.List.map)
Actually I tried to implement it by myself in the old Haddock, but I
could not precisely identify the place, where the qualification is
removed.
* Documentation of arguments of type constructors other than 'top level' arrows. E.g.
T (a {- ^ arg -} -> b {- ^ result -} )
(a {- ^ arg -} -> b {- ^ result -} ) -> c
(a {- ^ x coord -}, b {- ^ y coord -}) -> c
It's probably difficult to format properly in HTML.
* Do something better about re-exported symbols from another package.
* Haddock could compare interfaces from multiple versions of a module
and indicate changes between versions (eg. a small "new!" or
"changed!" icon, or "stable since 1.0").
* Something equivalent to JavaDoc's @since
* Source code: various people want to get at the source code from the docs.
* Optionally include source code for a function in its docs?
* Suggestion from Benjamin Pierce: generat separate HTML pages with the
source code, with anchors that you can link to from the docs.
Sounds fairly easy to implement...
* Parse and remember {-# SOURCE #-} imports, possibly do something sensible
with them?
* nested itemized and enumerated lists.
* There ought to be a way to include some structure in the "description"
(section headings, etc.) and possibly in other comments. (suggseted
by Daan).
* Comments on instance declarations? (suggested by Daan and Iavor).
* Comments on default method declarations? (suggested by Satnam).
* Comments on components of a tuple, for argument or return types.
* Add a search feature which just invokes Google?
* attributes for individual declarations, eg.
-- #abstract
or targetted to a specific decl:
-- #T: abstract
#long, #short, #noinstances (on a type or class)
#inline, #noinline on a module export
* Allow documentation annotations to explicitly name the entity they
refer to.
* In the contents page, indicate portability/stability of each module
somehow.
* Add back-references from the definition to the uses of types/classes
(perhaps in the index?)
* Add a link to the defining location of a re-exported entity
* fixities
* include file revision info in module headers
* Allow individual function arguments to be documented when the function
type is a record element?
* hiding instances?
* Add a way to indicate DEPRECATED functions/types/modules? Perhaps
parse the GHC DEPRECATED pragma?
-----------------------------------------------------------------------------
-- cosmetic
* Allow more parts of the documentation to be squashed and expanded?
* for a constructor, don't fill its entire cell with a grey background.
* switch to longer rendering form for datatypes when necessary?
* remove extra whitespace from the generated HTML to save space
|
