[crossfire] Code Doxygenification

[Nicolas Weeger (Laposte)]

Hi :)

> So does anyone have any objections to 'doxygenificaiton' of the code? :)

None here, quite the opposite :)

> 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
>  */

Agreed to that (first proposal).

> 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
>  */

Agreed to first proposal too.

> 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

Idem.

> 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.

Nice feature, yeah, agreed we should use it.

> 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.

Maybe "::foobar"? It's coherent with namespace naming.


I'd say we should do that progressively, while changing functions and such, 
instead of everything in one time.

Nicolas