If a .h file is written as a formal interface description when preparing an interface spec, c2man can generate all the manual pages required for the spec at one fell swoop, and then keep them up to date automatically as the interface changes.
Since c2man will accept either function definitions or prototypes, it can be used on either .c or .h files. If the input is a header file, any files specified by -i options are assumed to be prerequisites, and get parsed before the input file. (Any file whose extension begins with ``h'', matched case-insensitively, is considered a header file.)
This is potentially a huge win for most programmers that just love documenting their functions, and updating the documentation every time it changes. Here's an example, named example.h:
man2html: unable to open or read file ../example.h
When:
%
c2man example.h
is run,
this produces a file named
dowork.3
which can be processed by man(1) or used as:
%
nroff -man dowork.3
to produce:
man2html: unable to open or read file ../example.inc
Much of c2man's information is extracted from the comment placed immediately before the declaration/definition of the identifier being documented; this comment is taken to describe the identifier and must be present, or the identifier will be ignored entirely. In the case of a variable declaration/definition, this comment may instead be placed after it starting on the same line.
Global variables are not documented, unless the -v option is used.
Identifiers declared static are ignored by default unless the file is a header file (which is most useful with inline functions) or the -s option is used.
Declarations with the extern keyword are ignored unless they appear in a header file; note that this does not include function definitions.
The SYNOPSIS section begins with an #include line if the source file is a header. After this is an external declaration for the identifier(s) being documented.
Information in the PARAMETERS section is gleaned from the comments immediately before or after each parameter declaration. A comment after a parameter can follow the comma that separates that parameter from the next, if the comment starts on the same line and is the only remaining thing on that line. Leading underscores in a parameter name are stripped when printed in the manual page.
If the manual page is for a group of functions (ie: -g or -G options), identical parameters (in both name and type) common to more than one function are described only once if only one has a comment (as in the ctype example below).
If a parameter is an enumerated type, all the possible values it can take are output, along with their descriptions. These descriptions are gleaned from the comments surrounding the enum identifiers where the type was defined. Comments describing enum identifiers are placed in a similar manner to those that describe function parameters. enum identifiers that begin with an underscore are ignored, which is useful for padding or _NUMBER_OF_... values which aren't normally used by someone calling the function. If none of the identifiers in an enumerated type has a comment, c2man will bunch them together to save space.
The DESCRIPTION section contains everything after the first line or sentence of the comment describing the identifier, up until the word ``returns'' at the start of a line, matched case-insensitively and optionally followed by a colon (:). In the case of a variable of enumerated type, it will also list all the values it can hold.
The RETURNS section contains anything after that. Any of these lines that begin with a single word followed by a colon or a tab generate tagged paragraphs so that lists of possible return values and error codes look neat. If the function is void, don't put anything like "Returns: nothing" in the comment, since it's a waste of space. If the identifier is a function returning an enumerated type, its possible values will be listed here.
Finally, a SEE ALSO section is generated, referencing all the other manual pages generated, if any.
The RETURNS, PARAMETERS and SEE ALSO sections are omitted entirely if they aren't needed.
Comments can be placed with considerable flexibility so that most commenting
styles are supported.
13
The following variations of the enum definition in the dowork.h
example are all equivalent:
/* commas after the comments. */
enum Place
{
HOME /* Home, Sweet Home */,
WORK /* where I spend lots of time */,
MOVIES /* Saturday nights mainly */,
CITY /* New York, New York */,
COUNTRY /* Bob's Country Bunker */
};
16
/* the comment needn't go on the same line,
* if the comma goes after the comment.
*/
enum Place
{
HOME
/* Home, Sweet Home */,
WORK
/* where I spend lots of time */,
MOVIES
/* Saturday nights mainly */,
CITY
/* New York, New York */,
COUNTRY
/* Bob's Country Bunker */
};
14
/* the comment can go before it too. */
enum Place
{
/* Home, Sweet Home */
HOME,
/* where I spend lots of time */
WORK,
/* Saturday nights mainly */
MOVIES,
/* New York, New York */
CITY,
/* Bob's Country Bunker */
COUNTRY
};
But the following example is
NOT
equivalent because the commas are between the identifier and the its
associated comment, and the comment is on a different line.
Each comment actually applies to the wrong identifier, so this will result in
very misleading output.
16
Don't do this:
enum Place
{
HOME,
/* Home, Sweet Home */
WORK,
/* where I spend lots of time */
MOVIES,
/* Saturday nights mainly */
CITY,
/* New York, New York */
COUNTRY
/* Bob's Country Bunker */
};
Since enum identifiers sometimes fall into logical groups, a comment before
such an identifier will be taken to apply to the next few in the list,
provided that the comments describing each individual identifier
are placed after them. Also, there must be a blank line separating the comment
describing the next logical group and the comment at the end of the previous
line, or the two will be coalesced and incorrectly treated as a single comment
for the previous enumerator.
17
In other words, you can go:
/* include logical grouping comments. */
enum Place
{
/* These take up most of the week */
HOME, /* Home, Sweet Home */
WORK, /* where I spend lots of time */
/* More for special occasions */
MOVIES, /* Saturday nights mainly */
CITY, /* New York, New York */
/* The real favourite */
COUNTRY /* Bob's Country Bunker */
};
That may all sound a bit complex, but the upshot is that c2man will usually know which identifier a comment is associated with, unless you do something truly bizarre.
Typesetter specific commands may be included for more complex processing.
man2html: unable to open or read file ../ctype_ex.h
then using:
%
c2man -g ctype.h
yields:
man2html: unable to open or read file ../ctype_ex.inc
For example:
/* * Have a quick puff. * * Warning: Smoking causes lung cancer */ void go_for_a_smoke();
Generates a manual page with a WARNING section.
In all cases, any existing links will be removed before being rewritten.
-ifile
-i"file"
-i<file>
In Texinfo mode, each section is normally coded as a ``heading'' rather than a ``section''. This prevents the section name from appearing in the table of contents. If the option t is given, the name of the manpage is used for the title of the NAME section, and is encoded as a ``section'', placing it in the table of contents. Subsequent sections are encoded as ``headings''. Texinfo supports multiple levels of headings; the desired level may be specified via the sn option, where n starts at 0 for the ``chapter level'' and works down. A top level node is created for the manpage, except when in embedded mode (the c2man -e option). If the n option is specified, a node is created in embedded mode, but without Up, Previous, or Next pointers; these must be filled in (Texinfo mode in emacs does a good job of it).
If subdir is specified, the selected class of output will be written in that subdirectory under the directory given by the -o option if specified, otherwise under the current directory.
If .ext is specified, it will be used as the extension on the output files of the selected class, instead of the default based on the -S option (if specified), or the typesetting output format specified by the -T option.
For example, the following command will generate
nroff(1)
style output under the /usr/local/man hierarchy, documenting functions in
section 3 (/usr/local/man/man3/*.3), global variables in section 3v
(/usr/local/man/man3/*.3v), static functions in section 9
(/usr/local/man/man9/*.9) and
static variables in section 9v (/usr/local/man/man9/*.9v):
%
c2man -o/usr/local/man -v -s -Ofman3.3 -Ovman3.3v -OFman9.9 -OVman9.9v input.c
The -O options will have no effect if -o- is used to write to standard output, and -Ov, -OF and -OV will have no effect unless their classes of output are enabled via the appropriate -v and -s options.
" int f ( a, b )"
but you may replace each space in this string with any number of
whitespace characters.
For example, the option
-F"int f(\n\ta,\n\tb\n\t)"
5
will produce:
int main(
int argc,
char *argv[]
)
5
The default output format is:
int main
(
int argc,
char *argv[]
);
%
c2man -P gcc -E -C
An error at the very end of a function may indicate that the comments at the beginning are badly placed.
Graham Stoney Canon Information Systems Research Australia greyham@research.canon.oz.au (please send bug reports here)
but was heavily derived from
cproto
written by:
2
Chin Huang chin.huang@canrem.com
\n newline \t tab
A comment before a preprocessor directive will be considered to apply to the identifier that immediately follows, if it has no comment of its own. This is because the preprocessor directive gets removed by cpp before c2man looks at it.
Comments aren't legal in some of the more obscure places that they are in C.
Heavy use of #define in a program may yield somewhat obscure manual pages.