AutoGen - The Automated Program Generator: 7.13.2 library man pages

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 7.13.2 library man pages

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 section Invoking getdefs) near the procedure definition, but they may also be a separate AutoGen definitions file (see section 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 section subblock option) that tells it how to parse the `arg` attribute. The `library` and `header` entries are global definitions that apply to all the documented functions.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Bruce Korb on September, 30 2006 using texi2html 1.76.