% cceExtHtml --title "The Ptolemy Kernel" /users/ptolemy/src/kernel/*.{cc,h}
In general, place all comments before the entity they comment. In particular, cceExtHtml will mistakenly associate a comment after a variable declaration on the same line with the next entity. Comments within function arguments are the one exception to this rule, which much appear after the agument, but before the comma that separates it from the next argument.
When both a declaration and a definition of an entity, such as a method, appear, the comment for the definition takes precedence.
Comments may be of two forms: old-style comments, which are surrounded by /* */, and new-style comments, which are one or more lines that begin with //. By default, the text within these comments is interpreted as a short synopsis of the entity it precedes. Additional fields within a comment are denoted by a keyword starting with an at-sign. The text associated with a field starts immediately after the keyword and continues until the next such keyword or until the end of the comment. Invoke cceExtHtml with the --fields option to see the list of recognized fields.
Some sample comments are shown below
// A short synopsis in a new style comment
// A one-sentence description
//
// @Description With a longer, potentially multi-line
// description below it in a new-style
// comment block
/* Normal old-style comment */
/******************************
Example of ignoring asterisks
@Description Asterisks immediately after the start or immediately
before the end of an old-style comment are ignored.
@Author Stephen Edwards
******************************/
cceExtHtml only parses a subset of C++. In
particular, the types it recognizes must be ``simple.'' A class
variable, function argument, or return type must be either a simple
scalar, a class, or a type from a typedef. Additionally, the type may
be a pointer (of any depth, e.g., a pointer to a pointer) to, a
reference to, or a one-dimensional array of any of these simple types.
More complex types (e.g., function types, multi-dimensional arrays)
should be typedefed. Each variable declaration within a class definition may only declare a single variable, e.g., int a,b; is not permitted, but int a; int b; is.