[sldev] Viewer documentation & doxygen

[Glen]

Another very good example of doxygen in use is the KDevelop source and 
http://www.libqglviewer.com/.

--GC

Carlo Wood wrote:
> 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.
>