<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>3.4. Controlling the documentation structure</title><link rel="stylesheet" href="fptools.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="Haddock User Guide"><link rel="up" href="markup.html" title="Chapter 3. Documentation and Markup"><link rel="prev" href="ch03s03.html" title="3.3. The module description"><link rel="next" href="ch03s05.html" title="3.5. Named chunks of documentation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.4. Controlling the documentation structure</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch03s03.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Documentation and Markup</th><td width="20%" align="right"> <a accesskey="n" href="ch03s05.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2547808"></a>3.4. Controlling the documentation structure</h2></div></div></div><p>Haddock produces interface documentation that lists only
the entities actually exported by the module. The documentation
for a module will include <span class="emphasis"><em>all</em></span> 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.</p><p>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
<span class="emphasis"><em>order</em></span> 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 <span class="emphasis"><em>module</em></span> 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.</p><p>You can insert headings and sub-headings in the
documentation by including annotations at the appropriate point
in the export list. For example:</p><pre class="programlisting">
module Foo (
-- * Classes
C(..),
-- * Types
-- ** A data type
T,
-- ** A record
R,
-- * Some functions
f, g
) where
</pre><p>Headings are introduced with the syntax
“<span class="quote"><code class="literal">-- *</code></span>”,
“<span class="quote"><code class="literal">-- **</code></span>” and so on, where
the number of <code class="literal">*</code>s indicates the level of the
heading (section, sub-section, sub-sub-section, etc.).</p><p>If you use section headings, then Haddock will generate a
table of contents at the top of the module documentation for
you.</p><p>The alternative style of placing the commas at the
beginning of each line is also supported. eg.:</p><pre class="programlisting">
module Foo (
-- * Classes
, C(..)
-- * Types
-- ** A data type
, T
-- ** A record
, R
-- * Some functions
, f
, g
) where
</pre><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2547905"></a>3.4.1. Re-exporting an entire module</h3></div></div></div><p>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:</p><pre class="programlisting">
module A (
module B,
module C
) where
</pre><p>What will the Haddock-generated documentation for this
module look like? Well, it depends on how the modules
<code class="literal">B</code> and <code class="literal">C</code> are imported.
If they are imported wholly and without any
<code class="literal">hiding</code> qualifiers, then the documentation
will just contain a cross-reference to the documentation for
<code class="literal">B</code> and <code class="literal">C</code>. However, if
the modules are not <span class="emphasis"><em>completely</em></span>
re-exported, for example:</p><pre class="programlisting">
module A (
module B,
module C
) where
import B hiding (f)
import C (a, b)
</pre><p>then Haddock behaves as if the set of entities
re-exported from <code class="literal">B</code> and <code class="literal">C</code>
had been listed explicitly in the export
list<sup>[<a name="id2547983" href="#ftn.id2547983" class="footnote">2</a>]</sup>.</p><p>The exception to this rule is when the re-exported
module is declared with the <code class="literal">hide</code> attribute
(<a class="xref" href="module-attributes.html" title="3.7. Module Attributes">Section 3.7, “Module Attributes”</a>), in which case the module
is never cross-referenced; the contents are always expanded in
place in the re-exporting module.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2548009"></a>3.4.2. Omitting the export list</h3></div></div></div><p>If there is no export list in the module, how does
Haddock generate documentation? Well, when the export list is
omitted, e.g.:</p><pre class="programlisting">module Foo where</pre><p>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).</p></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.id2547983" href="#id2547983" class="para">2</a>] </sup>NOTE: this is not fully implemented at the
time of writing (version 0.2). At the moment, Haddock always
inserts a cross-reference.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch03s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="markup.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch03s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.3. The module description </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3.5. Named chunks of documentation</td></tr></table></div></body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
87b4172b3b1930a874e4a9620c298a79
>
files
>
17
