[sldev] Viewer documentation & doxygen

[Jacek Antonelli]

On Tue, Apr 7, 2009 at 4:47 PM, Robin Cornelius
<robin.cornelius at gmail.com> wrote:
>
> What is not clear from [2] & [3] is that doxygen also supports a simple
> comment/mark up system for documenting the code. What this means is
> comments can be added explaining API functions and interfaces through
> out the code and this will be used when generating the html pages to
> provide more thorough documentation, with clickable links directly to
> the code and class references.

Even with the lack of documentation comments in the viewer, Doxygen
has helped me a lot while developing Imprudence. In particular, being
able to see the class inheritance tree and being able to get a list of
all members and methods of a class (including inherited ones) is handy
for the UI widget classes, where there's a lot of inheritance going
on.

Of course, it'd be even more useful with plentiful comments, so I
think putting in some effort to improve the documentation is a very
good idea.

> It does not all need to be
> done at once and clearly this is something that could be chipped away at
> with little extra overhead (as you would only add API docs when you were
> digging in for re-factoring/unit testing/new coding).

I hope this is not meant to exclude those of us who might like to
contribute documentation by itself. :-)


One thought is that it would be good to have established style
guidelines for the documentation. (Something more specific and
concrete than "Doxygen compatible markup".) The "Coding standard" wiki
page [1] refers to a missing "Using Doxygen" page, which I assume
is/was located on the Linden's internal wiki, and may perhaps have
some style guidelines or usage tips. Could a Linden please take a look
and see whether it has anything useful that could be "declassified"?

  [1] http://wiki.secondlife.com/wiki/Coding_standard#Comments


- Jacek