diff options
Diffstat (limited to 'doc/haddock.xml')
| -rw-r--r-- | doc/haddock.xml | 1437 |
1 files changed, 1437 insertions, 0 deletions
diff --git a/doc/haddock.xml b/doc/haddock.xml new file mode 100644 index 00000000..b0592eb9 --- /dev/null +++ b/doc/haddock.xml @@ -0,0 +1,1437 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<book id="haddock"> + <bookinfo> + <date>2004-08-02</date> + <title>Haddock User Guide</title> + <author> + <firstname>Simon</firstname> + <surname>Marlow</surname> + </author> + <address><email>simonmar@microsoft.com</email></address> + <copyright> + <year>2004</year> + <holder>Simon Marlow</holder> + </copyright> + <abstract> + <para>This document describes Haddock version 0.6, 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/html/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, packaging, and moral support: Simon Peyton + Jones, Mark Shields, Manuel Chakravarty, Ross Patterson, Brett + Letner, Sven Panne, Hal Daume, George Russell, Oliver Braun, + Ashley Yakeley, Malcolm Wallace, Krasimir Angelov, 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. Only plain Haskell source + files are accepted (but see <xref linkend="cpp"/> for instructions + on how to pre-process source files for feeding to Haddock).</para> + + <para>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> + <indexterm><primary><option>-o</option></primary></indexterm> + <option>-o</option> <replaceable>dir</replaceable> + </term> + <term> + <indexterm><primary><option>--odir</option></primary></indexterm> + <option>--odir</option>=<replaceable>dir</replaceable> + </term> + <listitem> + <para>Generate files into <replaceable>dir</replaceable> + instead of the current directory.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-i</option></primary></indexterm> + <option>-i</option> <replaceable>path</replaceable>,<replaceable>file</replaceable> + </term> + <term> + <indexterm><primary><option>--read-interface</option></primary></indexterm> + <option>--read-interface</option>=<replaceable>path</replaceable>,<replaceable>file</replaceable> + </term> + <listitem> + <para>Read the interface file in + <replaceable>file</replaceable>, which must have been + produced by running Haddock with the + <option>--dump-interface</option> option. The interface + describes a set of modules whose HTML documentation is + located in <replaceable>path</replaceable> (which may be a + relative pathname). The <replaceable>path</replaceable> is + optional, and defaults to <quote>.</quote>.</para> + + <para>This option allows Haddock to produce separate sets of + documentation with hyperlinks between them. The + <replaceable>path</replaceable> is used to direct hyperlinks + to point to the right files; so make sure you don't move the + HTML files later or these links will break. Using a + relative <replaceable>path</replaceable> means that a + documentation subtree can still be moved around without + breaking links.</para> + + <para>Multiple <option>--read-interface</option> options may + be given.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-D</option></primary></indexterm> + <option>-D</option> <replaceable>file</replaceable> + </term> + <term> + <indexterm><primary><option>--dump-interface</option></primary></indexterm> + <option>--dump-interface</option>=<replaceable>file</replaceable> + </term> + <listitem> + <para>Produce an <firstterm>interface + file</firstterm><footnote><para>Haddock interface files are + not the same as Haskell interface files, I just couldn't + think of a better name.</para> </footnote> + in the file <replaceable>file</replaceable>. An interface + file contains information Haddock needs to produce more + documentation that refers to the modules currently being + processed - see the <option>--read-interface</option> option + for more details. The interface file is in a binary format; + don't try to read it.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-l</option></primary></indexterm> + <option>-l</option> <replaceable>dir</replaceable> + </term> + <term> + <indexterm><primary><option>--lib</option></primary></indexterm> + <option>--lib</option>=<replaceable>dir</replaceable> + </term> + <listitem> + <para>Use auxiliary files in <replaceable>dir</replaceable>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-S</option></primary></indexterm> + <option>-S</option> + </term> + <term> + <indexterm><primary><option>--docbook</option></primary></indexterm> + <option>--docbook</option> + </term> + <listitem> + <para>Reserved for future use (output documentation in SGML DocBook + format).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-h</option></primary></indexterm> + <option>-h</option> + </term> + <term> + <indexterm><primary><option>--html</option></primary></indexterm> + <option>--html</option> + </term> + <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>haddock.js</filename></term> + <listitem> + <para>A small piece of JavaScript for collapsing sections + of the generated HTML.</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> + <indexterm><primary><option>-m</option></primary></indexterm> + <option>-m</option> + </term> + <term> + <indexterm><primary><option>--html-help</option></primary></indexterm> + <option>--html-help</option> + </term> + <listitem> + <para>(In HTML mode only) Produce extra contents and index + files for given HTML Help system. Currently supported Help + systems are Microsoft HTML Help 1.3 and 2.0 and GNOME DevHelp.</para> + + <para>Using the Microsoft HTML Help system provides two + advantages over plain HTML: the help viewer gives you a nice + hierarchical folding contents pane on the left, and the + documentation files are compressed and therefore much + smaller (roughly a factor of 10). The disadvantage is that + the help can't be viewed over the web.</para> + + <para>In order to create a compiled Microsoft help file, you + also need the Microsoft HTML Help compiler, which is + available free from + <ulink url="http://www.microsoft.com/">http://www.microsoft.com/</ulink> + (search for <quote>HTML Help compiler</quote>).</para> + + <para>Viewers</para> + <variablelist> + <varlistentry> + <term>Microsoft HTML Help Viewer</term> + <listitem><para>Distributed with Microsoft Windows</para></listitem> + </varlistentry> + <varlistentry> + <term><ulink url="http://xchm.sourceforge.net">xCHM</ulink></term> + <listitem><para>a CHM viewer for UNIX (Linux, *BSD, Solaris), written by Razvan Cojocaru</para></listitem> + </varlistentry> + <varlistentry> + <term><ulink url="http://www.jouledata.com/MacProducts.html">JouleData Solutions' CHM Viewer</ulink></term> + <listitem><para>a comercial 100% native Cocoa .chm file viewer for the Mac OS X platform</para></listitem> + </varlistentry> + <varlistentry> + <term><ulink url="http://gnochm.sourceforge.net">GnoCHM</ulink></term> + <listitem><para>a CHM file viewer. It is designed to integrate nicely with Gnome.</para></listitem> + </varlistentry> + </variablelist> + + <para>The GNOME DevHelp also provides help viewer which looks like + MSHelp viewer but the documentation files aren't compressed. + The documentation can be viewed with any HTML browser but + DevHelp gives you a nice hierarchical folding contents and + keyword index panes on the left. The DevHelp expects to see + *.devhelp file in the folder where the documentation is placed. + The file contains all required information + to build the contents and index panes. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-s</option></primary></indexterm> + <option>-s</option> <replaceable>URL</replaceable> + </term> + <term> + <indexterm><primary><option>--source</option></primary></indexterm> + <option>--source</option>=<replaceable>URL</replaceable> + </term> + <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> + <indexterm><primary><option>-c</option></primary></indexterm> + <option>-c</option> <replaceable>file</replaceable> + </term> + <term> + <indexterm><primary><option>--css</option></primary></indexterm> + <option>--css</option>=<replaceable>file</replaceable> + </term> + <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> + + <varlistentry> + <term> + <indexterm><primary><option>-p</option></primary></indexterm> + <option>-p</option> <replaceable>file</replaceable> + </term> + <term> + <indexterm><primary><option>--prologue</option></primary></indexterm> + <option>--prologue</option>=<replaceable>file</replaceable> + </term> + <listitem> + <para>Specify a file containing documentation which is + placed on the main contents page under the heading + “Description”. The file is parsed as a normal + Haddock doc comment (but the comment markers are not + required).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-t</option></primary></indexterm> + <option>-t</option> <replaceable>title</replaceable> + </term> + <term> + <indexterm><primary><option>--title</option></primary></indexterm> + <option>--title</option>=<replaceable>title</replaceable> + </term> + <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> + <indexterm><primary><option>-n</option></primary></indexterm> + <option>-n</option> + </term> + <term> + <indexterm><primary><option>--no-implicit-prelude</option></primary></indexterm> + <option>--no-implicit-prelude</option> + </term> + <listitem> + <para>Don't automatically import <literal>Prelude</literal> + in every module. Used when producing documentation for the + <literal>Prelude</literal> itself.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-d</option></primary></indexterm> + <option>-d</option> + </term> + <term> + <indexterm><primary><option>--debug</option></primary></indexterm> + <option>--debug</option> + </term> + <listitem> + <para>Produce extra debugging output.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-?</option></primary></indexterm> + <option>-?</option> + </term> + <term> + <indexterm><primary><option>--help</option></primary></indexterm> + <option>--help</option> + </term> + <listitem> + <para>Display help and exit.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-v</option></primary></indexterm> + <option>-v</option> + </term> + <term> + <indexterm><primary><option>--verbose</option></primary></indexterm> + <option>--verbose</option> + </term> + <listitem> + <para>Increase verbosity. Currently this will cause Haddock + to emit some extra warnings, in particular about modules + which were imported but it had no information about (this is + often quite normal; for example when there is no information + about the <literal>Prelude</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-V</option></primary></indexterm> + <option>-V</option> + </term> + <term> + <indexterm><primary><option>--version</option></primary></indexterm> + <option>--version</option> + </term> + <listitem> + <para>Output version information and exit.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>--use-index</option></primary></indexterm> + <option>--use-index=<replaceable>URL</replaceable></option> + </term> + <listitem> + <para>When generating HTML, do not generate an index. + Instead, redirect the Index link on each page to + <replaceable>URL</replaceable>. This option is intended for + use in conjuction with <option>--gen-index</option> for + generating a separate index covering multiple + libraries.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>--gen-index</option></primary></indexterm> + <option>--gen-index</option> + </term> + <listitem> + <para>Generate an HTML index containing entries pulled from + all the specified interfaces (interfaces are specified using + <option>-i</option> or <option>--read-interface</option>). + This is used to generate a single index for multiple sets of + Haddock documentstation.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>-k</option></primary></indexterm> + <option>-k</option> <replaceable>P</replaceable> + </term> + <term> + <indexterm><primary><option>--package</option></primary></indexterm> + <option>--package=</option><replaceable>P</replaceable> + </term> + <listitem> + <para>Set the package name for these modules to + <replaceable>P</replaceable>. In a combined index generated + with <option>--gen-index</option>, the package name for each + module is shown in the right-hand column.</para> + </listitem> + </varlistentry> + </variablelist> + + <section id="cpp"> + <title>Using literate or pre-processed source</title> + + <para>Haddock only accepts plain, non-literate, Haskell source. + This means that if you program in Literate Haskell, or you need + to use the C pre-processor in your Haskell source, then you need + to pre-process the files before feeding them to Haddock. This + is easily accomplished using GHC; for example, suppose we have a + Literate Haskell source file <filename>Foo.lhs</filename>, on + which we also need to run the C pre-processor:</para> + +<screen> +$ ghc -cpp -E -optP-P -D__HADDOCK__ Foo.lhs -o Foo.hs +$ haddock -h Foo.hs ... +</screen> + + <para>The <option>-E</option> option to GHC says "stop after + pre-processing", the <option>-cpp</option> option turns on the C + pre-processor, the <option>-optP-P</option> option tells the C + pre-processor not to leave any extra dropping behind (see the + description of the <option>-P</option> option in the gcc manual + for details), and the <option>-D__HADDOCK__</option> option + defines the symbol <literal>__HADDOCK__</literal> when + pre-processing (this is sometimes handy if you need to any + pre-processing conditionals in your source which depend on + whether the source is going to be fed to Haddock).</para> + </section> + + </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 — 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 + — 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> + + <para>Documentation annotations may span several lines; the + annotation continues until the first non-comment line in the + source file. For example:</para> + +<programlisting> +-- |The 'square' function squares an integer. +-- It takes one argument, of type 'Int'. +square :: Int -> Int +square x = x * x +</programlisting> + + <para>You can also use Haskell's nested-comment style for + documentation annotations, which is sometimes more convenient + when using multi-line comments:</para> + +<programlisting> +{-| + The 'square' function squares an integer. + It takes one argument, of type 'Int'. +-} +square :: Int -> Int +square x = x * x +</programlisting> + + </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>-- |</literal></quote> or + <quote><literal>-- ^</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> + </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> + + <para>Alternative layout styles are generally accepted by + Haddock - for example doc comments can appear before or after + the comma in separated lists such as the list of record fields + above.</para> + </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> + </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>-- *</literal></quote>, + <quote><literal>-- **</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> + + <para>The alternative style of placing the commas at the + beginning of each line is also supported. eg.:</para> + +<programlisting> +module Foo ( + -- * Classes + , C(..) + -- * Types + -- ** A data type + , T + -- ** A record + , R + -- * Some functions + , f + , g + ) where +</programlisting> + + <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 A ( + module B, + module C + ) where +</programlisting> + + <para>What will the Haddock-generated documentation for this + module look like? Well, it depends on how the modules + <literal>B</literal> and <literal>C</literal> are imported. + If they are imported wholly and without any + <literal>hiding</literal> qualifiers, then the documentation + will just contain a cross-reference to the documentation for + <literal>B</literal> and <literal>C</literal>. However, if + the modules are not <emphasis>completely</emphasis> + re-exported, for example:</para> + +<programlisting> +module A ( + module B, + module C + ) where + +import B hiding (f) +import C (a, b) +</programlisting> + + <para>then Haddock behaves as if the set of entities + re-exported from <literal>B</literal> and <literal>C</literal> + had been listed explicitly in the export + list<footnote><para>NOTE: this is not fully implemented at the + time of writing (version 0.2). At the moment, Haddock always + inserts a cross-reference.</para> + </footnote>.</para> + + <para>The exception to this rule is when the re-exported + module is declared with the <literal>hide</literal> attribute + (<xref linkend="module-attributes"/>), in which case the module + is never cross-referenced; the contents are always expanded in + place in the re-exporting module.</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>-- $</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>-- $</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 id="module-attributes"> + <title>Module Attributes</title> + + <para>Certain attributes may be specified for each module which + affects the way that Haddock generates documentation for that + module. Attributes are specified in a comma-separated list in a + <literal>-- #</literal> (or + <literal>{- # ... -}</literal>) comment at the + top of the module, either before or after the module + description. For example:</para> + +<programlisting> +-- #hide, prune, ignore-exports +-- |Module description +module A where +... +</programlisting> + + <para>The following attributes are currently understood by + Haddock:</para> + + <variablelist> + <varlistentry> + <term> + <indexterm><primary><literal>hide</literal></primary></indexterm> + <literal>hide</literal> + </term> + <listitem> + <para>Omit this module from the generated documentation, + but nevertheless propagate definitions and documentation + from within this module to modules that re-export those + definitions.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><literal>hide</literal></primary></indexterm> + <literal>prune</literal> + </term> + <listitem> + <para>Omit definitions that have no documentation + annotations from the generated documentation.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><literal>hide</literal></primary></indexterm> + <literal>ignore-exports</literal> + </term> + <listitem> + <para>Ignore the export list. Generate documentation as + if the module had no export list - i.e. all the top-level + declarations are exported, and section headings may be + given in the body of the module.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Markup</title> + + <para>Haddock understands certain textual cues inside + documentation annotations that tell it how to render the + documentation. The cues (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>@</literal>, + <literal><</literal>. To insert a literal occurrence of + one of these special characters, precede it with a backslash + (<literal>\</literal>).</para> + + <para>Additionally, the character <literal>></literal> has + a special meaning at the beginning of a line, and 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>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>></literal> (we often + call these “bird tracks”). For + example:</para> + +<programlisting> +-- | This documentation includes two blocks of code: +-- +-- @ +-- f x = x + x +-- @ +-- +-- > g x = x * 42 +</programlisting> + + <para>There is an important difference between the two forms + of code block: in the bird-track form, the text to the right + of the ‘<literal>></literal>’ is interpreted + literally, whereas the <literal>@...@</literal> form + interprets markup as normal inside the code block.</para> + </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> + + <para>It is also possible to refer to entities that are not in + scope in the current module, by giving the full qualified name + of the entity:</para> + +<programlisting> +-- | The identifier 'M.T' is not in scope +</programlisting> + + <para>If <literal>M.T</literal> is not otherwise in scope, + then Haddock will simply emit a link pointing to the entity + <literal>T</literal> exported from module <literal>M</literal> + (without checking to see whether either <literal>M</literal> + or <literal>M.T</literal> exist).</para> + + <para>To make life easier for documentation writers, a quoted + identifier is only interpreted as such if the quotes surround + a lexically valid Haskell identifier. This means, for + example, that it normally isn't necessary to escape the single + quote when used as an apostrophe:</para> + +<programlisting> +-- | I don't have to escape my apostrophes; great, isn't it? +</programlisting> + + <para>For compatibility with other systems, the following + alternative form of markup is accepted<footnote><para> + We chose not to use this as the primary markup for + identifiers because strictly speaking the <literal>`</literal> + character should not be used as a left quote, it is a grave accent.</para> + </footnote>: <literal>`T'</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>. Other markup is + valid inside a monospaced span: for example + <literal>@'f' a b@</literal> will hyperlink the + identifier <literal>f</literal> inside the code fragment.</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>Definition lists</title> + + <para>Definition lists are written as follows:</para> + +<programlisting> +-- | This is a definition list: +-- +-- [@foo@] The description of @foo@. +-- +-- [@bar@] The description of @bar@. +</programlisting> + + <para>To produce output something like this:</para> + + <variablelist> + <varlistentry> + <term><literal>foo</literal></term> + <listitem> + <para>The description of <literal>foo</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>bar</literal></term> + <listitem> + <para>The description of <literal>bar</literal>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Each paragraph should be preceded by the + “definition term” enclosed in square brackets. + The square bracket characters have no special meaning outside + the beginning of a definition paragraph. That is, if a + paragraph begins with a <literal>[</literal> character, then + it is assumed to be a definition paragraph, and the next + <literal>]</literal> character found will close the definition + term. Other markup operators may be used freely within the + definition term.</para> + </section> + + <section> + <title>URLs</title> + + <para>A URL can be included in a documentation comment by + surrounding it in angle brackets: + <literal><...></literal>. If the output format supports + it, the URL will be turned into a hyperlink when + rendered.</para> + </section> + + <section> + <title>Anchors</title> + + <para>Sometimes it is useful to be able to link to a point in + the documentation which doesn't correspond to a particular + entity. For that purpose, we allow <emphasis>anchors</emphasis> to be + included in a documentation comment. The syntax is + <literal>#<replaceable>label</replaceable>#</literal>, where + <replaceable>label</replaceable> is the name of the anchor. + An anchor is invisible in the generated documentation.</para> + + <para>To link to an anchor from elsewhere, use the syntax + <literal>"<replaceable>module</replaceable>#<replaceable>label</replaceable>"</literal> + where <replaceable>module</replaceable> is the module name + containing the anchor, and <replaceable>label</replaceable> is + the anchor label. The module does not have to be local, it + can be imported via an interface.</para> + </section> + </section> + </chapter> +</book> |