[crossfire] Code Doxygenification

[Alex Schultz]

Hi everyone,

So does anyone have any objections to 'doxygenificaiton' of the code? :)
Also, we need to agree on a standard form of doxygen comments to use as
there are a few different syntax variations it accepts. In addition, if
we do agree that the code should be 'doxygenificatated', I think it
would be a good idea to document this in the coding style docs.
Personally I'd advocate the following commenting style:

-------
Use Javadoc style comments as opposed to QT style comments. IMHO it's
easier on the eyes. For example:
/**
 * This does foobar
 */
and *not*:
/*!
 * This does foobar
 */

-------
Doxygen accepts commands in both the forms "\foobar" or "@foobar". I
believe that "@foobar" is easier to read as it stands out more (from
things like escape characters and the / character used in commenting)
without being an eyesore either. For example
/**
 * This function does foobar
 * @param ob The object to foobar
 * @todo Handle multitile objects
 */
as opposed to
/**
 * This function does foobar
 * \param ob The object to foobar
 * \todo Handle multitile objects
 */

-------
Make use of the "@file foobar.c" directive at the top of code files. I
think files should have their purpose clearly outlined in order to keep
code organized. For example:
/** @file foobar.c
 * Handle foobaring.
 * @note Don't put baz here.
 */
at the start of the file

-------
Have JAVADOC_AUTOBRIEF set to TRUE and comment appropriately.
Doxygen supports both full and brief descriptions. Explicitly specifying
each tends to look poor when looking at the comment manually, however by
using JAVADOC_AUTOBRIEF, it automatically makes the first sentence of 
the description the brief description. This requires comments to be
written to fit this, with the first sentence of the description being a
summary of what the function/etc. does.
      (see:
http://www.stack.nl/~dimitri/doxygen/config.html#cfg_javadoc_autobrief )

-------
Another thing, is that in order to link to global variables or global
typedefs in doxygen comments, one needs to write it as either "::foobar"
or as  "#foobar". Personally I don't like either much, but we should
decide which to use.

I suggest one looks at
http://www.stack.nl/~dimitri/doxygen/docblocks.html for more information
on what doxygen accepts.

Alex Schultz