dependencies: 
|
[Dependency "abstract-curry" [[VGte "4.0.0",VLt "5.0.0"]],Dependency "ansi-terminal" [[VGte "3.0.0",VLt "4.0.0"]],Dependency "base" [[VGte "3.3.0",VLt "4.0.0"]],Dependency "cass-analysis" [[VGte "4.0.0",VLt "5.0.0"]],Dependency "cass" [[VGte "4.1.0",VLt "5.0.0"]],Dependency "currypath" [[VGte "3.0.0",VLt "4.0.0"]],Dependency "flatcurry" [[VGte "4.0.0",VLt "5.0.0"]],Dependency "frontend-exec" [[VGte "3.3.0",VLt "4.0.0"]],Dependency "html2" [[VGte "3.5.2",VLt "4.0.0"]],Dependency "markdown" [[VGte "3.3.0",VLt "4.0.0"]],Dependency "wl-pprint" [[VGte "3.0.0",VLt "4.0.0"]],Dependency "xml" [[VGte "3.0.0",VLt "4.0.0"]],Dependency "curry-ast" [[VGte "3.1.0",VLt "4.0.0"]],Dependency "json" [[VGte "3.0.0",VLt "4.0.0"]],Dependency "curry-resources" [[VGte "1.0.0",VLt "2.0.0"]],Dependency "string-trie" [[VGte "0.0.2",VLt "1.0.0"]]]
|
|
documentation:
|
currydoc: A Documentation Generator for Curry Programs
======================================================
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.
Short Description
-----------------
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: comment
Specifies a a short description of a module.
Category: comment
Specifies the category of a module, such as `general` or `data structures`.
Author: comment
Specifies the author of a module.
Version: comment
Specifies the version of a module.
The comment of a documented entity can be any string in
[Markdown](http://en.wikipedia.org/wiki/Markdown) syntax.
The currently supported set of elements is described in
[Curry package markdown](https://github.com/curry-packages/markdown/blob/master/docs/markdown-syntax.md).
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 tree
If this program is contained in the file `Example.curry`,
one can generate the documentation by executing the command
currydoc Example
This 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 Example
where `docdir` is the directory for the documentation files.
For a comprehensive example, refer to the [Guide](/examples/Guide.curry).
Further Information
-------------------
The bachelor's thesis [An Automated Documentation Generation Tool for Curry Programs](https://www.michaelhanus.de/lehre/abschlussarbeiten/bsc/Prott.pdf)
(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](https://www.curry-lang.org/pakcs/) and
[KiCS2](https://www.curry-lang.org/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
|