NAME

apigen - code and documentation generator for API libraries


SYNOPSIS

apigen [-p <path>] [specification file]


ARGUMENTS

-p <path>
specify path for output files (default is current working directory)


DESCRIPTION

apigen automatically generates code and associated documentation for API libraries, implemented over ATMOS messaging.

The output path may be specifed on the command line; everything else is controlled in the specification file, as detailed below.

The specification file

The overall format of the specification file is a number of blocks, which consist of a keyword (possibly with some arguments), followed by a number of documentation lines.

Keywords tell apigen everything that is required to generate code. Documentation lines are optional, and attach to certain keyword lines to provide text that will be used to generate the HTML documentation.

There must be no blank lines between a keyword line and any of the associated documentation lines.

Line types

The following types of lines are recognised:

# <comment text>
Any line starting with a '#' character is a comment and will be ignored.

<keyword> [<arguments>]
Keywords are described below.

- <short description>
The '-' symbol specifies a short (one-line) description of the associated API or function.

: <long description>
The ':' symbol specifies a long description of the associated API or function. More than one line may be used. For example:
       : This is a long description which continues
       : on the following line.

? <argument name> <argument description>
The '?' symbol specifies the description of a named argument of the associated function. For example:
       ? seconds   Time in seconds

> <return description>
The '>' symbol specifies a description of the return value of the associated function. More than one line may be used (as for ':' above). For example:
       > This function really doesn't return anything
       > at all interesting.

+ <references>
The '+' symbol specifies other functions that relate to the associated function, for the ``see also'' section of the documentation. For example:
       + myRelatedFunction(), myOtherRelatedFunction()

Keywords

The following keywords are recognised:

api <name>
The name of the the module that the API is being generated for. By convention, if the module is called <name>, its API library is called <name>Lib.

This keyword is required (once and only once).

Short and long description lines may optionally be attached ('-' and ':') above.

For example:

       api bridge
       - Virata bridge API
       : <B>bridgeLib</B> provides an API for the Virata bridge.

moduleoutput <file>
Specifies the module output file. If <file> is given as '-', module output will be suppressed.

If omitted, the default name is <name>Lib.module (where <name> is the name specified with the api keyword)>

headeroutput <file>
Specifies the C header output file. If <file> is given as '-', header output will be suppressed.

If omitted, the default name is <name>Lib.h.

codeoutput <file>
Specifies the C code output file. If <file> is given as '-', C code output will be suppressed.

If omitted, the default name is <name>Lib.c.

htmloutput <file>
Specifies the HTML output file. If <file> is given as '-', HTML output will be suppressed.

If omitted, the default name is <name>Lib.html.

messageprefix <prefix>
apigen attempts to intelligently construct suitable ATMOS message names based on the API function names. The prefix for the message names may be overridden by using this keyword.

The default name is <NAME>LIB_ (where <NAME> represents the name specified with the api keyword, in upper case).

It is not usually necessary to use this keyword.

messageid <number>
Specifies the base ATMOS message ID for the API interface messages, written to the module file as an aconfig MessageId directive. If omitted, no MessageId directive will be generated.

nolibinit
If this keyword is specified, no <name>LibInit() function will be generated in the C code and header files. This option is only likely to be useful in order to document an existing header file that has been produced by other means. For example:
       moduleoutput -
       codeoutput -
       headeroutput -
       htmloutput my_documentation.html
       nolibinit

If this keyword is specified when code output is enabled, the resulting code will fail to work unless it is manually edited afterwards.

It is not usually necessary to use this keyword.

function <prototype>
Functions are specified using this keyword; any or all of the documentation lines described above may be attached. <prototype> should be a complete prototype for the function (with all arguments named). A semicolon at the end of the line is optional.

For example:

       function int bridgeFilterAge(void);
       - return filter age
       : Return the current filter age time in seconds.
       > Filter age time in seconds.
       + bridgeFilterAgeSet(), bridgeFilterShow()

Module file output

The module file produced contains aconfig directives to export the generated header file, build the generated C code file, and define a message for each of the specified functions.

Each message field takes the name and type of the argument it corresponds to. If the function returns a result, an additional result field is added to the message, taking its type from the return type of the function.

Header file output

The header file produced contains prototypes for all of the specifed functions, plus the <name>LibInit() function unless suppressed by the nolibinit keywords.

Code file output

The code file produced contains an implementation of the <name>LibInit() function (unless suppressed) which finds the <name> process, and each function of the API, implemented by copying the arguments into the associated message, sending it to the <name> process and waiting for the reply, and returning the result field if applicable.

HTML file output

The HTML file produced contains all of the documentation. References within the HTML to other functions in the API are automatically hyperlinked if they are of the form:

       otherFunction()

(but only if otherFunction() is one of the other functions in the API.)


NOTES

Documenting the <name>LibInit() function

In most cases it is desirable to include the <name>LibInit() function in the apigen specification file for the purposes of documenting it. It takes no arguments and returns an int: 0 (OK) if successful and -1 (ERROR) if not. For example:

       function int bridgeLibInit(void);
       - initialise the bridge API library
       : This must be called once before calling any
       : of the other functions in this library.
       > <B>OK</B> if successful, or <B>ERROR</B> if not.

Implementing the other side of the interface

The <name> module should respond to all of the generated messages by performing the appropriate action, filling in the result field if applicable, and replying to the message.