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

[Petr Baudis <pasky@xxxxxxxxxxx>]

Dear diary, on Mon, Dec 03, 2001 at 05:01:28PM CET, I got a letter,
where Andrew Sutton <ansutton@xxxxxxx> told me, that...
> 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.
uhuh? who where said anything about webpage?
# kerneldoc [ -docbook | -html | -text | -man ]

> doxygen won't support the long comment string because of the lexical tokens 
> used to parse comment blocks.
i think it can, glancing at
<FindMembers,FindFields,MemberSpec,FuncQual,SkipCurly,Operator,ClassVar,SkipInits,Bases>("//"{B}*)?"/**"/[^/*]
 {
- so it can just because of the lexical tokens used to parse comment blocks ;p.

>                               however, we could probably get away with
> 
> /*****************************/
> /** (or /*@ or /*!)
>  * doxygen comments
>  */
> /*****************************/
I don't like that, if we are going to use something, it should be clever enough
to get us right, especially when we actually use
/**********************************************************************
blabla
**********************************************************************/
convention, which should be pretty friendly to this.

> 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).
you wrote that in your document. i don't see what do you react to.

how do you like the kernel-doc? you did reply to my mail, but didn't respond
the main question of it :-).

-- 

                                Petr "Pasky" Baudis

UN*X programmer, UN*X administrator, hobbies = IPv6, IRC, FreeCiv hacking
.
  "A common mistake that people make, when trying to design
   something completely foolproof is to underestimate the
   ingenuity of complete fools."
     -- Douglas Adams in Mostly Harmless
.
Public PGP key, geekcode and stuff: http://pasky.ji.cz/~pasky/