The library code documentation includes:
General comments (see above)
Standard header including the GPL
Structured comments for all datatypes
Structured comments for all functions
Functional sections (library source file only)
Each library source file (*.c) must begin with a standard header. This is essentially the same as the application header and includes the GPL:
/******************************************************************** ** @source AJAXLibraryAreafunctions ** **ShortDescription** ** @author Copyright (C)Year AuthorName** @versionVersionNumberdescription of version** @modifiedEditDateEditorNamedescription of edit** @@ ** ** 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. ********************************************************************/
The tags are the same as in the application header except that LibraryArea describes the general area of the library, e.g. "string".
For example:
/****************************************************************************** ** @source AJAX string functions ** ** AjPStr objects are reference counted strings ** Any change will need a new string object if the use count ** is greater than 1, so the original AjPStr is provided as a pointer ** so that it can be reallocated in any routine where string modification ** may be needed. ** ** In many cases the text is always a copy, even of a constant original, so ** that it can be simply freed. ** ** @author Copyright (C) 1998 Peter Rice ** @version 1.0 ** @modified Jun 25 pmr First version ** @@ ** ** 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. ******************************************************************************/
Structured comments (see below) are required for all library functions and datatypes.
Functions in a library source file (*.c) are organised into sections which define groups of functions with related functionality. The sections are documented using structured comments which define rules for naming functions, for naming and datatyping function parameters and for defining the return datatype of the section. This ensures that functions within a library file, and to an extent across library files, present an intuitive and consistent API.
Where new functions are added to an existing library file, they should be positioned in the file under the appropriate section. Where a new library file is created, it is recommended but not strictly required that sections are added to the file.
Sections are of three types. The start of the structured comment is indicated by the tag given:
File Section (@filesection)
Data Section (@datasection)
Standard Section (@section)
A single file section should be given before the functions themselves. This contains basic documentation and rules for the library as a whole. The file section contains a number of data sections, one for each major datatype processed by the functions.
A data section is typically given for all the public datatypes (identified by @data) defined in the header file. For example, ajstr.h defines three new datatypes, AjPStr, AjIStr, AjPStrTok, but there are also functions whose major parameter is a C-style (char*) string. Therefore there are four data sections in total listed under the file section.
Standard sections are given under the data sections. These define groups of functions with related functionality, similar names, and similar parameters. The data section under which a standard section is given depends on the datatype of the return value or major parameter. For example, the default string constructor has no parameters but returns an AjPStr string and therefore is listed under the AjPStr data section. What defines the "major" parameter is to some extent subjective. For all functions with multiple parameters, where the major parameter is not determined by the return type, it should be the first parameter in the list.
Each @filesection, @datasection and @section contains standard text tags described below.
The available tags are preceded by @ as shown in the table (Table D.1, “Function Section Documentation Tags”).
| Tag | Description |
|---|---|
@filesection | Start of structured comment for the file section and followed by the library name, and any number of lines of free text with markup. |
@datasection | Start of structured comment for a data section and followed by the datatype, a description of the datatype, and any number of lines of free text with markup. |
@section | Start of structured comment for a general section and followed by the section name and any number of lines of free text with markup. |
@fnote | Used for general comments about the section, for instance, its relations to other sections. |
@nam | Defines a rule for naming functions. It is followed by a text token indicating a component (substring) of the function name and one or more lines of free text describing the functionality of functions with that named component. X is an integer number which defines the order of that component in the function name (see below). |
@suffix | Defines a naming rule for differentiating functions with essentially the same function but which differ by a single parameter datatype only. For example, two string insertion functions which both insert into an EMBOSS (AjPStr) string, but which insert either an AjPStr or a C-type (char *) string. The permissible suffix that may appear in the function name after the components defined by the @nam tags (see below) is given first. This is followed by the datatype (in brackets) and free text describing the datatype. |
@fdata (standard section only) | Appears in standard sections only, where it must be present. It defines the major datatype (in brackets) that the functions in the section operate on. The datatype must be the same as that given in the current data section. Functions are checked to ensure the data type is used and passed appropriately for the function category (see @fcategory). |
@argrule | Defines a rule for naming and datatyping function parameters and (optionally) for defining the function name suffix. It is followed by a text token indicating the suffix of the function name, or '*' if none is indicated. A second text token gives the name of the parameter. The parameter datatype is then given (in brackets) followed by one or more lines of free text describing the parameter. |
@valrule | Defines the function return type. It is followed by a text token indicating the suffix of the function names for which this return type applies. The return datatype follows (in brackets) and is in turn followed by one or more lines of free text describing the return value under various conditions. |
@fcategory (standard section only) | Defines a standard name used for the functional category. This is used to validate the way in which the data type (see @fdata) is passed to functions. Values can be: "new", "delete", "assign", "modify", "cast", "derive", "use", "iterate", "input", "output", "misc" or "internals" |
An excerpt from ajstr.c is shown below, indicating the first file section, data section and standard section in the file:
/* @filesection ajstr ******************************************************** ** ** @nam1rule aj Function belongs to the AJAX library. ** ** @suffix Len [size_t] length ** @suffix C [char*] C character string ** @suffix S [AjPStr] string object ** @suffix K [char] single character */ /* @datasection [AjPStr] String *********************************************** ** ** Functions for manipulating AJAX (AjPStr) strings ** ** @nam2rule Str Function is for manipulating strings ** */ /* @section comparison ** ** Functions for comparing strings ** ** @fdata [AjPStr] ** ** @nam3rule Match Compare two complete strings. ** @nam4rule MatchCase Case-insensitive comparison. ** @nam4rule MatchWild Comparison using wildcard characters. ** @nam5rule MatchWildCase Case-insensitive comparison ** using wildcard characters. ** @nam5rule MatchWildWord Case-sensitive wildcard comparison of ** first words within two strings. ** @nam6rule MatchWildWordCase Case-insensitive wildcard comparison of ** first words within two strings. ** @nam4rule MatchWord Comparison using whole words. ** @nam5rule MatchWordOne Comparison using whole words matching any one. ** @nam5rule MatchWordAll Comparison using whole words matching every one. ** @nam3rule Prefix Compare start of string to given prefix. ** @nam4rule PrefixCase Case-insensitive comparison. ** @nam3rule Suffix Compare end of string to given suffix. ** @nam4rule SuffixCase Case-insensitive comparison. ** ** @argrule * str [const AjPStr] String ** @argrule C txt2 [const char*] String ** @argrule S str2 [const AjPStr] String ** ** @valrule * [AjBool] True on success ** ** @fcategory use */
Prototypes of functions in the "comparison" section are below:
AjBool ajStrMatchC (const AjPStr thys, const char* txt); AjBool ajStrMatchS (const AjPStr thys, const AjPStr str); AjBool ajStrMatchCaseC (const AjPStr thys, const char* text); AjBool ajStrMatchCaseS (const AjPStr thys, const AjPStr str); AjBool ajStrMatchWildC (const AjPStr thys, const char* text); AjBool ajStrMatchWildS (const AjPStr thys, const AjPStr wild); AjBool ajStrMatchWildCaseC (const AjPStr thys, const char* text); AjBool ajStrMatchWildCaseS (const AjPStr thys, const AjPStr wild); AjBool ajStrMatchWildWordC (const AjPStr str, const char* text); AjBool ajStrMatchWildWordS (const AjPStr str, const AjPStr text); AjBool ajStrMatchWildWordCaseC (const AjPStr str, const char* text); AjBool ajStrMatchWildWordCaseS (const AjPStr str, const AjPStr text); AjBool ajStrMatchWordAllS(const AjPStr str, const AjPStr str2); AjBool ajStrMatchWordOneS(const AjPStr str, const AjPStr str2); AjBool ajStrPrefixC(const AjPStr str, const char* txt2); AjBool ajStrPrefixS(const AjPStr str, const AjPStr str2); AjBool ajStrPrefixCaseC (const AjPStr str, const char* pref); AjBool ajStrPrefixCaseS (const AjPStr str, const AjPStr pref); AjBool ajStrSuffixC (const AjPStr thys, const char* suff); AjBool ajStrSuffixS (const AjPStr thys, const AjPStr suff); AjBool ajStrSuffixCaseC (const AjPStr str, const char* pref); AjBool ajStrSuffixCaseS (const AjPStr str, const AjPStr pref);
Let us examine how the name rules work for the function ajStrMatchWildWordCaseS. This is the most difficult example you are likely to find:
@nam1rule aj Function belongs to the AJAX library.
This rule in the file section defines the first function name component to be aj. All functions in the AJAX library have this prefix.
@nam2rule Str Function is for manipulating strings.
This rule in the data section for AJAX (AjPStr) strings defines the second function name component to be Str. All functions in the AJAX string library (ajstr.h/c) that operate on AJAX (AjPStr) strings have the prefix ajStr.
@nam3rule Match Compare two complete strings.
This rule in the standard section for "comparison" functions defines the third function name component to be Match. The free text indicates that all functions with the prefix ajStrMatch* are for comparing two complete strings.
@nam4rule MatchWild Comparison using wildcard characters.
This rule defines the fourth function name component to be Wild and indicates that functions with the prefix ajStrMatchWild* compare two (complete) strings using wildcard characters.
@nam5rule MatchWildWord Case-sensitive wildcard comparison of first words within two strings.
This rule defines the fifth function name component to be Word and indicates that functions with the prefix ajStrMatchWildWord compare two complete strings using wildcard characters, using only the first words within the two strings.
@nam6rule MatchWildWordCase Case-insensitive wildcard comparison of first words within two strings.
This rule defines the sixth function name component to be Case and indicates that functions with the prefix ajStrMatchWildWordCase compare two complete strings using wildcard characters, using only the first words within the two strings, with case-insensitivity.
@suffix C [char*] C character string.
This rule defined in the file section indicates that the functions with the suffix C take a C-type (char *) string argument.
The naming rules should only be defined where they are strictly necessary to differentiate existing functions. They should not be used in cases where one could break down the functionality semantically, but there is no justification to do so because there are no other similar functions. In such cases the function should have a single component after the basic prefix (e.g. ajStr). This component is typically one capitalised word, but where clarity is genuinely improved by using more than one word then SentenceCase should be used.