You have to comment your own code in a particular way to allow Cod2Doc to create a documentation. Cod2Doc will interpret the commented line in the code to create the documentation. Only comment lines correctly placed are taken into account. Cod2Doc is able to document:

• the description of the code
• include files
• constant variables
• global variables and arrays
• types
• functions.

Local variables are not documented.
See the first section for a description about formatting a normal text in description.




Text in description (description of header, variables, types, functions, inline documentation) are formatted similarly to the source from which they are extracted. Carriage returns are assumed in the same way.

To have a continuous text in html, the special tag ";;" should be used instead of ";". The line is considered then to be the continuation of the last one (this gives a much better result in html).
The same rule apply with the ;+ prolongation tag: you have to replace ;+ by ;;+ to continue on the same line.

You can also add a blank line by inserting an empty comment line between two lines of text.

Notice that for inline documentation, you have also the possibility to add one or several empty lines (non commented) between two lines.

Here is an example:


It's possible to insert any html tag in the normal text. You can thus change font, colour, insert complex tables,... Remember also that you can change the default behaviour of html tags (like <b> or <em>) in the style file.

Warning: there are some special characters that needs to be escaped in the comments of your code. To display the following characters properly, you will have in some cases to replace them by their html equivalent:

• & = &amp;
• < = &lt;
• > = &gt;
• " = &quot;

Cod2Doc, like in html, does not take into account more than one space at a time. If you want to include additional spaces between words, then you will have to use the html code &nbsp;.

Notice that you shouldn't need to insert a lot of html tags! Cod2Doc does a lot for you: it can easily insert links, email addresses, images, tables, pre-format text,... See further in the documentation for more details.

Here is an example of the use of html tags:





The first comments of the file are considered as a code description and will be included in the documentation. Moreover, the first line will be used as a summary of the code description (in the index file index.html). Notice that if empty lines are put on the top of the source file before the comments containing the description, these comments won't be taken into account by Cod2Doc.





Cod2Doc documents constant and global variables as well as arrays. It considers that the documentation comes on the same line as the variable declaration. For constant variables, their constant value will be documented. For global variables, in in case it has a default value, it's also specified in the documentation. By default, only the comment on the same line of the variable will be taken into account. To add more lines of description, add one or several ;+ lines immediately after the declaration of the variable.

Notice that Cod2Doc could also document several variables declared on the same line (like "Global myVar1, myVar2").





There is two possibilities to write a description for a type. The documentation can be before or after the Type line at your convenience. However the priority is for code above the Type line. Several lines are possible for the documentation (there should be no blank line between the description and the Type line). The Field lines are documented similarly to variables: the comment should be on the same line as the Field declaration. More description can be added using the special comment ;+. Default values of Field are also reported.

Notice that Cod2Doc could also document several fields declared on the same line (like "Field myVar1, myVar2").


Notice also that this structure would also be correct (comments after the Type line):





Identically to types, there is also two possibilities to write a description for a function. The documentation can be before or after the Function line at your convenience. However the priority is for code above the Function line. Several lines are possible for the documentation (there should be no blank line between the description and the Function line).

The arguments of the function are also documented, and optional arguments are put into [] with their default values. To document argument, two possibilities are offered. A special comment has to be inserted in the function description:

• ; nameOfVariable = Description of the variable nameOfVariable
  where nameOfVariable is the name of the concerned argument
• ; argn = Description of the argument n
  where n is the index of the concerned argument in the argument list of the function (this method has the advantage to be quick to write, but has some drawbacks in case of argument re-ordering or in the readability of the code)

The return value is documented also in the function description. Cod2Doc searches for a line of this type:

• ; return = Description of the return value

If the function has no return value, Cod2Doc determines it and then specifies the return value as "None".

More description can be added to the variable or return description using the special comment ;+. Of course, one of the variables (or all) or the return value may not appear in the function description.


Notice also that this structure would also be correct (comments after the Function line and use of the keyword argn):





Final remark on colours of the different categories
You can easily set different colours for every category (global variable, functions, ...) for a better visual differentiation. For that, you will need to modify the style files written in cascading style sheets.