|
Rockbox mail archiveSubject: Plugin API documentationPlugin API documentation
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 Page template was last modified "Tue Sep 7 00:00:02 2021" The Rockbox Crew -- Privacy Policy |