Re: [ROOT] THtml & W3C validation

From: Christian Holm Christensen (cholm@hehi03.nbi.dk)
Date: Mon Aug 05 2002 - 14:03:02 MEST


Hi Fons et al, 

On 05 Aug 2002 13:51:12 +0200
Fons Rademakers <Fons.Rademakers@cern.ch> wrote
concerning "Re: [ROOT] THtml & W3C validation":
> JDoc makes the header files totally unreadable with all the comments. I
> strongly prefer the comments in the source file. Also every change in
> the implementation would force a change in the header to update the
> comments and trigger complete recompiles. That is why we made THtml and
> the source comments as they are. It would be nice if doxygen could be
> made to understand the current ROOT doc style (description + first
> consecutive comment field at the beginning of each method.

It can.  You can put documentation _anywhere_ you please with
DoxyGen, even in completly seperate files if you like.  I realised
that I didn't show an example in my previous post of the `first
comment' convention, so here goes: 

   Foo::Foo(Int_t integer, Float_t floatingPoint) 
     : fInteger(integer), fFloatingPoint(floatingPoint)
   {
      /// @fn Foo::Foo(Int_t integer, Float_t floatingPoint);
      /// @brief Constructor.
      /// This shows how to document member function arguments (THtml
      /// can't do that). 
      /// @param integer An integer argument. 
      /// @param floatingPoint A floating point (real) argument. */ 
   } 
   ^^^
   Notice the three spaces Fons :-) [For everyone else, this is _not_
   something that DoxyGen insists upon - I'm just teasing Fons]. 

So what you need to do to turn THtml docs into DoxyGen docs: 

* Add another slash '/' in front of your documentation comments. 
* Add the `@fn <member function>' for member function documentation. 
* Add the `@class <class>' for class documentation. 
* Add other fancy stuff if you like
* Edit your configuration, or use the GNOME GUI `doxywizard' to make
  your configuration. 
* Run `doxygen <config file>'.  
* Note the options to make a Java applet tree - it looks really nice,
  but some browser don't like Java, so beware. 
  
That's it.  I hope you like it. 

Yours, 

 ____ |  Christian Holm Christensen 
  |_| |	 -------------------------------------------------------------
    | |	 Address: Sankt Hansgade 23, 1. th.  Phone:  (+45) 35 35 96 91
     _|	          DK-2200 Copenhagen N       Cell:   (+45) 24 61 85 91
    _|	          Denmark                    Office: (+45) 353  25 305
 ____|	 Email:   cholm@nbi.dk               Web:    www.nbi.dk/~cholm
 | |



This archive was generated by hypermail 2b29 : Sat Jan 04 2003 - 23:51:03 MET