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
> * @param arg1 description of arg1
> * @param arg2 description of arg2
> * @return description of return valus
> * @see [W[RockboxKernel]]
> */

Doxygen knows a tag @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 @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 @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 @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 was last modified "Jan 10 2012" The Rockbox Crew
aaa