This package contains a tool to generate the documentation for a Curry program (i.e., the main module and all its imported modules) in HTML (or LaTeX) 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.
A documentation comment starts at the beginning of a
line starting with -- |. All documentation comments
immediately before a definition of a datatype or (top-level) function
are kept together. The documentation comments for the complete module
occur before the first module or import line
in the module.
The comments of a module definition can also contain several special
tags. Such a tag of form key: value must be the first thing
on its line (in the documentation comment) and spans all characters of
all subsequent comment lines until the end of the comment, or until a
comment line with indentation less than the associated colon
(:) character occurs.
The following tags are recognized:
Description: commentSpecifies a a short description of a module.
Category: commentSpecifies the category of a module, such as general or
data structures.
Author: commentSpecifies the author of a module.
Version: commentSpecifies the version of a module.
The comment of a documented entity can be any string in Markdown syntax. The
currently supported set of elements is described in Curry
package markdown. The comments can also contain markups in HTML
format so that special characters like < must be quoted.
In addition to Markdown or HTML markups, one can also mark
references to names of operations or data types in
Curry programs. These are translated into links inside the generated
HTML documentation (if they are unqualified) or into links in other
module documentations if they are qualified with a module name. Such
references have to be enclosed in single quotes (e.g.,
'sum').
The following example shows a Curry program with some documentation comments:
{- | Description: Example module.
Category : Example
Author : Michael Hanus
Version : 0.1
This is an example module
with features XY.
-}
module Example where
-- | The function `conc` concatenates two lists.
-- It is also predefined as 'Prelude.++'.
conc :: [a] -- ^ the first list
-> [a] -- ^ the second list
-> [a] -- ^ 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.
last :: [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 comment **will** be included in the documentation
-- | This data type defines _polymorphic_ trees.
data Tree a = Leaf a -- ^ a leaf of the tree
| Node [Tree a] -- ^ an inner node of the treeIf this program is contained in the file Example.curry,
one can generate the documentation by executing the command
currydoc ExampleThis command creates the directory DOC_Example (if it
does not exist) and puts all HTML documentation files for the main
program module Example and all its imported modules in this
directory together with a main index file index.html.
Additionally, a file containing the CDoc representation of the module is
created. If one prefers another directory for the documentation files,
one can also execute the command
currydoc docdir Examplewhere docdir is the directory for the documentation
files.
For a comprehensive example, refer to the Guide.
The bachelor's thesis An Automated Documentation Generation Tool for Curry Programs (in German, by Kai-Oliver Prott, September 2018) describes the implementation details of the new CurryDoc overhaul that takes inspiration from Haddock's documentation style.
More details on CurryDoc are described in the user manuals of the Curry systems PAKCS and KiCS2. There is also a paper describing the basic ideas of CurryDoc:
M. Hanus: CurryDoc : A Documentation Tool for Declarative Programs. Proc. of the 11th International Workshop on Functional and (Constraint) Logic Programming (WFLP 2002), Research Report UDMI/18/2002/RR, Università degli Studi di Udine, pp. 225-228, 2002