2002-4-10Haddock User GuideSimonMarlowsimonmar@microsoft.com2002Simon MarlowThis document describes Haddock, a Haskell documentation
tool.IntroductionThis is Haddock, a tool for automatically generating
documentation from annotated Haskell source code. Haddock was
designed with several goals in mind: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.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.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 IDoc.
In fact, Haddock can understand IDoc-annotated source
code.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.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.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.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.Obtaining HaddockDistributions (source & binary) of Haddock can be obtained
from its web
site.Up-to-date sources can also be obtained from CVS. The
Haddock sources are under fptools/haddock in
the fptools CVS repository, which also
contains GHC, Happy, and several other projects. See Using
The CVS Repository for information on how to access the
CVS repository. Note that you need to check out the
fpconfig module first to get the generic
build system (the fptools directory), and
then check out fptools/haddock to get the
Haddock sources.LicenseThe following license covers this documentation, and the
Haddock source code, except where otherwise indicated.
Copyright 2002, Simon Marlow. All rights reserved.Redistribution and use in source and binary forms, with
or without modification, are permitted provided that the
following conditions are met:Redistributions of source code must retain the above
copyright notice, this list of conditions and the
following disclaimer.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.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.
Invoking HaddockHaddock is invoked from the command line, like so:haddockoptionfileWhere each file 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.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.The modules should not be mutually
recursive, as Haddock don't like swimming in circles.The following options are available:Output documentation in SGML DocBook format. NOTE: at
time of writing this is only partially implemented and
doens't work.Generate documentation in HTML format. Several files
will be generated into the current directory (or the
specified directory if the option is
given), including the following:index.htmlThe top level page of the documentation: lists
the modules available, using indentation to represent
the hierarchy if the modules are hierarchical.haddock.cssThe 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.module.htmlAn HTML page for each
module.doc-index.htmldoc-index-XX.htmlThe index, split into two
(functions/constructors and types/classes, as per
Haskell namespaces) and further split
alphabetically.dir=dirGenerate files into dir
instead of the current directory.URL=URLInclude links to the source files in the generated
documentation, where URL is the
base URL where the source files can be found.title=titleUse title as the page
heading for each page in the documentation.This will
normally be the name of the library being documented.The title should be a plain string (no markup
please!).Reserved for future expansion.=filenameSpecify a stylesheet to use instead of the default one
that comes with Haddock. It should specify certain classes:
see the default stylesheet for details.Documentation and MarkupHaddock 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.Documenting a top-level declarationThe 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:
square :: Int -> Int
square x = x * x
Then we can document it like this:
-- |The 'sqaure' function squares an integer.
square :: Int -> Int
square x = x * x
The -- | syntax begins a
documentation annotation, which applies to the
following declaration in the source file.
Note that the annotation is just a comment in Haskell — it
will be ignored by the Haskell compiler.The declaration following a documentation annotation
should be one of the following:A type signature for a top-level function,A data declaration,A newtype declaration,A type declaration, orA class declaration.If the annotation is followed by a different kind of
declaration, it will probably be ignored by Haddock.Some people like to write their documentation
after the declaration; this is possible in
Haddock too:
square :: Int -> Int
-- ^The 'sqaure' function squares an integer.
square x = x * x
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.Controlling the documentation structureHaddock produces interface documentation that lists only
the entities actually exported by the module. The
documentation for a module will include
all 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.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
order 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 module 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.You can insert headings and sub-headings in the
documentation by including annotations at the appropriate
point in the export list. For example:
module Foo (
-- * Classes
C(..),
-- * Types
-- ** A data type
T,
-- ** A record
R,
-- * Some functions
f, g
) where
Headings are introduced with the syntax
-- *,
-- **
and so on, where the number of *s indicates
the level of the heading (section, sub-section,
sub-sub-section, etc.).If you use section headings, then Haddock will generate
a table of contents at the top of the module documentation for
you.Re-exporting an entire moduleHaskell 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:
module Foo (
module Bar,
module Baz
) where
What will the Haddock-generated documentation for this
module look like? Well, Haddock simply behaves as if the
export list for modules Bar and
Baz had been expanded in-place in the
export list for Foo, including all of
their structure (section headings etc.).More about re-exported entitiesHow hyperlinks are re-targetted when an entity is
re-exported.The module descriptionNamed chunks of documentationMarkup
links to identifiers
links to modules
itemized lists
enumerated lists
emphasis
code blocks
URLs