[Freeciv-Dev] Re: Code commentary proposal (by A. Sutton)

[Andrew Sutton <ansutton@xxxxxxx>]

On Monday 03 December 2001 10:56 am, Petr Baudis wrote:
> I like that! However doxygen seems to be a bit too large and complex for
> me. IMHO we would be able to survive with even something much smaller and
> lightweight, like 'kernel-doc' - GPL'ed perl script taking the format
> mentioned in Andrew's document, but it has only 45kb and can be easily
> shipped along with the mainline distribution (source-code obviously :). For
> those who don't happen to have /usr/src/linux/scripts/kernel-doc, I copied
> it to
> http://pasky.ji.cz/~pasky/cp/kernel-doc. The only disadvantage obvious to
> me at the first sight is missing support for /**< ... */.
>
> I would only propose to change the prefix from /** to
> /**********************************************************************
> this is actually used in the freeciv code and keeping this will result in
> smaller diffs, higher lucidity and happier Raimar ;).

it doesn't have to be a web page. doxygen can generate latex documents that 
can be turned into ps or pdf format for easier consumption.

doxygen won't support the long comment string because of the lexical tokens 
used to parse comment blocks. however, we could probably get away with

/*****************************/
/** (or /*@ or /*!)
 * doxygen comments
 */
/*****************************/

it's a little redundant but it will allow both visible separation of code 
chunks and doxygen comments.

the /**< ... */ comment block is used for inlining comments. for example,

struct foo {
        int bar;        /**< Some documentation */
};

this will attribute the declaration of bar with the comment provided. the 
only other way to get doxygen to see the comment is to add a comment block 
above or below the declared member (above looks alot better in those cases).

andy