2002-4-10
Haddock User Guide
Simon
Marlow
simonmar@microsoft.com
2002
Simon Marlow
This document describes Haddock, a Haskell documentation
tool.
Introduction
This 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. 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 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 Haddock
Distributions (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.
License
The 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 Haddock
Documentation and Markup