path: root/doc/haddock.sgml

<!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>
  </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 'sqaure' 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 'sqaure' 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>
	<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>

	<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>More about re-exported entities</title> 
	  
	  <para>How hyperlinks are re-targetted when an entity is
	  re-exported.</para>

	</section>
      </section>

    </section>

    <section>
      <title>The module description</title>
      <para></para>
    </section>
    
    <section>
      <title>Named chunks of documentation</title>
      <para></para>
    </section>
    
    <section>
      <title>Markup</title>
      <para>
	links to identifiers
	links to modules
	itemized lists
	enumerated lists
	emphasis
	code blocks
	URLs</para>
    </section>
  </chapter>
</book>