Difference between revisions of "Documentation Principles"

From ApCoCoAWiki
Line 1: Line 1:
=Structure of your Wiki-page=
+
=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:
 
Write your documentation within the '''command'''-XML-tag. The content of your documentation should be structured as follows:
Line 69: Line 71:
  
 
==Description==
 
==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.
 +
 +
* <code>@param M: Matrix M for which the determinant is computed.</code>
 +
* <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.
  
==Examples==
+
===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 <code>Use ...</code> 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 are not only cover the trivial cases.
 +
* It could also be a support for the user if you comment your function especially by difficult examples.
  
  

Revision as of 15:20, 27 March 2009

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 are not only cover the trivial cases.
  • It could also be a support for the user if you comment your function especially by difficult examples.