<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Documentation and Markup</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Haddock User Guide"
HREF="haddock.html"><LINK
REL="PREVIOUS"
TITLE="Invoking Haddock"
HREF="invoking.html"><LINK
REL="NEXT"
TITLE="Documenting parts of a declaration"
HREF="x444.html"></HEAD
><BODY
CLASS="CHAPTER"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Haddock User Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="invoking.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x444.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="MARKUP"
></A
>Chapter 3. Documentation and Markup</H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
>3.1. <A
HREF="markup.html#AEN409"
>Documenting a top-level declaration</A
></DT
><DT
>3.2. <A
HREF="x444.html"
>Documenting parts of a declaration</A
></DT
><DT
>3.3. <A
HREF="x468.html"
>The module description</A
></DT
><DT
>3.4. <A
HREF="x473.html"
>Controlling the documentation structure</A
></DT
><DT
>3.5. <A
HREF="x516.html"
>Named chunks of documentation</A
></DT
><DT
>3.6. <A
HREF="x531.html"
>Hyperlinking and re-exported entities</A
></DT
><DT
>3.7. <A
HREF="module-attributes.html"
>Module Attributes</A
></DT
><DT
>3.8. <A
HREF="x599.html"
>Markup</A
></DT
></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"
><H1
CLASS="SECTION"
><A
NAME="AEN409"
>3.1. Documenting a top-level declaration</A
></H1
><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
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>square :: Int -> Int
square x = x * x</PRE
></TD
></TR
></TABLE
><P
>Then we can document it like this:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>-- |The 'square' function squares an integer.
square :: Int -> Int
square x = x * x</PRE
></TD
></TR
></TABLE
><P
>The <SPAN
CLASS="QUOTE"
>"<TT
CLASS="LITERAL"
>-- |</TT
>"</SPAN
> syntax begins a
documentation annotation, which applies to the
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>following</I
></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
><P
></P
><UL
><LI
><P
>A type signature for a top-level function,</P
></LI
><LI
><P
>A <TT
CLASS="LITERAL"
>data</TT
> declaration,</P
></LI
><LI
><P
>A <TT
CLASS="LITERAL"
>newtype</TT
> declaration,</P
></LI
><LI
><P
>A <TT
CLASS="LITERAL"
>type</TT
> declaration, or</P
></LI
><LI
><P
>A <TT
CLASS="LITERAL"
>class</TT
> declaration.</P
></LI
></UL
><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"
><I
CLASS="EMPHASIS"
>after</I
></SPAN
> the declaration; this is possible in
Haddock too:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>square :: Int -> Int
-- ^The 'square' function squares an integer.
square x = x * x</PRE
></TD
></TR
></TABLE
><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
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>-- |The 'square' function squares an integer.
-- It takes one argument, of type 'Int'.
square :: Int -> Int
square x = x * x</PRE
></TD
></TR
></TABLE
><P
>You can also use Haskell's nested-comment style for
documentation annotations, which is sometimes more convenient
when using multi-line comments:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>{-|
The 'square' function squares an integer.
It takes one argument, of type 'Int'.
-}
square :: Int -> Int
square x = x * x</PRE
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="invoking.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="haddock.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x444.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Invoking Haddock</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
> </TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Documenting parts of a declaration</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
distrib
>
Mandriva
>
10.2
>
i586
>
media
>
contrib
>
by-pkgid
>
ddf0d3a2339db97341c9705cffcc2e11
>
files
>
15
