Man pages for libraries are documented using the agman3.tpl template.
Two global definitions are required, and then
one library man page is produced for each export_func definition
that is found. It is generally convenient to place these definitions
as getdefs comments (see getdefs Invocation) near the procedure
definition, but they may also be a separate AutoGen definitions file
(see Definitions File). Each function will be cross referenced
with their sister functions in a SEE ALSO section. A global
see_also definition will be appended to this cross referencing text.
The two global definitions required are:
library
This is the name of your library, without the lib prefix.
The AutoOpts library is named libopts.so..., so the library
attribute would have the value opts.
header
Generally, using a library with a compiled program entails
#include-ing a header file. Name that header with this attribute.
In the case of AutoOpts, it is generated and will vary based on the
name of the option definition file. Consequently, your-opts.h is
specified.
The export_func definition should contain the following attributes:
name
The name of the procedure the library user may call.
what
A brief sentence describing what the procedure does.
doc
A detailed description of what the procedure does.
It may ramble on for as long as necessary to properly describe it.
err
A short description of how errors are handled.
ret_type
The data type returned by the procedure.
Omit this for void procedures.
ret_desc
Describe what the returned value is, if needed.
private
If specified, the function will not be documented.
This is used, for example, to produce external declarations for functions
that are not available for public use, but are used in the generated text.
arg
This is a compound attribute that contains:
arg_type
The data type of the argument.
arg_name
A short name for it.
arg_desc
A brief description.
As a getdefs comment, this would appear something like this:
/*=--subblock=arg=arg_type,arg_name,arg_desc =*/
/*=*
* library: opts
* header: your-opts.h
=*/
/*=export_func optionProcess
*
* what: this is the main option processing routine
* arg: + tOptions* + pOpts + program options descriptor +
* arg: + int + argc + program arg count +
* arg: + char** + argv + program arg vector +
* ret_type: int
* ret_desc: the count of the arguments processed
*
* doc: This is what it does.
* err: When it can't, it does this.
=*/
Note the subblock and library comments.
subblock is an embedded getdefs
option (see getdefs subblock) that tells it how to parse the
arg attribute. The library and header entries
are global definitions that apply to all the documented functions.