aboutsummaryrefslogtreecommitdiff
path: root/doc/haddock.sgml
blob: a9730394b3a80578797cddc68c5ea15db4c144a3 (plain) (blame)
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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
<!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.  The easier it is to write
	documentation, the more likely the programmer is to do it.
	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 not only
	non-exported entities from the interface, but also 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>

    <section>
      <title>Acknowledgements</title>
      
      <para>Several documentation systems provided the inspiration for
      Haddock, most notably:</para>

      <itemizedlist>
	<listitem>
	  <para><ulink
          url="http://www.cse.unsw.edu.au/~chak/haskell/idoc/">
          IDoc</ulink></para>
	</listitem>
	<listitem>
	  <para><ulink
	  url="http://www.fmi.uni-passau.de/~groessli/hdoc/">HDoc</ulink></para>
	</listitem>
	<listitem>
	  <para><ulink url="http://www.stack.nl/~dimitri/doxygen/">
          Doxygen</ulink></para>
	</listitem>
      </itemizedlist>

      <para>and probably several others I've forgotten.</para>

      <para>Thanks to the following people for useful feedback,
      discussion, patches, and moral support: Simon Peyton Jones, Mark
      Shields, Manuel Chakravarty, Ross Patterson, Brett Letner, the
      members of <email>haskelldoc@haskell.org</email>, and everyone
      who contributed to the many libraries that Haddock makes use
      of.</para>
    </section>

  </chapter>

  <chapter id="invoking">
    <title>Invoking Haddock</title>
    <para>Haddock is invoked from the command line, like so:</para>

    <cmdsynopsis>
      <command>haddock</command>
      <arg rep=repeat><replaceable>option</replaceable></arg>
      <arg rep=repeat choice=plain><replaceable>file</replaceable></arg>
    </cmdsynopsis>

    <para>Where each <replaceable>file</replaceable> is a filename
    containing a Haskell source module.  All the modules specified on
    the command line will be processed together.  When one module
    refers to an entity in another module being processed, the
    documentation will link directly to that entity.</para>

    <para>Entities that cannot be found, for example because they are
    in a module that isn't being processed as part of the current
    batch, simply won't be hyperlinked in the generated
    documentation.  Haddock will emit warnings listing all the
    indentifiers it couldn't resolve.</para>

    <para>The modules should <emphasis>not</emphasis> be mutually
    recursive, as Haddock don't like swimming in circles.</para> 

    <para>The following options are available:</para>

    <variablelist>
      <varlistentry>
	<term><option>-d</option></term>
	<term><option>--docbook</option></term>
	<indexterm><primary><option>-d</option></primary></indexterm>
	<indexterm><primary><option>--docbook</option></primary></indexterm>
	<listitem>
	  <para>Output documentation in SGML DocBook format.  NOTE: at
	  time of writing this is only partially implemented and
	  doens't work.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-h</option></term>
	<term><option>--html</option></term>
	<indexterm><primary><option>-h</option></primary></indexterm>
	<indexterm><primary><option>--html</option></primary></indexterm>
	<listitem>
	  <para>Generate documentation in HTML format.  Several files
	  will be generated into the current directory (or the
	  specified directory if the <option>-o</option> option is
	  given), including the following:</para>
	  <variablelist>
	    <varlistentry>
	      <term><filename>index.html</filename></term>
	      <listitem>
		<para>The top level page of the documentation: lists
		the modules available, using indentation to represent
		the hierarchy if the modules are hierarchical.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><filename>haddock.css</filename></term>
	      <listitem>
		<para>The stylesheet used by the generated HTML.  Feel
		free to modify this to change the colors or
		layout, or even specify your own stylesheet using the
		<option>--css</option> option.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><filename><replaceable>module</replaceable>.html</filename></term>
	      <listitem>
		<para>An HTML page for each
		<replaceable>module</replaceable>.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><filename>doc-index.html</filename></term>
	      <term><filename>doc-index-XX.html</filename></term>
	      <listitem>
		<para>The index, split into two
		(functions/constructors and types/classes, as per
		Haskell namespaces) and further split
		alphabetically.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-o</option> <replaceable>dir</replaceable></term>
	<term><option>--odir</option>=<replaceable>dir</replaceable></term>
	<indexterm><primary><option>-o</option></primary></indexterm>
	<indexterm><primary><option>--odir</option></primary></indexterm>
	<listitem>
	  <para>Generate files into <replaceable>dir</replaceable>
	  instead of the current directory.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-s</option> <replaceable>URL</replaceable></term>
	<term><option>--source</option>=<replaceable>URL</replaceable></term>
	<indexterm><primary><option>-s</option></primary></indexterm>
	<indexterm><primary><option>--source</option></primary></indexterm>
	<listitem>
	  <para>Include links to the source files in the generated
	  documentation, where <replaceable>URL</replaceable> is the
	  base URL where the source files can be found.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-t</option> <replaceable>title</replaceable></term>
	<term><option>--title</option>=<replaceable>title</replaceable></term>
	<indexterm><primary><option>-t</option></primary></indexterm>
	<indexterm><primary><option>--title</option></primary></indexterm>
	<listitem>
	  <para>Use <replaceable>title</replaceable> as the page
	  heading for each page in the documentation.This will
	  normally be the name of the library being documented.</para>

	  <para>The title should be a plain string (no markup
	  please!).</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-v</option></term>
	<term><option>--verbose</option></term>
	<indexterm><primary><option>-v</option></primary></indexterm>
	<indexterm><primary><option>--verbose</option></primary></indexterm>
	<listitem>
	  <para>Reserved for future expansion.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--css</option>=<replaceable>filename</replaceable></term>
	<indexterm><primary><option>--css</option></primary></indexterm>
	<listitem>
	  <para>Specify a stylesheet to use instead of the default one
	  that comes with Haddock.  It should specify certain classes:
	  see the default stylesheet for details.</para>
	</listitem>
      </varlistentry>
    </variablelist>

  </chapter>
  
  <chapter id="markup">
    <title>Documentation and Markup</title>

    <para>Haddock understands special documentation annotations in the
    Haskell source file and propagates these into the generated
    documentation.  The annotations are purely optional: if there are
    no annotations, Haddock will just generate documentation that
    contains the type signatures, data type declarations, and class
    declarations exported by each of the modules being
    processed.</para>

    <section>
      <title>Documenting a top-level declaration</title>

      <para>The simplest example of a documentation annotation is for
      documenting any top-level declaration (function type signature,
      type declaration, or class declaration).  For example, if the
      source file contains the following type signature:</para>

