Rockbox.org home
release
dev builds
extras
themes manual
wiki
device status forums
mailing lists
IRC bugs
patches
dev guide



Rockbox mail archive

Subject: Re: Plugin API documentation

Re: Plugin API documentation

From: Dominik Riebeling <dominik.riebeling_at_gmail.com>
Date: Tue, 13 Jan 2009 23:11:25 +0100

On Tue, Jan 13, 2009 at 6:48 PM, Maurus Cuelenaere
<mcuelenaere_at_gmail.com> wrote:
> I don't have any problems with that, but does Doxygen ignore unsupported
> commands?

yes. It will throw a warning during its "compilation" run and ignore
the tag line.

> Like for example when you have something like:
>
> /** short description of the function.
> * optional longer description of the function
> * _at_param arg1 description of arg1
> * _at_param arg2 description of arg2
> * _at_return description of return valus
> * _at_see [W[RockboxKernel]]
> */

Doxygen knows a tag _at_see ;-)

> And does Doxygen has a feature where only 1 type of description can get
> used? I don't see any use for adding both a short and long description, IMO
> one (long) description suffices.

Of course -- I wrote "optional longer description" on purpose ;-)
Usually you have at least the _at_brief description, but that can of
course be longer if needed (though the manual advises to keep it
brief. From what I've seen from the current output the descriptions
aren't that long anyway, so I don't see a problem here). With the
JAVADOC_AUTOBRIEF you can only use one description, and everything up
to the first period is considered the brief description. If you want
to use multiple sentences for the brief description you need to mark
it as _at_brief explicitly, at least as far as I understood the
documentation. But as far as I can see the JAVADOC_AUTOBRIEF option is
what we want here.

Oh, and to put a description into a group you write _at_ingroup <groupname>.

And just an idea that popped into my mind: why not recognize links to
the wiki from CamelCase names?


 - Dominik
Received on 2009-01-13

Page template was last modified "Tue Sep 7 00:00:02 2021" The Rockbox Crew -- Privacy Policy