RE: [Doxygen-users] Formatting groups within "Class Hierarchy" page

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

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.

[2] You need to do a @defgroup <foo> only once, in some higher level (in
my case, doxygen-only) header file. Of course, you need a @defgroup for
all groups you intend on using later in your @ingroup commands.

[3] All code items that are to appear in that group need to have an
@ingroup <foo> somewhere in their doxygen block.

Others can give you advice on @( grouping.

In my case, I find simplicity and consistency to have many benefits over
efficiency. By that I mean that we defined coding standards that
included coding templates for the engineers to adhere to. The engineers
said that they wanted @param, @return/@retval, and @bug no matter what;
they should be "None." if it doesn't apply. The technical writer (me)
said that I wanted @ingroup no matter what.

/** @brief short and sweet
 **
 ** @param _TBD_
 **
 ** @return _TBD_
 **
 ** Detailed stuff
 **
 ** @bug None
 ** @ingroup foo
 **/

In other words, I've never really attempted to get @{ working. Nearly
all doxgyen comment blocks (for classes, member functions, global
functions, etc.) contain an appropriate @ingroup. I find that it helps
me subdivide and organize things better. It helps multiple people (the
engineer, the technical writer) who are working on the code; nothing
convoluted.

This advice may not be completely applicable to your situation. YMMV.

HTH,
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: Evil Kosh [mailto:evi...@ya...]
> Sent: Saturday, February 23, 2002 11:56 PM
> To: Doxygen Mailing list
> Subject: [Doxygen-users] Formatting groups within "Class=20
> Hierarchy" page
>=20
<snip>=20
> 	I wanted to provide documentation which would group in=20
> terms of Fusion=20
> Core, then each of the DLL modules separately, but at the=20
> moment, it's=20
> extracting all the classes into one big list, I want to break=20
> that list up,=20
> into chunks according to how they are related, Fusion objects=20
> within the=20
> Fusion Core, would be grouped under Fusion for example, then=20
> the Graphics=20
> Subsystem would list all the classes it had under it, etc, etc, etc.
>=20
> Example:
>=20
> Fusion
> 	FusionCore
> 	FusionObject
>=20
> Graphics
> 	OGLGraphics
> 		OGLSurface
> 	DG8Graphics
> 		OGLSurface
> 	NoArch
> 		Mesh
> 		Vertex3f
> 		Vertex2f
> 		Colour3f
> 		Colour4f
> Sound
> 	ISound
> 	ISoundBuffer
> 	FMODSound
> 		FMODSoundBuffer
> 	SDLSound
> 		SDLSoundBuffer
>=20
> something like this, but I'm having trouble, whenever I try=20
> @defgroup for=20
> the fusion core object for example, using these doxygen tags
>=20
> /** @defgroup FusionGroup Fusion Core object
>   * @{
>   */
>=20
> some global pieces of data
>=20
> /** @class FusionCore
>   * description
>   */
> class FusionCore{
> etc etc etc
> };
>=20
> /** @} */
>=20
> then it does create a module called Fusion, but when you go=20
> into it, only=20
> the global variables are there, the fusion class isnt, it's=20
> containing in a=20
> link, which is repeated twice to the class definition.
>=20
> I think the reason for the duplicated link, is that doxygen doesnt=20
> understand predeclared classes, as in, to get around circular=20
> #include'ing