dev builds
themes manual
device status forums
mailing lists
IRC bugs
dev guide

Rockbox mail archive

Subject: Plugin API documentation

Plugin API documentation

From: Maurus Cuelenaere <>
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/; I would merge plugin.h and the actual

   * 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

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

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

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:

Cuelenaere Maurus
Received on 2009-01-13

Page was last modified "Jan 10 2012" The Rockbox Crew