<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 1. Introduction</title><link rel="stylesheet" href="fptools.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="Haddock User Guide"><link rel="up" href="index.html" title="Haddock User Guide"><link rel="prev" href="index.html" title="Haddock User Guide"><link rel="next" href="license.html" title="1.2. License"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 1. Introduction</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="license.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="introduction"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="introduction.html#obtaining">1.1. Obtaining Haddock</a></span></dt><dt><span class="section"><a href="license.html">1.2. License</a></span></dt><dt><span class="section"><a href="ch01s03.html">1.3. Acknowledgements</a></span></dt></dl></div><p>This is Haddock, a tool for automatically generating
documentation from annotated Haskell source code. Haddock was
designed with several goals in mind:</p><div class="itemizedlist"><ul type="disc"><li><p>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.</p></li><li><p>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.</p></li><li><p>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 <a class="ulink" href="http://www.cse.unsw.edu.au/~chak/haskell/idoc/" target="_top">IDoc</a>.
In fact, Haddock can understand IDoc-annotated source
code.</p></li><li><p>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.</p><p>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.</p></li><li><p>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.</p></li><li><p>We might want documentation in multiple formats - online
and printed, for example. Haddock comes with HTML, DocBook
and Hoogle backends, and it is structured in such a way that adding new
back-ends is straightforward.</p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="obtaining"></a>1.1. Obtaining Haddock</h2></div></div></div><p>Distributions (source & binary) of Haddock can be obtained
from its <a class="ulink" href="http://www.haskell.org/haddock/" target="_top">web
site</a>.</p><p>Up-to-date sources can also be obtained from our public
darcs repository. The Haddock sources are at
<code class="literal">http://code.haskell.org/haddock</code>. See
<a class="ulink" href="http://www.darcs.net/" target="_top">darcs.net</a> for more
information on the darcs version control utility.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="license.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Haddock User Guide </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 1.2. License</td></tr></table></div></body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
87b4172b3b1930a874e4a9620c298a79
>
files
>
23
