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
|
-----------------------------------------------------------------------------
-- bugs
* I've been thinking of a solution along these lines: Haddock
processes the modules in two phases. The first phase resolves all the
names and determines the "definitive" documentation for each entity.
The second phase makes all the links point to the definitive
documentation, with certain exceptions: if the entity is also
documented in the local module, then point there instead. Perhaps
there are other exceptions. We might need a way to indicate
"definitive", or maybe just the module(s) furthest up the dependency
tree would do.
* 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").
* doc --gen-contents and --use-contents
* 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).
* remove the s/r conflicts I added to the grammar
* Support for the rest of GHC extensions in the parser:
- scoped type variables (return types left to do).
- template haskell
- explicit kind annotations
- infix type constructors
* 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.
* derived instance support isn't quite right (doing it properly is
hard, though).
* Referring to something that has a defn but no type signature doesn't
elicit a useful message.
* 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
* Command-line flag to give the effect of --#ignore-exports on all modules
(request by Chris Ryder, for generating implementation docs.)
* Command-line flags to hide modules (easier for Cabal to use than requiring
#hide directives in the source).
* Parse and remember {-# SOURCE #-} imports, possibly do something sensible
with them?
* In theory there's no reason why we have to only link to modules which
are imported by the current module. This is an artificial
restriction. We might try doing a two-pass strategy: first find out
what everything exports, and then resolve all the links in the
documentation. We could mark some modules as "definitive" destinations
for links to their entities, or even give a priority for each module.
* 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?
* Do the unlitting/CPPing from Haddock itself so we get the source file
links right.
* 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
|
