The application code documentation includes:
General comments (see above)
Standard header including the GPL
Documentation of main() function
Structured comments (ideally) for datatypes
Structured comments (ideally) for functions
The application source file must begin with a standard header that includes the General Public License (GPL) statement, which should be used where possible (see Section 1.1, “Licence Information”). The header is shown below. The first few lines are specific to each source file, the remainder are constant:
/******************************************************************** ** @sourceApplicationName** **ShortDescription** ** @author Copyright (C)Year AuthorName** @versionVersionNumberdescription of version** @modifiedEditDateEditorNamedescription of edit** @@ ** ** 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. ********************************************************************/
Where:
ApplicationName is the name of the application.
ShortDescription is a short description of the application, which should be identical to the text given after the documentation: attribute in the application ACD file and in the main() function documentation (see below).
Year is the year of first release and AuthorName is the original author.
VersionNumber is the version number and may be followed by an optional description.
EditDate and EditorName are the date and author of the last significant edit and may be followed by an optional description of the revision. The header may contain as many of these lines as required.
For example:
/* @source water ** ** Smith-Waterman local alignment ** ** @author: Copyright (C) Alan Bleasby ** @@ ** ** 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. ******************************************************************************
This should be preceded by a header block matching the following format:
/* @progApplicationName**************************************************************** ** **ShortDescription** ******************************************************************************/
Where
ApplicationName is the name of the application.
ShortDescription is a short description of the application, which should be identical to the text given after the documentation: attribute in the application ACD file and in the application code standard header (see above).
For example:
/* @prog water **************************************************************** ** ** Smith-Waterman local alignment ** ******************************************************************************/