<programlisting>
square :: Int -> Int
square x = x * x
</programlisting>

    <para>Then we can document it like this:</para>

<programlisting>
-- |The 'square' function squares an integer.
square :: Int -> Int
square x = x * x
</programlisting>


      <para>The <quote><literal>-- |</literal></quote> syntax begins a
      documentation annotation, which applies to the
      <emphasis>following</emphasis> declaration in the source file.
      Note that the annotation is just a comment in Haskell &mdash; it
      will be ignored by the Haskell compiler.</para>

      <para>The declaration following a documentation annotation
      should be one of the following:</para>
      <itemizedlist>
	<listitem>
	  <para>A type signature for a top-level function,</para>
	</listitem>
	<listitem>
	  <para>A <literal>data</literal> declaration,</para>
	</listitem>
	<listitem>
	  <para>A <literal>newtype</literal> declaration,</para>
	</listitem>
	<listitem>
	  <para>A <literal>type</literal> declaration, or</para>
	</listitem>
	<listitem>
	  <para>A <literal>class</literal> declaration.</para>
	</listitem>
      </itemizedlist>

      <para>If the annotation is followed by a different kind of
      declaration, it will probably be ignored by Haddock.</para>

      <para>Some people like to write their documentation
      <emphasis>after</emphasis> the declaration; this is possible in
      Haddock too:</para>
     
<programlisting>
square :: Int -> Int
-- ^The 'square' function squares an integer.
square x = x * x
</programlisting>

      <para>Note that Haddock doesn't contain a Haskell type system
      &mdash; if you don't write the type signature for a function,
      then Haddock can't tell what its type is and it won't be
      included in the documentation.</para>
      
    </section>
    <section>
      <title>Documenting parts of a declaration</title>
      
      <para>In addition to documenting the whole declaration, in some
      cases we can also document individual parts of the
      declaration.</para>

      <section>
	<title>Class methods</title>
	  
	<para>Class methods are documented in the same way as top
	level type signatures, by using either the
	<quote><literal>--&nbsp;|</literal></quote> or
	<quote><literal>--&nbsp;^</literal></quote>
	annotations:</para>
	  
