Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
tools:currydoc [2013-02-26 09:49] mh |
tools:currydoc [2013-02-26 11:14] 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 33: | Line 35: | ||
| * ''@return comment'': A comment for the return value of a function (only reasonable in function comments). | * ''@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 which are translated into links inside | ||
| + | the generated HTML documentation. 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. | ||
| + | --- @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 ==== | ||
