Difference between revisions of "Documentation Principles"
From ApCoCoAWiki
(Documenting principles for documenting functions within the Wiki.) |
S schuster (talk | contribs) |
||
| Line 1: | Line 1: | ||
| − | =Documenting a package | + | =Documenting a Package in the Wiki pages= |
| + | This pages describes some common principles to keep in mind when you document your package in the Wiki pages and | ||
| + | is meant to give the documentation a uniform look and feel. | ||
| + | |||
| + | |||
By documenting your package mind the following: | By documenting your package mind the following: | ||
| − | * use for the name of | + | * use for the name of your <code>.cpkg</code> file only '''lower case letters''' (if necessary separated by "_"), |
| − | * your description should contain which '''alias''' you have chosen for your package, | + | * if possible, use for the name of the package (wich is 'not' the global alias) the same name as your <code>.cpkg</code> package has, |
| − | * how to create an alias: | + | * your description should contain which '''global alias''' you have chosen for your package, |
| − | ** the alias has to follow the CoCoA coding conventions, | + | * how to create an global alias: |
| − | ** | + | ** the alias has to follow the CoCoA coding conventions, i.e., has to start with a capital letter, |
| + | ** it should be as short as possible and concise. | ||
| + | For example, assume that in file ''matrices.cpkg'' you provide a package ''matrices'' that specifies a function ''Det'' | ||
| + | that, given either a matrix or a list of lists of ring elements, computes the determinant of a matrix. | ||
| + | A reasonable global alias for your package then would be ''Mat''. | ||
| − | =Documenting a | + | =Documenting a Function= |
==Structure of your Wiki-page== | ==Structure of your Wiki-page== | ||
| Line 48: | Line 56: | ||
| − | == | + | ==<title>== |
| − | The title of your command is the concatenation of the global alias, which you have defined for your CoCoA-package, and the | + | The title of your command is the concatenation of the global alias, which you have defined for your CoCoA-package, a dot and the name of your function, e.g. |
<code> | <code> | ||
<title>Mat.Det</title> | <title>Mat.Det</title> | ||
| Line 55: | Line 63: | ||
for a function called ''Det'' within a package ''matrix'' with global alias ''Mat''. | 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 | + | 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 full stop'''. |
<code> | <code> | ||
| Line 62: | Line 70: | ||
</code> | </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. | + | 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> | <code> | ||
| Line 80: | Line 88: | ||
</code> | </code> | ||
| − | == | + | ==<description>== |
Describe and explain here in detail what your function does. First of all itemize all your parameters and the return value and describe as short as possible which role they play within your function, e.g. | Describe and explain here in detail what your function does. First of all itemize all your parameters and the return value and describe as short as possible which role they play within your function, e.g. | ||
| − | * <code>@param M | + | * <code>@param M Matrix M for which the determinant is computed.</code> |
| − | * <code>@return | + | * <code>@return The determinant of matrix M.</code> |
Please use by your description the strings "@param" and "@return" to mark the parameters and return values. | Please use by your description the strings "@param" and "@return" to mark the parameters and return values. | ||
| − | === | + | ===<example>=== |
| − | Please note the examples '''have to be written within the description-tag'''! Write as many examples as necessary to understand the complete functionality of your function. | + | Please note, the examples '''have to be written within the description-tag'''! Write as many examples as necessary to understand the complete functionality of your function. |
* If you write more than one example use a new example-tag for every example! | * If you write more than one example use a new example-tag for every example! | ||
| − | * The examples should be complete, i.e. they have to begin with <code>Use ...</code> and end with the result. So it is possible for the user to copy the whole example ( | + | * The examples should be complete, i.e. they have to begin with <code>Use ...</code> and end with the result. So it is possible for the user to copy the whole example (only having to ommit the the expected ApCoCoA response), paste it into (Ap)CoCoA and execute it. |
* Please give intelligent examples, i.e. examples which do not only cover the trivial cases. | * Please give intelligent examples, i.e. examples which do not only cover the trivial cases. | ||
| − | * It could also be a support for the user if you comment your example especially by difficult examples. | + | * It could also be a support for the user if you comment your example especially by difficult examples. If you do so, comment every line that is not executable with a ''--'', see second item above. |
| + | <code> | ||
| + | <example> | ||
| + | -- Here goes your first example for the determinant. | ||
| + | -- TBD!! | ||
| + | Use ... | ||
| + | Det.Mat([[1,0][0,1]]); | ||
| + | --------------------- | ||
| + | |||
| + | </example> | ||
| + | <example> | ||
| + | -- Here is, within seperate example tags, your second example | ||
| + | -- demonstrating how matrices are supplied | ||
| + | Use ... | ||
| + | M := ... | ||
| + | Det.Mat(M); | ||
| + | </example> | ||
| + | </code> | ||
| − | == | + | ==<types>== |
| − | Declare here all data types | + | Declare here all data types that the formal parameters in the signature of your functions have. For example the function ''Det'' is a function for types ''MAT'' and ''LIST'', so ''Det'' has to be added to the group of all functions for type ''MAT'' and to the group of all functions for type ''LIST''. Therefore declare all these types within the types-tag, e.g. |
<code> | <code> | ||
| Line 107: | Line 132: | ||
</code> | </code> | ||
| − | == | + | ==<see>== |
You can set references to other functions which are related to this function. You only have to declare the '''title''' of these function within the see-tag, e.g. | You can set references to other functions which are related to this function. You only have to declare the '''title''' of these function within the see-tag, e.g. | ||
| Line 116: | Line 141: | ||
Please be careful with your references! Use only reasonable references, but set as many as possible! | Please be careful with your references! Use only reasonable references, but set as many as possible! | ||
| − | == | + | ==<key>== |
The set of keywords is the set of expressions in which a search term is searched by the <code>? ...</code> or <code>Man</code>-command in (Ap)CoCoA! Therefore be careful with your keywords! | The set of keywords is the set of expressions in which a search term is searched by the <code>? ...</code> or <code>Man</code>-command in (Ap)CoCoA! Therefore be careful with your keywords! | ||
| Line 134: | Line 159: | ||
</code> | </code> | ||
| − | == | + | ==<wiki-category>== |
The wiki-category is always constructed in the same way, i.e. the concatenation of '''Package_''' and the name of the package which contains your function, e.g. | The wiki-category is always constructed in the same way, i.e. the concatenation of '''Package_''' and the name of the package which contains your function, e.g. | ||
Revision as of 09:31, 1 April 2009
Documenting a Package in the Wiki pages
This pages describes some common principles to keep in mind when you document your package in the Wiki pages and is meant to give the documentation a uniform look and feel.
By documenting your package mind the following:
- use for the name of your
.cpkgfile only lower case letters (if necessary separated by "_"), - if possible, use for the name of the package (wich is 'not' the global alias) the same name as your
.cpkgpackage has, - your description should contain which global alias you have chosen for your package,
- how to create an global alias:
- the alias has to follow the CoCoA coding conventions, i.e., has to start with a capital letter,
- it should be as short as possible and concise.
For example, assume that in file matrices.cpkg you provide a package matrices that specifies a function Det that, given either a matrix or a list of lists of ring elements, computes the determinant of a matrix. A reasonable global alias for your package then would be Mat.
Documenting a Function
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
...
...
==
== The title of your command is the concatenation of the global alias, which you have defined for your CoCoA-package, a dot and the name of your function, e.g. <code> <title>Mat.Det
for a function called Det within a package matrix with global alias Mat.
==
== 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 full stop.
<short_description>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. <code> <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
<description>
Describe and explain here in detail what your function does. First of all itemize all your parameters and the return value and describe as short as possible which role they play within your function, e.g.
@param M Matrix M for which the determinant is computed.@return The determinant of matrix M.
Please use by your description the strings "@param" and "@return" to mark the parameters and return values.
===
Example
=== Please note, the examples '''have to be written within the description-tag'''! Write as many examples as necessary to understand the complete functionality of your function. * If you write more than one example use a new example-tag for every example! * The examples should be complete, i.e. they have to begin with <code>Use ...</code> and end with the result. So it is possible for the user to copy the whole example (only having to ommit the the expected ApCoCoA response), paste it into (Ap)CoCoA and execute it. * Please give intelligent examples, i.e. examples which do not only cover the trivial cases. * It could also be a support for the user if you comment your example especially by difficult examples. If you do so, comment every line that is not executable with a ''--'', see second item above. <code> <example> -- Here goes your first example for the determinant. -- TBD!! Use ... Det.Mat([[1,0][0,1]]); ---------------------
Example
-- Here is, within seperate example tags, your second example -- demonstrating how matrices are supplied Use ... M := ... Det.Mat(M);
==
==
[[== You can set references to other functions which are related to this function. You only have to declare the title of these function within the see-tag, e.g.
<see>LinBox.Det]]
Please be careful with your references! Use only reasonable references, but set as many as possible!
==
==
Further remarks
- Use as little Tex-code as possible.