<programlisting>
class C a where
   -- | This is the documentation for the 'f' method
   f :: a -> Int
   -- | This is the documentation for the 'g' method
   g :: Int -> a
</programlisting>

	<para>Note that in Haddock documentation annotations are
	first-class syntactic objects that are subject to the same
	layout rules as other syntactic objects; thus in the example
	class declaration above the documentation annotations must
	begin in the same column as the method signatures.  If you use
	explicit layout, then don't forget the semi-colon after each
	documentation comment (but don't put the semi-colon on the
	same line as the documentation comment, because it will be
	interpreted as part of the documentation!).</para>
      </section>

      <section>
	<title>Constructors and record fields</title>

	<para>Constructors are documented like so:</para>

<programlisting>
data T a b
  = -- | This is the documentation for the 'C1' constructor
    C1 a b 
  | -- | This is the documentation for the 'C2' constructor
    C2 a b 
</programlisting>

	<para>or like this:</para>

<programlisting>
data T a b
  = C1 a b  -- ^ This is the documentation for the 'C1' constructor
  | C2 a b  -- ^ This is the documentation for the 'C2' constructor
</programlisting>

	<para>Record fields are documented using one of these
	styles:</para>

<programlisting>
data R a b = 
  C { -- | This is the documentation for the 'a' field
      a :: a,
      -- | This is the documentation for the 'b' field
      b :: b
    }

data R a b = 
  C { a :: a,  -- ^ This is the documentation for the 'a' field
      b :: b   -- ^ This is the documentation for the 'b' field
    }
</programlisting>
      </section>

      <section>
	<title>Function arguments</title>
	
	<para>Individual arguments to a function may be documented
	like this:</para>

<programlisting>
f  :: Int      -- ^ The 'Int' argument
   -> Float    -- ^ The 'Float' argument
   -> IO ()    -- ^ The return value
</programlisting>

	<para>NOTE: this feature isn't implemented in Haddock
	0.1.</para>
      </section>
    </section>

    <section>
      <title>The module description</title>

      <para>A module may contain a documentation comment before the
      module header, in which case this comment is interpreted by
      Haddock as an overall description of the module itself, and
      placed in a section entitled <quote>Description</quote> in the
      documentation for the module.  For example:</para>

<programlisting>
-- | This is the description for module "Foo"
module Foo where
...
</programlisting>
    </section>
    
    <section>
      <title>Controlling the documentation structure</title>
	
      <para>Haddock produces interface documentation that lists only
      the entities actually exported by the module.  The documentation
      for a module will include <emphasis>all</emphasis> entities
      exported by that module, even if they were re-exported by
      another module.  The only exception is when Haddock can't see
      the declaration for the re-exported entity, perhaps because it
      isn't part of the batch of modules currently being
      processed.</para>

      <para>However, to Haddock the export list has even more
      significance than just specifying the entities to be included in
      the documentation.  It also specifies the
      <emphasis>order</emphasis> that entities will be listed in the
      generated documentation.  This leaves the programmer free to
      implement functions in any order he/she pleases, and indeed in
      any <emphasis>module</emphasis> he/she pleases, but still
      specify the order that the functions should be documented in the
      export list.  Indeed, many programmers already do this: the
      export list is often used as a kind of ad-hoc interface
      documentation, with headings, groups of functions, type
      signatures and declarations in comments.</para>

      <para>You can insert headings and sub-headings in the
      documentation by including annotations at the appropriate point
      in the export list.  For example:</para>

<programlisting>
module Foo (
  -- * Classes
  C(..),
  -- * Types
  -- ** A data type
  T,
  -- ** A record
  R,
  -- * Some functions
  f, g
  ) where
</programlisting>

      <para>Headings are introduced with the syntax
      <quote><literal>--&nbsp;*</literal></quote>,
      <quote><literal>--&nbsp;**</literal></quote> and so on, where
      the number of <literal>*</literal>s indicates the level of the
      heading (section, sub-section, sub-sub-section, etc.).</para>

      <para>If you use section headings, then Haddock will generate a
      table of contents at the top of the module documentation for
      you.</para>

      <section>
	<title>Re-exporting an entire module</title>
	
	<para>Haskell allows you to re-export the entire contents of a
	module (or at least, everything currently in scope that was
	imported from a given module) by listing it in the export
	list:</para>

