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

[Glenn M. <gle...@vo...>]

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

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>
>=20
>=20
> > -----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=20
> > Hierarchy"
> > page
> >=20
> >=20
> > Just a few points:
> >=20
> > [1] Don't use @class <blah> unless that doxygen comment is=20
> > separate from
> > the owning code item. If the doxygen comment is immediately=20
> > in front of
> > the owning code item, you can start right away with @brief or=20
> > whatever.
>=20
> I use //! \class blah blah.h dir/blah.h
>=20
> for the sole purpose of getting the proper include path=20
> (dir/blah.h rather
> than just blah.h) in the docs. Is there another (better) way=20
> to get this
> behavior? Note that even if blah.h was actually in a=20
> subdirectory relative
> to where Doxygen was run from, Doxygen still strips away the=20
> directory name,
> so I have to put it back in by hand in docs. Am I missing a=20
> config flag to
> get the behavior I want?
>=20
> Thanks
> JR
>=20
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>=20