more comments in HTML doc

Pasha Murat (murat@cdfsga.fnal.gov)
Thu, 6 Aug 1998 11:26:04 -0500 (CDT)


Hi Rooters, -
I have one more suggestion. I believe it would be very nice if some
comments typed in the include files would propagate into THtml-generated
documentation. The case I'm particularly interested in is given by the
following fragment of an include file:

-------------------------------------------------------------------------- Svx.hh
class SVX : public POBJECT, public G3_TUBE {
public:
// pointers to currently processed
// subunits
SVX_LAYER* CurrentLayer;
SVX_BARREL* CurrentBarrel;
SVX_LADDER* CurrentLadder;

protected:
// 1 if clustering has already been done
// for event being processed
int ClusteringDone;
// 1 if hits have to be generated by MC
int HitGenerationFlag;
// SVX reconstruction mode : to the
// moment 0 or 1
int ReconstructionMode;
.. snip...
//------------------------------------------------------------------------------
// function members
//------------------------------------------------------------------------------
public:

SVX();
~SVX();
// event initialization routine

int initEvent(CDF_EVENT* event);

// initalize geometry, `level' defines
// the level of detalization

int initGeometry(int level);

// initalize SVX readout constants
int initReadout();
...snip ...

--------------------------------------------------------------------------------
The brief comments which go along with the declarations of the data members
and the member functions (but not necessarily on the same line - it may be
2 os 3 line long comment) would be of great help in the HTML generated docs.
I personally like having comments *before* the declaration itself.
Parsing would be a bit more tricky in this case, but still not a big deal.

How does it sound to you? - Pasha

P.S. Even having the comments right after the declaration still would be much
better than not having them at all.