[sldev] Viewer documentation & doxygen

[Carlo Wood]

On Tue, Apr 07, 2009 at 10:47:07PM +0100, Robin Cornelius 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.

Let me add that (the use of) doxygen in itself is not very useful.
What makes the end-product (the documentation) useful is extensive
documentation by the coders, not just having (for example) a class
hierarchy.

So, why doxygen? One of the strong points of doxygen (over, for example
documentation on a wiki) is that the documentation and the code
are kept very close together. This motivates coders a lot more to
keep the documentation up to date: when code is changed, the
documentation is updated and changed as well, in the same file.
This makes it also easier to make it part of the review of patches
to demand that documentation is kept up to date.

I hate to do this (cause it's of course my own project ;), but here
is an example of how documentation can look like:

http://www.xs4all.nl/~carlo17/cwchessboard/index.html

If you click around, you will note that only the somewhat larger
blocks of text really tell you something, not the one-liners.
However, if a developer would really dig deep into this project,
one of the strong points (of using doxygen) is that this documentation
is almost fully automated hyperlinked! While reading about what
class does what in a summary, you can click directly through to
that class for a quick overview.

-- 
Carlo Wood <carlo at alinoe.com>