% Haddock-DH.tex
\begin{hcarentry}[updated]{Haddock}
\label{haddock}
\report{David Waern}%11/10
\status{experimental, maintained}
\makeheader

Haddock is a widely used documentation-generation tool for Haskell
library code.  Haddock generates documentation by parsing and typechecking
Haskell source code directly and including documentation supplied by the
programmer in the form of specially-formatted comments in the source code
itself.  Haddock has direct support in Cabal~\cref{cabal}, and is used to
generate the documentation for the hierarchical libraries that come with GHC,
Hugs, and nhc98
(\url{http://www.haskell.org/ghc/docs/latest/html/libraries}) as well as
the documentation on Hackage.

The latest release is version 2.8.1, released September 3 2010.

\Separate
Recent changes:
\begin{itemize}
\item HTML backend completely rewritten to generate semantically rich XHTML
      using the xhtml package.
\item New default CSS based on the color scheme chosen for the new Haskell
      wiki, with a pull-out tab for the synopsis.
\item Theme engine based on CSS files. Themes can be switched from the
      header menu.
\item Markup support for executable examples/unit-tests.
\item Addition of a LaTeX backend.
\item Additions and changes to the Haddock API.
\item Various smaller new features and bug fixes.
\end{itemize}

\FuturePlans
\begin{itemize}
\item Although Haddock understands many GHC language extensions, we would like it to
understand all of them. Currently there are some constructs you cannot comment,
like GADTs and associated type synonyms.
 
\item Error messages is an area with room for improvement. We would like Haddock
to include accurate line numbers in markup syntax errors.

\item On the HTML rendering side we want to make more use of Javascript in order to make
the viewing experience better. The frames-mode could be improved this way, for
example.

\item Finally, the long term plan is to split Haddock into one program that creates
data from sources, and separate backend programs that use that data via the
Haddock API. This will scale better, not requiring adding new backends to Haddock
for every tool that needs its own format.
\end{itemize}

\FurtherReading
\begin{compactitem}
\item Haddock's homepage:
\url{http://www.haskell.org/haddock/}

\item Haddock's developer Wiki and Trac:
\url{http://trac.haskell.org/haddock}

\item Haddock's mailing list:
\url{haddock@@projects.haskell.org}
\end{compactitem}
\end{hcarentry}