<programlisting>
module Foo (
  module Bar,
  module Baz
 ) where	  
</programlisting>

	<para>What will the Haddock-generated documentation for this
	module look like?  Well, Haddock simply behaves as if the
	export list for modules <literal>Bar</literal> and
	<literal>Baz</literal> had been expanded in-place in the
	export list for <literal>Foo</literal>, including all of their
	structure (section headings etc.).</para>
      </section>
      
      <section>
	<title>Omitting the export list</title>
	
	<para>If there is no export list in the module, how does
	Haddock generate documentation?  Well, when the export list is
	omitted, e.g.:</para>

<programlisting>module Foo where</programlisting>

	<para>this is equivalent to an export list which mentions
	every entity defined at the top level in this module, and
	Haddock treats it in the same way.  Furthermore, the generated
	documentation will retain the order in which entities are
	defined in the module.  In this special case the module body
	may also include section headings (normally they would be
	ignored by Haddock).</para>
      </section>
    </section>

    <section>
      <title>Named chunks of documentation</title>

      <para>Occasionally it is desirable to include a chunk of
      documentation which is not attached to any particular Haskell
      declaration.  There are two ways to do this:</para>

      <itemizedlist>
	<listitem>
	  <para>The documentation can be included in the export list
	  directly, e.g.:</para>

<programlisting>
module Foo (
   -- * A section heading
   -- | Some documentation not attached to a particular Haskell entity
   ...
 ) where
</programlisting>
	</listitem>
	
	<listitem>
	  <para>If the documentation is large and placing it inline in
	  the export list might bloat the export list and obscure the
	  structure, then it can be given a name and placed out of
	  line in the body of the module.  This is achieved with a
	  special form of documentation annotation
	  <quote><literal>--&nbsp;$</literal></quote>:</para>

<programlisting>
module Foo (
   -- * A section heading
   -- $doc
   ...
 ) where

-- $doc 
-- Here is a large chunk of documentation which may be referred to by
-- the name $doc.
</programlisting>

	  <para>The documentation chunk is given a name, which is the
	  sequence of alphanumeric characters directly after the
	  <quote><literal>--&nbsp;$</literal></quote>, and it may be
	  referred to by the same name in the export list.</para>
	</listitem>
      </itemizedlist>
    </section>

    <section>
      <title>Hyperlinking and re-exported entities</title> 
      
      <para>When Haddock renders a type in the generated
      documentation, it hyperlinks all the type constructors and class
      names in that type to their respective definitions.  But for a
      given type constructor or class there may be several modules
      re-exporting it, and therefore several modules whose
      documentation contains the definition of that type or class
      (possibly including the current module!) so which one do we link
      to?</para>

      <para>Let's look at an example.  Suppose we have three modules
      <literal>A</literal>, <literal>B</literal> and
      <literal>C</literal> defined as follows:</para>

<programlisting>
module A (T) where
data T a = C a

module B (f) where
import A
f :: T Int -> Int
f (C i) = i

