Chapter 1. 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 a 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 obscure 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, LaTeX,
and Hoogle backends, and it is structured in such a way that adding new
backends is straightforward.

1.1. Obtaining Haddock

Distributions (source & binary) of Haddock can be obtained
from its web
site.

Up-to-date sources can also be obtained from our public
darcs repository. The Haddock sources are at
http://code.haskell.org/haddock. See
darcs.net for more
information on the darcs version control utility.