\section{CurryDoc: A Documentation Generator for Curry Programs}

CurryDoc\index{CurryDoc}%
\index{program!documentation}\index{documentation generator}
is a tool to generate
the documentation for a Curry program (i.e., the main module
and all its imported modules) in HTML format.
It can also be used with the Curry Package Manager CPM
(see below) to generate the documentation of a Curry package.
The generated HTML pages contain information about
all data types, type classes and operations exported by a module as well
as links between the different entities.
Furthermore, some information about the definitional status
of operations (like rigid, flexible, external, complete, or
overlapping definitions) are provided and combined with
documentation comments provided by the programmer.

\subsection{Installation}

The implementation of CurryDoc is contained in a package
managed by the Curry Package Manager CPM.
Thus, to install the newest version of CurryDoc, use the following commands:
%
\begin{curry}
> cypm update
> cypm install currydoc
\end{curry}
%
This downloads the newest package, compiles it, and places
the executable \code{curry-doc} into the directory \code{\$HOME/.cpm/bin}.
Hence it is recommended to add this directory to your path
in order to execute CurryDoc as described below.

\subsection{Documentation Comments}

The documentation syntax follows Haddock
(see \url{https://www.haskell.org/haddock/doc/html/index.html}).%
\footnote{Note that older versions of CurryDoc ($< 5.0.0$)
use a slightly different syntax which is still supported but
should not be used.}

A \emph{documentation comment}%
\index{documentation comment}\index{comment!documentation}
starts with \ccode{-{}- | } or \ccode{-{}- \textasciicircum }
(also in literate programs!).%
\footnote{\ccode{-{}-{}- } can be used instead of
          \ccode{-{}- | } for backwards compatibility}
The former style can be used to write document comments preceding a declaration
and the latter for comments following a declaration.
Nested comments are also supported with  \ccode{\{- | }
or \ccode{\{- \textasciicircum}
Other comments are also considered as documentation comments, if they are
on a line directly below another documentation comment.

The documentation comments for the complete module occur before
the first ``module'' or ``import'' line in the module.
The module comments can also contain several special tags. These tags
must be the first thing on its line (in the documentation comment)
and continues until a line has at most the same degree of indentation or
until the end of the comment.
No tag must occur in the module comments, but any
occurring tag as to be in the specified order.
The following tags are recognized:
\begin{description}
\item[\code{Description:}]\pindex{"Description:} \emph{comment}\\
Specifies a short description of a module
\item[\code{Category:}]\pindex{"Category:} \emph{comment}\\
Specifies the category of a module
\item[\code{Author:}]\pindex{"Author:} \emph{comment}\\
Specifies the author of a module
\item[\code{Version:}]\pindex{"Version:} \emph{comment}\\
Specifies the version of a module
\end{description}
All text following the tags can be used for a longer module description.

The ordering of the final documentation can be controlled via the export list
in the module header.
The user can insert section headings via comments of the form \ccode{-{}- *} or
\ccode{\{- * }. The number of \ccode{*} controls if it is a subsection,
subsubsection, etc.

The comment of a documented entity can be any string in
\emph{Markdown syntax}\index{markdown}\footnote{%
\url{http://en.wikipedia.org/wiki/Markdown}}.
The currently supported set of elements is described in the
Curry package \code{markdown}.\footnote{%
\url{https://cpm.curry-lang.org/pkgs/markdown.html}}
For instance, it can contain Markdown annotations for
emphasizing elements (e.g., \verb!_verb_!),
strong elements (e.g., \verb!**important**!),
code elements (e.g., \verb!`3+4`!), code blocks (lines prefixed by four blanks),
unordered lists (lines prefixed by  ``\verb! * !''),
ordered lists (lines prefixed by blanks followed by a digit and a dot),
quotations (lines prefixed by ``\verb!> !''),
and web links of the form \ccode{<http://\ldots>}
or \ccode{[link text](http://\ldots)}.
If the Markdown syntax should not be used, one could run CurryDoc
with the option \ccode{-{}-nomarkdown}.

The comments cannot contain markups in HTML format anymore,
due to the possibility of XSS-Attacks.
In addition to Markdown,
one can also mark \emph{references to names} of operations or data types
in Curry programs which are translated into links inside
the generated HTML documentation. Such references have to be
enclosed in single quotes. For instance, the text
\verb!'conc'! refers to the Curry operation \code{conc}
inside the current module whereas the text
\verb!'Prelude.reverse'! refers to the operation \code{reverse}
of the module \code{Prelude}.
If one wants to write single quotes without this specific
meaning, one can escape them with a backslash:
\begin{curry}
-- | This is a comment without a \'reference\'.
\end{curry}
To simplify the writing of documentation comments,
such escaping is only necessary for single words,
i.e., if the text inside quotes has not the syntax of
an identifier, the escaping can be omitted, as in
\begin{curry}
-- | This isn't a reference.
\end{curry}
%
The following example text shows a Curry program with some
documentation comments:
\begin{curry}
{- |
     Description: A simple example for CurryDoc
     Author     : Michael Hanus
     Version    : 0.1

     This is an
     example module.
-}
module Example (
  -- * Tree type
  Tree(..),
  -- * Operations on lists
  last,
  -- ** Operations repeated from the prelude
  conc
 ) where

-- | The function `conc` concatenates two lists.
--   It is identical to the function 'Prelude.++'.
conc :: [a] -- ^ The first list
     -> [a] -- ^ The second list
     -> [a] -- ^ A list containing all elements of the parameters
conc (x:xs) ys = x : conc xs ys
conc []     ys = ys
-- ^ This comment will also be included in the documentation

-- | The function `last` computes the last element of a given list.
--   It is based on the operation 'conc' to concatenate two lists.
last :: Data a
     => [a] -- ^ The given input list
     -> a   -- ^ The last element of the input list
last xs | conc ys [x] =:= xs  = x   where x,ys free

-- | This data type defines _polymorphic_ trees.
data Tree a = Leaf a -- ^ A leaf of the tree
            | Node [Tree a] -- ^ An inner node of the tree
\end{curry}


\subsection{Generating Documentation for Curry Modules}

To generate the documentation of the module \code{Example} shown above,
execute the command
\pindex{curry-doc}\pindex{doc}
\begin{curry}
curry-doc Example
\end{curry}
This command creates the directory \code{DOC\_Example} (if it does not exist)
and puts all HTML documentation files for the main program module
\code{Example}
and all its imported modules in this directory together with
a main index file \code{index.html}.
If one prefers another directory for the documentation files,
one can also execute the command
\begin{curry}
curry-doc docdir Example
\end{curry}
where \code{docdir} is the directory for the documentation files.

In order to generate the common documentation for large collections
of Curry modules (e.g., the libraries contained in the \CYS distribution),
one can call \code{curry-doc} with the following options:
\begin{description}
\item[\code{curry-doc --noindexhtml docdir Mod}] ~\\
\pindex{noindex}
This command generates the documentation for module \code{Mod}
in the directory \code{docdir} without the index pages (i.e., main index page
and index pages for all functions and constructors defined in \code{Mod}
and its imported modules).
\item[\code{curry-doc --onlyindexhtml docdir Mod1 Mod2 \ldots Mod$n$}] ~\\
\pindex{onlyindex}
This command generates only the index pages (i.e., a main index page
and index pages for all functions and constructors defined in the modules
\code{Mod1}, \code{Mod2},\ldots,\code{Mod$n$} and their imported modules)
in the directory \code{docdir}.
\end{description}

\subsection{Generating Documentation for Curry Packages}

CurryDoc is also used by the Curry Package Manager CPM
to generate the documentation of a Curry package.
Inside a Curry package, one can execute the command
%
\begin{curry}
> cypm doc
\end{curry}
%
to generate the documentation of all modules exported by this package.
A detailed description of this command and its options
can be found in the manual of CPM.


%%% Local Variables:
%%% mode: pdflatex
%%% TeX-master: "main"
%%% End: