src2man scans source file srcfile. Only C source files are supported
for now. Comments blocks starting by "/** num", where num is a section
number, are converted into a man file, using txt2man(1).
The first line of the comment block must contain the name of the
manpage, usually the function name, followed by a "-" and a short
description. The following lines are the "DESCRIPTION" section
content, except if they are in upper case, in which case they define
a new section.
If the next line after a comment block is empty, Then no "SYNOPSIS"
section will be generated. Otherwise, src2man will look in the following
source lines for a function prototype or a type definion (struct,
union, typedef, ...) matching the manpage name, and include it in a
"SYNOPSIS" section. This avoids to duplicate the type or function
prototype in the comment block.
The best place for code documentation is in the source file, where
the body is implemented, not the header file which only contains
the prototype. src2man automatically searches for the presence of a
prototype in the corresponding header file, and if found, will print a
"#include" statement in the synopsis.