module C (T, f) where
import A
import B
</programlisting>

      <para>Module <literal>A</literal> exports a datatype
      <literal>T</literal>.  Module <literal>B</literal> imports
      <literal>A</literal> and exports a function <literal>f</literal>
      whose type refers to <literal>T</literal>: the hyperlink in
      <literal>f</literal>'s signature will point to the definition of
      <literal>T</literal> in the documentation for module
      <literal>A</literal>.</para>

      <para>Now, module <literal>C</literal> exports both
      <literal>T</literal> and <literal>f</literal>.  We have a choice
      about where to point the hyperlink to <literal>T</literal> in
      <literal>f</literal>'s type: either the definition exported by
      module <literal>C</literal> or the definition exported by module
      <literal>A</literal>.  Haddock takes the view that in this case
      pointing to the definition in <literal>C</literal> is better,
      because the programmer might not wish to expose
      <literal>A</literal> to the programmer at all:
      <literal>A</literal> might be a module internal to the
      implementation of the library in which <literal>C</literal> is
      the external interface, so linking to definitions in the current
      module is preferrable over an imported module.</para>

      <para>The general rule is this: when attempting to link an
      instance of a type constructor or class to its definition, the
      link is made to</para>
      <itemizedlist>
	<listitem>
	  <para>the current module, if the current module exports the
	  relevant definition, or</para>
	</listitem>
	<listitem>
	  <para>the module that the entity was imported from,
	  otherwise.  If the entity was imported via multiple routes,
	  then Haddock picks the module listed earliest in the imports
	  of the current module.</para>
	</listitem>
      </itemizedlist>
    </section>

    <section>
      <title>Markup</title>

      <para>Haddock understands certain textual queues inside
      documentation annotations that tell it how to render the
      documentation.  The queues (or <quote>markup</quote>) have been
      designed to be simple and mnemonic in ASCII so that the
      programmer doesn't have to deal with heavyweight annotations
      when editing documentation comments.</para>

      <section>
	<title>Paragraphs</title>
	
	<para>One or more blank lines separates two paragraphs in a
	documentation comment.</para>
      </section>

      <section>
	<title>Special characters</title>

	<para>The following characters have special meanings in
	documentation comments: <literal>/</literal>,
	<literal>'</literal>, <literal>[</literal>,
	<literal>]</literal>, <literal>&lt;</literal>.  To insert a
	literal occurrence of one of these special characters, precede
	it with a backslash (<literal>\</literal>).</para>

	<para>Additionally, the following characters have special
	meanings at the beginning of a paragraph:
	<literal>*</literal>, <literal>-</literal>.  These characters
	can also be escaped using <literal>\</literal>.</para>

      </section>

      <section>
	<title>Emphasis and Monospaced text</title>

	<para>Emphasis may be added by surrounding text with
	<literal>/.../</literal>.</para>

	<para>Monospaced (or typewriter) text is indicated by
	surrounding it with <literal>[...]</literal>.</para>
      </section>

      <section>
	<title>Code Blocks</title>

	<para>Displayed blocks of code are indicated by surrounding a
	paragraph with <literal>[...]</literal> or by preceding each
	line of a paragraph with <literal>&gt;</literal>.  For
	example:</para>

<programlisting>
-- | This documentation includes two blocks of code:
--
-- [
--     f x = x + x
-- ]
--
-- >  g x = x * 42
</programlisting>
      </section>

      <section>
	<title>Hyperlinked Identifiers</title>

	<para>Referring to a Haskell identifier, whether it be a type,
	class, constructor, or function, is done by surrounding it
	with single quotes:</para>

<programlisting>
-- | This module defines the type 'T'.
</programlisting>

	<para>If there is an entity <literal>T</literal> in scope in
	the current module, then the documentation will hyperlink the
	reference in the text to the definition of
	<literal>T</literal> (if the output format supports
	hyperlinking, of course; in a printed format it might instead
	insert a page reference to the definition).</para>
      </section>

      <section>
	<title>Linking to modules</title>

	<para>Linking to a module is done by surrounding the module
	name with double quotes:</para>

<programlisting>
-- | This is a reference to the "Foo" module.
</programlisting>

      </section>

      <section>
	<title>Itemized and Enumerated lists</title>

	<para>A bulleted item is represented by preceding a paragraph
	with either <quote><literal>*</literal></quote> or
	<quote><literal>-</literal></quote>.  A sequence of bulleted
	paragraphs is rendered as an itemized list in the generated
	documentation, eg.:</para>

<programlisting>
-- | This is a bulleted list:
--
--     * first item
--
--     * second item
</programlisting>

	<para>An enumerated list is similar, except each paragraph
	must be preceded by either
	<quote><literal>(<replaceable>n</replaceable>)</literal></quote>
	or
	<quote><literal><replaceable>n</replaceable>.</literal></quote>
	where <replaceable>n</replaceable> is any integer.  e.g.</para>

<programlisting>
-- | This is an enumerated list:
--
--     (1) first item
--
--     2. second item
</programlisting>
      </section>

      <section>
	<title>URLs</title>

	<para>A URL can be included in a documentation comment by
	surrounding it in angle brackets:
	<literal>&lt;...&gt;</literal>.  If the output format supports
	it, the URL will be turned into a hyperlink when
	rendered.</para>
      </section>
    </section>
  </chapter>
</book>