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

[Benjamin Kosnik]

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

  The Qt style, where special documentation blocks look like: 
/*! 
   ... text... 
*/ 

and the one line version: //! ... one line of text ...   


The JavaDoc style, where special documentation blocks look like: 
 /** 
  * ...text ... 
  */ and the one line version: 


/// ... one line of text ...



Personally, I'd rather use triple-slashes (ie, one-line javadoc style)

Thus:

!   /// 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)

-benjamin