<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 3. Documentation and Markup</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="index.html" title="Haddock User Guide"><link rel="prev" href="invoking.html" title="Chapter 2. Invoking Haddock"><link rel="next" href="ch03s02.html" title="3.2. Documenting parts of a declaration"></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">Chapter 3. Documentation and Markup</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="invoking.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch03s02.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="markup"></a>Chapter 3. Documentation and Markup</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="markup.html#id2547498">3.1. Documenting a top-level declaration</a></span></dt><dt><span class="section"><a href="ch03s02.html">3.2. Documenting parts of a declaration</a></span></dt><dd><dl><dt><span class="section"><a href="ch03s02.html#id2547679">3.2.1. Class methods</a></span></dt><dt><span class="section"><a href="ch03s02.html#id2547714">3.2.2. Constructors and record fields</a></span></dt><dt><span class="section"><a href="ch03s02.html#id2547766">3.2.3. Function arguments</a></span></dt></dl></dd><dt><span class="section"><a href="ch03s03.html">3.3. The module description</a></span></dt><dt><span class="section"><a href="ch03s04.html">3.4. Controlling the documentation structure</a></span></dt><dd><dl><dt><span class="section"><a href="ch03s04.html#id2547905">3.4.1. Re-exporting an entire module</a></span></dt><dt><span class="section"><a href="ch03s04.html#id2548009">3.4.2. Omitting the export list</a></span></dt></dl></dd><dt><span class="section"><a href="ch03s05.html">3.5. Named chunks of documentation</a></span></dt><dt><span class="section"><a href="hyperlinking.html">3.6. Hyperlinking and re-exported entities</a></span></dt><dt><span class="section"><a href="module-attributes.html">3.7. Module Attributes</a></span></dt><dt><span class="section"><a href="ch03s08.html">3.8. Markup</a></span></dt><dd><dl><dt><span class="section"><a href="ch03s08.html#id2548512">3.8.1. Paragraphs</a></span></dt><dt><span class="section"><a href="ch03s08.html#id2548523">3.8.2. Special characters</a></span></dt><dt><span class="section"><a href="ch03s08.html#id2548600">3.8.3. Character references</a></span></dt><dt><span class="section"><a href="ch03s08.html#id2548666">3.8.4. Code Blocks</a></span></dt><dt><span class="section"><a href="ch03s08.html#id2548718">3.8.5. Hyperlinked Identifiers</a></span></dt><dt><span class="section"><a href="ch03s08.html#id2548841">3.8.6. Emphasis and Monospaced text</a></span></dt><dt><span class="section"><a href="ch03s08.html#id2548881">3.8.7. Linking to modules</a></span></dt><dt><span class="section"><a href="ch03s08.html#id2548900">3.8.8. Itemized and Enumerated lists</a></span></dt><dt><span class="section"><a href="ch03s08.html#id2548965">3.8.9. Definition lists</a></span></dt><dt><span class="section"><a href="ch03s08.html#id2549054">3.8.10. URLs</a></span></dt><dt><span class="section"><a href="ch03s08.html#id2549072">3.8.11. Anchors</a></span></dt></dl></dd></dl></div><p>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.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2547498"></a>3.1. Documenting a top-level declaration</h2></div></div></div><p>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:</p><pre class="programlisting">
square :: Int -> Int
square x = x * x
</pre><p>Then we can document it like this:</p><pre class="programlisting">
-- |The 'square' function squares an integer.
square :: Int -> Int
square x = x * x
</pre><p>The “<span class="quote"><code class="literal">-- |</code></span>” syntax begins a
documentation annotation, which applies to the
<span class="emphasis"><em>following</em></span> declaration in the source file.
Note that the annotation is just a comment in Haskell — it
will be ignored by the Haskell compiler.</p><p>The declaration following a documentation annotation
should be one of the following:</p><div class="itemizedlist"><ul type="disc"><li><p>A type signature for a top-level function,</p></li><li><p>A <code class="literal">data</code> declaration,</p></li><li><p>A <code class="literal">newtype</code> declaration,</p></li><li><p>A <code class="literal">type</code> declaration, or</p></li><li><p>A <code class="literal">class</code> declaration.</p></li></ul></div><p>If the annotation is followed by a different kind of
declaration, it will probably be ignored by Haddock.</p><p>Some people like to write their documentation
<span class="emphasis"><em>after</em></span> the declaration; this is possible in
Haddock too:</p><pre class="programlisting">
square :: Int -> Int
-- ^The 'square' function squares an integer.
square x = x * x
</pre><p>Note that Haddock doesn't contain a Haskell type system
— 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.</p><p>Documentation annotations may span several lines; the
annotation continues until the first non-comment line in the
source file. For example:</p><pre class="programlisting">
-- |The 'square' function squares an integer.
-- It takes one argument, of type 'Int'.
square :: Int -> Int
square x = x * x
</pre><p>You can also use Haskell's nested-comment style for
documentation annotations, which is sometimes more convenient
when using multi-line comments:</p><pre class="programlisting">
{-|
The 'square' function squares an integer.
It takes one argument, of type 'Int'.
-}
square :: Int -> Int
square x = x * x
</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="invoking.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch03s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Invoking Haddock </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3.2. Documenting parts of a declaration</td></tr></table></div></body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
87b4172b3b1930a874e4a9620c298a79
>
files
>
27
