RE: [Doxygen-users] Formatting groups within "Class Hierarchy" page
Brought to you by:
dimitri
|
From: Glenn M. <gle...@vo...> - 2002-02-25 15:41:46
|
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
|