The guidelines for code documentation currently cover:
General comments documenting the source code
Structured comments and licence information at the head of each application source file
Structured comments and licence information at the head of each library source file
Structured comments describing each function
Structured comments describing each datatype (C structure definitions)
Be aware that the guidelines may change with time as progress is made in code refactoring to improve the quality, consistency and documentation of the EMBOSS C source code.
A particular style (see below) is recommended for general C-style comments within the code. Such comments are an informal but valuable way of documenting the code. For the main body of documentation, structured comments are used.
The approach taken is based broadly on JavaDoc. Embedded documentation is marked up with text tags which begin with @ followed by a code identifying the item, then the free documentation text. No text should be given before the @ although any leading asterisks (*) or spaces are stripped before parsing. For example:
** @source |
Text following a tag on a line must not contain HTML markup (this would complicate parsers that convert the text to XML for use in generating the online documentation). The text after the tag continues until a new tag is reached or a token (*/) indicating the end of a C-style comment is found.