As noted previously, mxmldoc looks for in-line comments to describe the functions, types, and constants in your code. Mxmldoc will document all public names it finds in your source files - any names starting with the underscore character (_) or names that are documented with the @private@ directive are treated as private and are undocumented.
Comments appearing directly before a function or type definition are used to document that function or type. Comments appearing after argument, definition, return type, or variable declarations are used to document that argument, definition, return type, or variable. For example, the following code excerpt defines a key/value structure and a function that creates a new instance of that structure:
/* A key/value pair. This is used with the
dictionary structure. */
struct keyval
{
char *key; /* Key string */
char *val; /* Value string */
};
/* Create a new key/value pair. */
struct keyval * /* New key/value pair */
new_keyval(
const char *key, /* Key string */
const char *val) /* Value string */
{
...
}
Mxmldoc also knows to remove extra asterisks (*) from the comment string, so the comment string:
/*
* Compute the value of PI.
*
* The function connects to an Internet server
* that streams audio of mathematical monks
* chanting the first 100 digits of PI.
*/
will be shown as:
Compute the value of PI.
The function connects to an Internet server
that streams audio of mathematical monks
chanting the first 100 digits of PI.
Comments can also include the following special @name ...@ directive strings: