Documentation Principles

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 .cpkg file 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 .cpkg package 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!

==

==

Formatting your text

There are a few XML-tags for formatting the text. Please, do not use any Wiki formatting styles!

• itemization:

• your text
  

• bold text:

<em>your text</em>

• true type text:

<tt>your text</tt>

• paragraphs:

<par><par/>
new paragraph

Please note: Paragraphs within the Wiki will not be taken over to html! Therefore always use the par-tag to structure your text!

Further remarks

• Use as little Tex-code as possible.
• Do not use any pictures!