Documentation Principles
Documenting a package
By documenting your package mind the following:
- use for the name of the package only lower case letters (if necessary separated by "_"),
- your description should contain which alias you have chosen for your package,
- how to create an alias:
- the alias has to follow the CoCoA coding conventions,
- they should be as short as possible and concise
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
...
...
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
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.
Examples
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
Use ...and end with the result. So it is possible for the user to copy the whole example (without the result), 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.
Types
Declare here all data types which your function modify, i.e. your function "does" something with a special type of input. 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.
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.
Please be careful with your references! Use only reasonable references, but set as many as possible!
Keywords
The set of keywords is the set of expressions in which a search term is searched by the ? ... or Man-command in (Ap)CoCoA! Therefore be careful with your keywords!
- The following words have to be keywords:
- the title of the function,
- the concatenation of the alias of the package and the title of the function,
- the concatenation of the package name and the title of the function.
- Do not use any names of persons, e.g. your own!
- You are allowed to declare other reasonable keywords.
Example:
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.
Further remarks
- Use as little Tex-code as possible.
