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
|
<!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<book id="haddock">
<bookinfo>
<date>2002-4-10</date>
<title>Haddock User Guide</title>
<author>
<firstname>Simon</firstname>
<surname>Marlow</surname>
</author>
<address><email>simonmar@microsoft.com</email></address>
<copyright>
<year>2002</year>
<holder>Simon Marlow</holder>
</copyright>
<abstract>
<para>This document describes Haddock, a Haskell documentation
tool.</para>
</abstract>
</bookinfo>
<!-- Table of contents -->
<toc></toc>
<chapter id="introduction">
<title>Introduction</title>
<para>This is Haddock, a tool for automatically generating
documentation from annotated Haskell source code. Haddock was
designed with several goals in mind:</para>
<itemizedlist>
<listitem>
<para>When documenting APIs, it is desirable to keep the
documentation close to the actual interface or implementation
of the API, preferably in the same file, to reduce the risk
that the two become out of sync. Haddock therefore lets you
write the documentation for an entity (function, type, or
class) next to the definition of the entity in the source
code.</para>
</listitem>
<listitem>
<para>There is s tremendous amount of useful API documentation
that can be extracted from just the bare source code,
including types of exported functions, definitions of data
types and classes, and so on. Haddock can therefore generate
documentation from a set of straight Haskell 98 modules, and
the documentation will contain precisely the interface that is
available to a programmer using those modules.</para>
</listitem>
<listitem>
<para>Documentation annotations in the source code should be
easy on the eye when editing the source code itself, so as not
to obsure the code and to make reading and writing
documentation annotations easy. Haddock therefore uses
lightweight markup in its annotations, taking several ideas
from <ulink
url="http://www.cse.unsw.edu.au/~chak/haskell/idoc/">IDoc</ulink>.
In fact, Haddock can understand IDoc-annotated source
code.</para>
</listitem>
<listitem>
<para>The documentation should not expose any of the structure
of the implementation, or to put it another way, the
implementer of the API should be free to structure the
implementation however he or she wishes, without exposing any
of that structure to the consumer. In practical terms, this
means that while an API may internally consist of several
Haskell modules, we often only want to expose a single module
to the user of the interface, where this single module just
re-exports the relevant parts of the implementation
modules.</para>
<para>Haddock therefore understands the Haskell module system
and can generate documentation which hides the internal module
structure of the interface. A documentation annotation can
still be placed next to the implementation, and it will be
propagated to the external module in the generated
documentation.</para>
</listitem>
<listitem>
<para>Being able to move around the documentation by following
hyperlinks is essential. Documentation generated by Haddock
is therefore littered with hyperlinks: every type and class
name is a link to the corresponding definition, and
user-written documentation annotations can contain identifiers
which are linked automatically when the documentation is
generated.</para>
</listitem>
<listitem>
<para>We might want documentation in multiple formats - online
and printed, for example. Haddock comes with HTML and DocBook
backends, and it is structured in such a way that adding new
back-ends is straightforward.</para>
</listitem>
</itemizedlist>
<section id="obtaining">
<title>Obtaining Haddock</title>
<para>Distributions (source & binary) of Haddock can be obtained
from its <ulink url="http://www.haskell.org/haddock/">web
site</ulink>.</para>
<para>Up-to-date sources can also be obtained from CVS. The
Haddock sources are under <literal>fptools/haddock</literal> in
the <literal>fptools</literal> CVS repository, which also
contains GHC, Happy, and several other projects. See <ulink
url="http://www.haskell.org/ghc/docs/latest/building/sec-cvs.html">Using
The CVS Repository</ulink> for information on how to access the
CVS repository. Note that you need to check out the
<literal>fpconfig</literal> module first to get the generic
build system (the <literal>fptools</literal> directory), and
then check out <literal>fptools/haddock</literal> to get the
Haddock sources.</para>
</section>
<section id="license">
<title>License</title>
<para>The following license covers this documentation, and the
Haddock source code, except where otherwise indicated.</para>
<blockquote>
<para>Copyright 2002, Simon Marlow. All rights reserved.</para>
<para>Redistribution and use in source and binary forms, with
or without modification, are permitted provided that the
following conditions are met:</para>
<itemizedlist>
<listitem>
<para>Redistributions of source code must retain the above
copyright notice, this list of conditions and the
following disclaimer.</para>
</listitem>
<listitem>
<para>Redistributions in binary form must reproduce the
above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other
materials provided with the distribution.</para>
</listitem>
</itemizedlist>
<para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.</para>
</blockquote>
</section>
</chapter>
<chapter id="invoking">
<title>Invoking Haddock</title>
<para></para>
</chapter>
<chapter id="markup">
<title>Documentation and Markup</title>
<para></para>
</chapter>
</book>
|
