From: Maurus Cuelenaere <mcuelenaere_at_gmail.com>
Date: Tue, 13 Jan 2009 15:26:04 +0100

Hi all,

As you know some time ago I committed a (PHP) plugin documentation
generator, which was meant to generate HTML documentation regarding the
plugin API.

Now, I would like to refactor this idea and instead of having a separate
file (docs/PLUGIN_API.new); I would merge plugin.h and the actual
documentation.

Advantages:
   * no need to edit another file when changing something to plugin.h
   * helps 'forgetting' to update the plugin documentation, as the
documentation will be next to the actual function call
   * 'forces' documentating of all functions in a way

Disadvantages:
   * plugin.h will get bigger and perhaps a bit more difficult to navigate
in

The way I see it how this should be done is something like:

/*
> Description of function. [REQUIRED]
> arg1: description of arg1 [OPTIONAL]
>
    arg2: description of arg2 [OPTIONAL]
> returns: description of return value [OPTIONAL]
> */
> int (*function)(int arg1, int arg2);
>

Of course, the documentation markup would still apply to the descriptions
(e.g.: [W[wiki url]], [S[svn url]], [F[function]], [[url]], %BR% and
=code=).

Also, the parser currently tries to parse so-called 'groups' of functions,
which are just a one-line C comment who are put here and there between
function calls.
This functionality (and the ability to detect whether HAVE_X or HAVE_Y needs
to be defined to get access to function z), would still be available.

Any comments/questions/opinions/... ?

P.S.: this is an example of the current output of the generator:
http://mcuelenaere.alwaysdata.net/rockbox_api_example_2/

Regards,
Cuelenaere Maurus
Received on 2009-01-13