Difference between revisions of "Documentation Principles"
(New page: =Structure of your Wiki-page= Write your documentation within the '''command'''-XML-tag. This content should be structured as follows: <code> <title>...</title> <short_description>......) |
|||
| Line 1: | Line 1: | ||
=Structure of your Wiki-page= | =Structure of your Wiki-page= | ||
| − | Write your documentation within the '''command'''-XML-tag. | + | Write your documentation within the '''command'''-XML-tag. The content of your documentation should be structured as follows: |
<code> | <code> | ||
| Line 36: | Line 36: | ||
| − | =Title= | + | ==Title== |
| + | The title of your command is the concatenation of the global alias, which you have defined for your CoCoA-package, and the title of your function, e.g. | ||
| + | <code> | ||
| + | <title>Mat.Det</title> | ||
| + | </code> | ||
| + | for a function called ''Det'' within a package ''matrix'' with global alias ''Mat''. | ||
| + | |||
| + | ==Short description== | ||
| + | Describe shortly the basic functionality of your function. Thereby treat your short description as a real sentence, i.e. your short description has to '''begin with a capital letter''' and has to '''end with a dot'''. | ||
| + | |||
| + | <code> | ||
| + | <short_description>Computes the determinant of a matrix.</short_description> | ||
| + | </code> | ||
| + | |||
| + | ==Syntax== | ||
| + | The syntax of your function has to be complete, i.e. including the types of your parameters and the type of your return value if this is possible! If it is possible to call your function with different types, then itemize the complete syntax for every possibility, e.g. | ||
| + | |||
| + | <code> | ||
| + | <syntax> | ||
| + | Mat.Det(M:MAT) | ||
| + | Mat.Det(M:LIST) | ||
| + | </syntax> | ||
| + | </code> | ||
| + | In this example it is possible to call the function ''Det'' either with the matrix ''M'' or with a list (of lists) which defines the matrix ''M''. Here it is not possible to determine the type of the return value, because it depends on the types of the entries of matrix ''M''. Suppose that ''M'' only has rational entries. Then the syntax should look like this: | ||
| + | |||
| + | <code> | ||
| + | <syntax> | ||
| + | Mat.Det(M:MAT):RAT | ||
| + | Mat.Det(M:LIST):RAT | ||
| + | </syntax> | ||
| + | </code> | ||
| + | |||
| + | ==Description== | ||
| + | |||
| + | |||
| + | ==Examples== | ||
Revision as of 14:38, 27 March 2009
Structure of your Wiki-page
Write your documentation within the command-XML-tag. The content of your documentation should be structured as follows:
...
...
Syntax
...
Description
...
Example
...
...
Example
...
...
Title
The title of your command is the concatenation of the global alias, which you have defined for your CoCoA-package, and the title of your function, e.g.
Mat.Det
for a function called Det within a package matrix with global alias Mat.
Short description
Describe shortly the basic functionality of your function. Thereby treat your short description as a real sentence, i.e. your short description has to begin with a capital letter and has to end with a dot.
Computes the determinant of a matrix.
Syntax
The syntax of your function has to be complete, i.e. including the types of your parameters and the type of your return value if this is possible! If it is possible to call your function with different types, then itemize the complete syntax for every possibility, e.g.
Syntax
Mat.Det(M:MAT)
Mat.Det(M:LIST)
In this example it is possible to call the function Det either with the matrix M or with a list (of lists) which defines the matrix M. Here it is not possible to determine the type of the return value, because it depends on the types of the entries of matrix M. Suppose that M only has rational entries. Then the syntax should look like this:
Syntax
Mat.Det(M:MAT):RAT
Mat.Det(M:LIST):RAT
