Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
tools:currydoc [2013-02-26 09:49] mh |
tools:currydoc [2020-12-22 23:18] mh |
||
|---|---|---|---|
| Line 14: | Line 14: | ||
| documentation comments provided by the programmer. | documentation comments provided by the programmer. | ||
| - | ==== Short Summary ==== | + | |
| + | |||
| + | |||
| + | ==== Short Description ==== | ||
| A **documentation comment** starts at the beginning of a line | A **documentation comment** starts at the beginning of a line | ||
| Line 27: | Line 30: | ||
| end of the comment. The following tags are recognized: | end of the comment. The following tags are recognized: | ||
| - | * ''@author comment'': Specifies the author of a module (only reasonable in module comments). | + | @author comment |
| - | * ''@version comment'': Specifies the version of a module (only reasonable in module comments). | + | |
| - | * ''@cons id comment'': A comment for the constructor ''id'' of a datatype (only reasonable in datatype comments). | + | Specifies the author of a module (only reasonable in module comments). |
| - | * ''@param id comment'': A comment for function parameter ''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. | + | |
| - | * ''@return comment'': A comment for the return value of a function (only reasonable in function comments). | + | @version comment |
| + | |||
| + | Specifies the version of a module (only reasonable in module comments). | ||
| + | |||
| + | @cons id comment | ||
| + | |||
| + | A comment for the constructor ''id'' of a datatype (only reasonable in datatype comments). | ||
| + | |||
| + | @param id comment | ||
| + | |||
| + | A comment for function parameter ''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. | ||
| + | |||
| + | @return comment | ||
| + | |||
| + | A comment for the return value of a function (only reasonable in function comments). | ||
| + | |||
| + | The comment of a documented entity can be any string in | ||
| + | [[http://en.wikipedia.org/wiki/Markdown | Markdown ]] syntax. | ||
| + | The currently supported set of elements is described in | ||
| + | [[http://www.informatik.uni-kiel.de/~pakcs/markdown_syntax.html | this page]]. | ||
| + | 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. | ||
| + | |||
| + | The following example shows a Curry program with some | ||
| + | documentation comments: | ||
| + | |||
| + | Example.curry: | ||
| + | |||
| + | --- This is an | ||
| + | --- example module. | ||
| + | --- @author Michael Hanus | ||
| + | --- @version 0.1 | ||
| + | |||
| + | module Example where | ||
| + | |||
| + | --- The function `conc` concatenates two lists. | ||
| + | --- It is also predefined as 'Prelude.++'. | ||
| + | --- @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] | ||
| + | |||
| + | To generate the documentation, execute 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''. | ||
| + | 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. | ||
| ==== Further Information ==== | ==== Further Information ==== | ||
