EMBOSS code documentation standards
Contents
- Comments before each function
- Function documentation tag descriptions
- Parameter codes
- Comments before each data type
- Datatype documentation tag descriptions
- Comments at the head of each library source file
- Comments at the head of each application source file
We considered a number of code documentation methods, including JavaDoc and de novo methods used in several other projects at the Sanger Centre.
None quite fits what we need, so we are picking the best bits from each format and defining our own standard.
Like JavaDoc, embedded documentation is enclosed in specially structured doc comments. Any leading "*" or spaces are stripped before parsing. A doc comment may contain HTML markup, but should avoid header markup such as <H1>, <H2> or <HR> which will be generated automatically by a parser.
The special tags begin with "@" and must be the first text on a line. The text after the tag continues until a new tag is reached or the end of comment is found.
Source code will include structured comments in the following format:
Comments before each function
/* @func functionname **********************************************
**
** Free text description
** on as many lines as needed
**
** @param [code] argname [type] ....description....
** @return [code] [type] ....description....
** @cre ....description....
** @ure ....description....
** @exception exceptname ....description....
** @see name
** @@
** ....comment text excluded from documentation....
**
*******************************************************************/
type functionname (type firstarg, type secondarg) {
|
Function documentation tag descriptions
The available tags are based on the set defined in JavaDoc.
| Element | Description |
|---|---|
| @func | Start of structured comment. Gives the function name. Followed by any number of lines of free text with markup. Use @funcstatic if the function is not publicly visible. |
| @funcstatic | Same as @func, but for static (internal) functions |
| @param | Used once for each parameter. Type is as defined in the function. See below for the use of "code". |
| @cre | Description of checked runtime error(s) for a parameter |
| @ure | Description of unchecked runtime error(s) for a parameter |
| @return | Description of the return value for successful execution. The code can indicate properties such as ownership or be just "[]" |
| @error | Description of the return value(s) for errors condition(s). Can be used more than once if appropriate. |
| @exception | Exception(s) thrown by this function.Can be used more than once if appropriate. |
| @see | Named tag in the same source file (name) or elsewhere (module.name) to be converted into a hyperlink. |
| @@ | Effectively ends the doc comment. Any following text is ignored by the HTML conversion parser. |
Parameter codes
The code consists of lower case letter(s) for the basic type and upper case modifiers.
| Code | Mnemonic | Description |
|---|---|---|
| r | Read | Value is used but not changed |
| w | Write | Value is ignored. A new value is always returned unless specific conditions are given for non-return. |
| u | Update | Value is used, and a new value is returned. |
| d | Delete | Value is a pointer to memory to be freed. The pointer will be set to NULL. |
| f | PointerToFunction | Value is a pointer to a function. The description should indicate the function type. |
| v | Vararg | Value is a variable-length argument list, in some form. |
| Code | Mnemonic | Description |
|---|---|---|
| C | Checked | The value is checked. See the @cre tag for checked runtime errors |
| E | Empty | An empty value will be accepted, for example a string of length zero |
| N | Null | A NULL value will be accepted |
| P | Pointer | Use this if a pointer is written or updated rather than just the data it points to |
Comments before each data type
/* @data datatype **********************************************
**
** Free text description
** on as many lines as needed
**
** @alias structname
** @alias objectname
**
** @new ....description....
** @delete ....description....
** @assign ....description....
**
** @attr attrname [type] ...description...
**
** @@
** ....comment text excluded from documentation....
**
*******************************************************************/
typedef struct structname
{
type firstattr;
type secondattr;
...
} objectname
#define datatype objectname*
|
Datatype documentation tag descriptions
| Element | Description |
|---|---|
| @data | Start of structured comment. Gives the data structure most used name. Followed by any number of lines of free text with markup. Use @datastatic if the data structure is not publicly visible. |
| @alias | Another name used for the datatype. Common usage is to use the pointer name (AjPStr etc.) as the main name, and the object name (AjOStr etc.) and the structure name (AjSStr etc.) as aliases. These are used to markup references through aliases in the source code. |
| @iterator | Name of the iterator type associated with this datatype (e.g. AjIStr) |
| @other | Name of any other type associated with this datatype |
| @new | Constructor. Gives the function name, followed by a copy of the function description. |
| @delete | Destructor. Gives the function name, followed by a copy of the function description. |
| @assign | Assignment (overwrites the value). Gives the function name, followed by a copy of the function description. |
| @modify | Modifier (updates the value). Gives the function name, followed by a copy of the function description. |
| @cast | Casts the value into something else as the return
type or another parameter. Gives the function name, followed by a copy of the function description. |
| @use | Uses the value but does not modify it or return any part. Gives the function name, followed by a copy of the function description. |
| @input | Input function (reads an input source and populates the datatype). Gives the function name, followed by a copy of the function description. |
| @output | Output function (writes the values to an output file). Gives the function name, followed by a copy of the function description. |
| @iterate | Iteration function (iterates over value or array of values). Gives the function name, followed by a copy of the function description. |
| @attr | Attribute name, type and description. Attributes are defined in the same order as they appear in the struct. The name and type must match the true definition. |
| @cc | Comment inserted between groups of attributes. No comments are allowed in the struct itself (to provide clean parsing) so comments are inserted in the header. |
Comments at the head of each library source file
Each library source file should begin with the Library General Public License statement. The first few lines are specific to each source file. The remainder is constant.
/******************************************************************** ** @source AJAX xxxxx functions ....description.... ** @author Copyright (C) 1998 Peter Rice ** @version version ....description.... ** @modified date initials ....description.... ** @modified date initials ....description.... ** @@ ** ** This library is free software; you can redistribute it and/or ** modify it under the terms of the GNU Library General Public ** License as published by the Free Software Foundation; either ** version 2 of the License, or (at your option) any later version. ** ** This library is distributed in the hope that it will be useful, ** but WITHOUT ANY WARRANTY; without even the implied warranty of ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ** Library General Public License for more details. ** ** You should have received a copy of the GNU Library General Public ** License along with this library; if not, write to the ** Free Software Foundation, Inc., 59 Temple Place - Suite 330, ** Boston, MA 02111-1307, USA. ********************************************************************/ |
Comments at the head of each application source file
Each application source file should begin with the General Public License statement. The first few lines are specific to each source file. The remainder is constant.
/******************************************************************** ** @source appname program ....description.... ** @author Copyright (C) 1998 Peter Rice ** @version version ....description.... ** @modified date initials ....description.... ** @modified date initials ....description.... ** @@ ** ** This program is free software; you can redistribute it and/or ** modify it under the terms of the GNU General Public License ** as published by the Free Software Foundation; either version 2 ** of the License, or (at your option) any later version. ** ** This program is distributed in the hope that it will be useful, ** but WITHOUT ANY WARRANTY; without even the implied warranty of ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ** GNU General Public License for more details. ** ** You should have received a copy of the GNU General Public License ** along with this program; if not, write to the Free Software ** Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ********************************************************************/ |