Re: [v3,trunk] Re: example of killer doxygen formatting

[Phil Edwards <pedwards at disaster dot jaj dot com>]

Responding to two messages at once:


Benjamin Kosnik wrote:
> 
> > When do we start adding comments to the files?  Do we want to use the Qt
> > style or the JavaDoc style?  (The correct answer is "Qt".  *grin*)
> 
> Aaah.... the important questions...

I picked the Qt style because

    1) if JavaDoc style is in use, there is a possibility of having to
       escape any periods used in the initial sentence of the comment
       (see Doxygen manual); I've seen some vague comments on other mailing
       lists that more of these situations may start happening in future
       versions of Doxygen
    2) Qt stands out in the code better -- this is admittedly my personal
       preference


> !   /// 27.4.2  Class ios_base
> !   /// The ios_base class does cool stuff.  Do not mess with ios_base.
> !   /// If ios_base becomes unstable, put it down and run away.  
> !   /// The ios_base class is not intended for use by children.  
> 
> (example only, I presume. The comments are a bit too goofy)

You presume correctly.  I needed a text block big enough to linewrap.

I don't think we can use the "brief" commenting markers for large blocks
though.  The brief comments are meant to possibly show up in multiple
places, and having entire paragrpahs pop up multiple times would be annoying.


Richard Andrews wrote:
> Personally I like the JavaDoc comments better.
> 
> Beyond personal choice, which version is more widely accepted? Doxygen is
> killer, but it won't necessarily always be the best system and we should
> consider that people may want to use other doc generators.

I presume that the Qt style is accepted by whatever generator the Qt
folks use.

We are talking about a single-character change, after all.  If we do decide
to change from one to the other, sed(1) is our friend.


> Another related question: do we use \ or @ for structured tags, and do we
> use the structured tags at all?
[...]
> You can certainly do a lot for the formatting of the doc by making use of
> @param, @return, @pre, @post, @sa etc. as well as just adding descriptions.

Yeah... I don't think I'm going to have enough time to do up the structured
tags on my own.  My initial thought was to just add the special comment
blocks and go back later.

Hmmmm.  It wouldn't be too difficult to add boilerplate text like

    /*   yadda yadda yadda
     *   \brief Please document me!
    */

throughout the library; that would at least reduce the generated text
to the set of things hat we wish to document, as opposed to /everything/
that the doxygen parser can get its hands on.


Phil

-- 
pedwards at disaster dot jaj dot com  |  pme at sources dot redhat dot com
devphil at several other less interesting addresses in various dot domains
The gods do not protect fools.  Fools are protected by more capable fools.