RE: [Doxygen-users] Don't use @class <blah>

[Jan R. <ja...@mo...>]

Good advice, thanks Glen.
JR

> -----Original Message-----
> From: Glenn Maxey [mailto:gle...@vo...]
> Sent: Monday, February 25, 2002 10:53 AM
> To: Jan Reimers; Doxygen Mailing list
> Subject: RE: [Doxygen-users] Don't use @class <blah>
> 
> 
> I stand corrected on an appropriate use of @class <blah>.
> 
> My advise against using @class/@fn/etc. stem from common 
> misunderstandings that I and others have when first getting 
> started using Doxygen. I mistakenly thought that I had to 
> tell Doxygen what the comment block was for. 
> 
> In actuality, I only have to tell Doxygen what the block is 
> for when the block doesn't appear with its owning code. (And 
> you bring up an important use of @class.)
> 
> In the case of @fn, if you don't use the exact current 
> syntax, you can screw up your output. You get absolutely no 
> benefit with "@fn <blah>" if it <blah> is just the function 
> name; <blah> has to contain the name and exact definition. If 
> the code definition changes without the @fn being updated, 
> you'll get (1) the changed code item without comments, (2) 
> the old comments won't attach to anything valid and land in 
> the ether never-never-land.
> 
> @class markings aren't so bad, because class names rarely 
> change. The @fn markings, however, can really mess you up, 
> because they require the exact syntax of the prototype. They 
> introduce yet another area that has to be manually updated 
> with the code. Hence, if you don't have to use @fn, don't.
> 
> Glenn Maxey
> Technical Writer
> Voyant Technologies, Inc.
> 1765 West 121st Avenue
> Westminster, CO 80234-2301
> Tel. +1 303.223.5164
> Fax. +1 303.223.5275
> gle...@vo...
> 
> 
> > -----Original Message-----
> > From: Jan Reimers [mailto:ja...@mo...]
> > Sent: Monday, February 25, 2002 11:40 AM
> > To: Doxygen Mailing list
> > Subject: [Doxygen-users] Don't use @class <blah>
> > 
> > 
> > > -----Original Message-----
> > > From: Glenn Maxey [mailto:gle...@vo...]
> > > Sent: Monday, February 25, 2002 7:42 AM
> > > To: Evil Kosh; Doxygen Mailing list
> > > Subject: RE: [Doxygen-users] Formatting groups within "Class 
> > > Hierarchy"
> > > page
> > > 
> > > 
> > > Just a few points:
> > > 
> > > [1] Don't use @class <blah> unless that doxygen comment is 
> > > separate from
> > > the owning code item. If the doxygen comment is immediately 
> > > in front of
> > > the owning code item, you can start right away with @brief or 
> > > whatever.
> > 
> > I use //! \class blah blah.h dir/blah.h
> > 
> > for the sole purpose of getting the proper include path 
> > (dir/blah.h rather
> > than just blah.h) in the docs. Is there another (better) way 
> > to get this
> > behavior? Note that even if blah.h was actually in a 
> > subdirectory relative
> > to where Doxygen was run from, Doxygen still strips away the 
> > directory name,
> > so I have to put it back in by hand in docs. Am I missing a 
> > config flag to
> > get the behavior I want?
> > 
> > Thanks
> > JR
> > 
> > _______________________________________________
> > Doxygen-users mailing list
> > Dox...@li...
> > https://lists.sourceforge.net/lists/listinfo/doxygen-users
> > 
>