apigen - code and documentation generator for API libraries
apigen [-p <path>] [specification file]
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 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.
The following types of lines are recognised:
: This is a long description which continues : on the following line.
? seconds Time in seconds
> This function really doesn't return anything > at all interesting.
+ myRelatedFunction(), myOtherRelatedFunction()
The following keywords are recognised:
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.
If omitted, the default name is <name>Lib.module (where
<name> is the name specified with the api
keyword)>
If omitted, the default name is <name>Lib.h.
If omitted, the default name is <name>Lib.c.
If omitted, the default name is <name>Lib.html.
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
directive. If
omitted, no MessageId
directive will be generated.
<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.
For example:
function int bridgeFilterAge(void); - return filter age : Return the current filter age time in seconds. > Filter age time in seconds. + bridgeFilterAgeSet(), bridgeFilterShow()
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.
The header file produced contains prototypes for all of the specifed
functions, plus the <name>LibInit()
function unless
suppressed by the nolibinit
keywords.
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.
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.)
<name>LibInit()
functionIn 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.
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.