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

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

On Sun, Apr 22, 2001 at 07:57:36AM -0400, Phil Edwards wrote:
> I installed graphviz 1.5.1 (the build and installation procedure sucks,
> by which I mean it's not automated unless you get AT&T's nmake, and the
> defaults are terrible (the default installation directory is "../../..",
> bleah)), and turned on "dot" in the doxygen config file.

Side note:  I thought that the GraphViz semi-requirement and location
would be mentioned somewhere on the otherwise-all-inclusive Doxygen
homepage, but it isn't.  You have to download the manual and begin
reading it before you discover the link (embedded in PDF) to GraphViz.
It's http://www.research.att.com/sw/tools/graphviz/ for the record.

I don't want to turn dot on by default just yet, but will keep playing
with it on the side.  (And I've asked the authors about the "don't know
whatcha mean by 'red' color" message.)


My biggest doxygen concern has been the flood of information generated from
implementation-only classes.  There's a config switch that says "only produce
docs for classes which are /actually documented/" but it's off right now.
(Otherwise we get nothing.)  So I dropped in some comments (continued)...

*** ios_base.h	2001/04/04 01:02:25	1.11
--- ios_base.h	2001/04/25 01:39:40
***************
*** 137,143 ****
  
    enum _Ios_Seekdir { _M_ios_seekdir_end = 1L << 16 };
  
!   // 27.4.2  Class ios_base
    class ios_base
    {
    public:
--- 137,147 ----
  
    enum _Ios_Seekdir { _M_ios_seekdir_end = 1L << 16 };
  
!   //! 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.  Do not taunt ios_base.
!   */
    class ios_base
    {
    public:


...and turned on that switch, and wow the output looks lots cleaner.
Very very nice.

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*)


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.