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

[Raimar Falke <hawk@xxxxxxxxxxxxxxxxxxxxxxx>]

On Mon, Dec 03, 2001 at 04:56:08PM +0100, Petr Baudis wrote:
> Dear diary, on Mon, Dec 03, 2001 at 04:26:32PM CET, I got a letter, where
> Gregory Berkolaiko <gberkolaiko@xxxxxxxxxxx> told me, that...
> > Please send your comments to the list and/or Andrew <ansutton@xxxxxxx>, I am
> > just a publisher (although highly supportive of the proposal).  Broken links
> > should be reported to me, of course.
> 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 ;).

Since there are tools out there (doxygen, kernel-doc and an doxy mode
for emacs) and people which know "/**" from javadoc this doesn't sound
like a clever idea.

        Raimar

-- 
 email: rf13@xxxxxxxxxxxxxxxxx
 "Of course, someone who knows more about this will correct me if I'm
  wrong, and someone who knows less will correct me if I'm right."
    -- David Palmer (palmer@xxxxxxxxxxxxxxxxxx)