Recognized Keywords

grdoc recognizes several keywords. You may use additional keywords if you wish, but this will produce a warning from the grdoc system, and be added in the additional information section of the grdoc documentation output.

The keywords fall into three classes. Keywords which can and cannot be contained, and container keywords. Note a special class of keywords which can be contained, the @v* keywords, must be contained in a @var region.

Keywords which cannot be contained

Comments:

The @file, @header and @routine keywords have a very special purpose in that they define the file header or routine for a grdoc region. A grdoc region need not have one of these, but if it does not, that region will be associated with the most recent grdoc region containing either @file, @header, or @routine. This is useful for documenting variables in place etc...
The @calls and @callsby keywords are used to generate a code calling tree. The grdoc system does a sanity check on this tree making sure that, for routine a, the routine b in an a's @calls list has a in b's @calledby list and vice versa. That is, you are not required to enter @calls b in a and @calledby a in b; Only one of these is required. However, we would like to point out that there are great advantages to having both once the system has warned you, namely that the raw source code will be better commented.

Keyword	Intended Meaning
@file	The name of file in question
@header	The header file in question
@routine	The name of the routine in question
@version	The author-assigned version number. Note the RCS ID, if present, will also be placed in the documentation
@author	The author of the routine/file in question
@date	The date the routine was last modified
@defines	The macros defined in the routine/file/header
@includs	The files included in the current file
@calledby	The nameof the @routine which calls the current @routine
@calls	The name of the @routines which are called by the current @routine
@stencil	The size, in computational elements, of the stencil used by the routine in question
@returntype	The type of object the routine or function returns. If the routine is void (or a fortran subroutine) omit this keyword.

Keywords which may or must be contained

Comments:

The @see* headers are special in that they have two purposes. When not placed inside a container tag, they are added to the description under the See also: region. However, when in a container, they are parsed out to become hyperlinks in the documentation.
Parameter tags must be in a @par @endpar region
Variable tags must be in a @var @endvar region
History tags must be in a @history @endhistory region. Note each entry must contain all three tags

@seefile	Creates a cross reference to the file mentioned as specified either by file name or by @file
@seeroutine	Creates a cross reference to the routine mentioned specified only by @routine
@seeheader	Creates a cross reference to the header mentioned specified only by @header
@seeclass	See info on grdoc with OO Langs
@seestruct	See info on grdoc with OO Langs
@seepackage	See info on grdoc with OO Langs
@vdesc	A short description of a variable
@vtype	The type (eg, float, int *) of variable
@vio	The i/o of the variable. Choose in, out, inout, or local, commonblock, or global
@vcomment	An unrestrained comment. NOTE this tag MAY contain html
@pdesc	A short description of a parameter
@ptype	The type (eg, float, int *) of the parameter
@pvalues	Possible values for the parameter in question
@pcomment	An unrestrained comment. NOTE this tag MAY contain html
@hdate	The date of the change
@hauthor	The author of the change
@hddesc	The description of the change

Boolean Keywords

@treeentry	The routine should be marked as a possible entry point into the calling tree
@public @private @protected	See info on grdoc with OO Langs

Container Keywords

@desc ... @enddesc	A description of the item in question
@comment ... @endcomment	A comment
@var ... @endvar	Description of a variable. Note the optional information to this container tag is the name of the variable in question.
@par ... @endpar	Description of a parameter Note the name of the optional information is the name of the parameter used by the routine in question.
@history ... @endhistory	List of historical changes to the file/routine/header in question.
@returndesc ... @endreturndesc	A description of the thing the subroutine returns, if it has a returntype. Note using @returndesc without @returntype will have unpredicatble results at best...
@method ... @endmethod	See info on grdoc with OO Langs

grdoc: A Code Documenting System

Paul Walker (pwalker@ncsa.uiuc.edu)
with Joan Masso (jmasso@ncsa.uiuc.edu)
and Alan Shutko (ats@hubert.wustl.edu)

Last Modified: <i>Fri May 25, 2018 (07:33:42 CEST)</i>