\section{\texttt{curry-doc}: A Documentation Generator for Curry Programs}

CurryDoc\index{CurryDoc}%
\index{program!documentation}\index{documentation generator}
is a tool in the \CYS distribution that generates
the documentation for a Curry program (i.e., the main module
and all its imported modules) in HTML format.
The generated HTML pages contain information about
all data types and functions exported by a module as well
as links between the different entities.
Furthermore, some information about the definitional status
of functions (like rigid, flexible, external, complete, or
overlapping definitions) are provided and combined with
documentation comments provided by the programmer.

\subsection{Installation}

The current implementation of CurryDoc is 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}

A \emph{documentation comment}%
\index{documentation comment}\index{comment!documentation}
starts at the beginning of a line
with \ccode{--- }\pindex{---} (also in literate programs!).
All documentation comments immediately before a
definition of a datatype or (top-level) function are kept together.\footnote{%
The documentation tool recognizes this association from the first identifier
in a program line. If one wants to add a documentation comment
to the definition of a function which is an infix operator,
the first line of the operator definition should be a type definition,
otherwise the documentation comment is not recognized.}
The documentation comments for the complete module occur before
the first ``module'' or ``import'' line in the module.
The comments can also contain several special tags. These tags
must be the first thing on its line (in the documentation comment)
and continues until the next tag is encountered or until the
end of the comment. The following tags are recognized:
\begin{description}
\item[\code{@author}]\pindex{"@author} \emph{comment}\\
Specifies the author of a module (only reasonable in module comments).
\item[\code{@version}]\pindex{"@version} \emph{comment}\\
Specifies the version of a module (only reasonable in module comments).
\item[\code{@cons}]\pindex{"@cons} \emph{id} \emph{comment}\\
A comment for the constructor \emph{id} of a datatype
(only reasonable in datatype comments).
\item[\code{@param}]\pindex{"@param} \emph{id} \emph{comment}\\
A comment for function parameter \emph{id}
(only reasonable in function comments).
Due to pattern matching, this need not be the name of a parameter
given in the declaration of the function but all parameters
for this functions must be commented in left-to-right order
(if they are commented at all).
\item[\code{@return}]\pindex{"@return} \emph{comment}\\
A comment for the return value of a function
(only reasonable in function comments).
\end{description}
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 parameter \ccode{--nomarkdown}.

The comments can also contain markups in HTML format
so that special characters like \ccode{<}
must be quoted (e.g., \ccode{\&lt;}).
However, header tags like \code{<h1>} should not be used
since the structuring is generated by CurryDoc.
In addition to Markdown or HTML markups,
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}
--- This is an
--- example module.
--- @author Michael Hanus
--- @version 0.1

module Example where

--- The function `conc` concatenates two lists.
--- @param xs - the first list
--- @param ys - the second list
--- @return a list containing all elements of `xs` and `ys`
conc []     ys = ys
conc (x:xs) ys = x : conc xs ys
-- this comment will not 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.
--- @param xs - the given input list
--- @return last element of the input list
last xs | conc ys [x] =:= xs  = x   where x,ys free

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

\subsection{Generating Documentation}

To generate the documentation, 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}

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