doxygen-users — List for users of doxygen

RE: [Doxygen-users] Newbie confused: How to document 'uncommon' c ode?

[Roy L. <Roy...@wd...>]

Hi Moritz,

I'd suggest that you break this up into two steps.  This makes it easier to
explain from C and from Doxygen.

typedef the function pointers above the structure

typedef void        (*t_functionOne)(void);		///< blah blah blah

typdef struct
{
	t_functionOne functionOne;		///< Blah Blah Blah
	...
}

Cheers,

Roy

-----Original Message-----
From: Moritz Voss [mailto:th...@gm...]
Sent: Wednesday, February 27, 2002 6:02 PM
To: Doxygen
Subject: [Doxygen-users] Newbie confused: How to document 'uncommon'
code?


Hello!
I am trying to figure out how to best document the interface structures we
use
in our project. The general deal is as follows: C-language, but
C++-class-like
interfaces are passed on between the modules. It'd be most intuitive to
describe
the function pointers in these interfaces instead of the actual
implementations
of the functions. The function members area actually filled in a constructor
method that is called upon loading of the module, which makes the process
logically opaque to all the other modules.

Example:
typedef struct
{
   void (*functionOne)   (void);
   void (*functionTwo)   (const char* two_parameter);
   int  (*functionThree) (int three_parameter);

} myInterface;


Addendum: These functions exist, with similar but not always identical
names,
however, as several interfaces in one module may have an 'open' member, for
example...

In this example, the actual implementations of the functions would thus
probably
be called "myintfunctionOne", etc.


--
Regards,
 Moritz Voss


_______________________________________________
Doxygen-users mailing list
Dox...@li...
https://lists.sourceforge.net/lists/listinfo/doxygen-users

[Doxygen-users] problem preprocessing #define statements

[Bien R. I. MP P. RD M. <rue...@mc...>]

Hi everyone,

I would like to expand #define statements in the generated html code =
like
this:

In the source:

#define VAL	0x1F
#define VAL2 	VAL

such that in the documentation I get something like this:

#define VAL2	0x1F

I have activated / tried any reasonable combinations of the
EXPAND/PREPROCESS settings, but I always get

#define VAL2 	VAL

Any ideas? Thanks!

Regards
	R=FCdiger

[Doxygen-users] Newbie confused: How to document 'uncommon' code?

[Moritz V. <th...@gm...>]

Hello!
I am trying to figure out how to best document the interface structures we use
in our project. The general deal is as follows: C-language, but C++-class-like
interfaces are passed on between the modules. It'd be most intuitive to describe
the function pointers in these interfaces instead of the actual implementations
of the functions. The function members area actually filled in a constructor
method that is called upon loading of the module, which makes the process
logically opaque to all the other modules.

Example:
typedef struct
{
   void (*functionOne)   (void);
   void (*functionTwo)   (const char* two_parameter);
   int  (*functionThree) (int three_parameter);

} myInterface;


Addendum: These functions exist, with similar but not always identical names,
however, as several interfaces in one module may have an 'open' member, for
example...

In this example, the actual implementations of the functions would thus probably
be called "myintfunctionOne", etc.


--
Regards,
 Moritz Voss

Re: [Doxygen-users] comments in comments

[Dimitri v. H. <di...@st...>]

On Wed, Feb 27, 2002 at 11:21:35AM +0100, Volker Boerchers wrote:
> Hi,
> 
> beside documenting code we are using doxygen also for some specification
> documents (using \page). Until some weeks ago one could use /* */ -
> comments inside a \page for comments that were ignored by doxygen. This
> (undocumented!) feature is broken now. Instead such comments lead to
> parsing errors. It seems as if doxygen takes the closing '*/' as the end
> of the comment-block. A warning 'comment inside a comment' would be
> helpful. (Note that these pages are never compiled so no compiler will do
> this job.)

Comments inside comments only work inside @code ... @endcode and
@verbatim ... @endverbatim blocks.

> Looking for a replacement I figured out that XML-style comments work
> instead. Since I couldn't find this feature documented anywhere (I'ld
> expect it in the "HTML Commands" section), I'ld like to know if this
> feature is "officially" supported or not.

The use of <!-- ... --> as comments inside a comment block is officially
supported by doxygen. I'll put a note in the docs.

Regards,
  Dimitri

[Doxygen-users] Few customization questions

[Tom S. <tsp...@mo...>]

    I've recently started to use Doxygen to document our in-house core
technology library.  I'm happy with the results so far, but i have a few
questions on customization.  Is there a simple way to keep Doxygen from
generating the File List?  I've found that for our project this list just
repeats the information found in the Namespace List.  Also is there a way to
rename a section like the Compound List and Namespace List?  Lastly is there
a way to add whole new sections to the documentation that will end up in the
compressed HTML docs?  In all these cases i'd prefer a method that doesn't
involve post-processing of the files generated by Doxygen, but just a simple
change to the input files, config file, or style sheet.  Thanks for the
help.  Tom

[Doxygen-users] comments in comments

[Volker B. <vbo...@te...>]

Hi,

beside documenting code we are using doxygen also for some specification
documents (using \page). Until some weeks ago one could use /* */ -
comments inside a \page for comments that were ignored by doxygen. This
(undocumented!) feature is broken now. Instead such comments lead to
parsing errors. It seems as if doxygen takes the closing '*/' as the end
of the comment-block. A warning 'comment inside a comment' would be
helpful. (Note that these pages are never compiled so no compiler will do
this job.)

Looking for a replacement I figured out that XML-style comments work
instead. Since I couldn't find this feature documented anywhere (I'ld
expect it in the "HTML Commands" section), I'ld like to know if this
feature is "officially" supported or not.

A little example that shows the problem (but gives no doxygen error
messages):

/** @page specs Technische Spezifikation
/*  $Id: specs.dox,v 1.10 2002/01/07 08:22:39 vboerchers Exp $  */
text
*/

Regards,
Volker
--=20
Volker Boerchers <vbo...@te...>
System Engineer
TECON Systems AG, Perlengraben 2, 50676 K=F6ln, http://www.tecon.de
Tel: +49-221-92007-55, Fax: +49-221-92007-77

[Doxygen-users] namespace in Class Heirarchy like class

[John <joh...@te...>]

Hi,
Sorry if this is is in the archives but I couldn't figure out how the search
the archives.

I would like my namepace to show up in the Class Heirarchy page
heirarchically grouped, like a class is. Is this possible?

This is what it looks like now:
Class1
  <>BaseClass1
Namespace1::Class2
Namespace1::Class3

But I would like it to look like this:
Class1
  <>BaseClass1
Namespace1
  <>Class2
  <>Class3

The namespace class definitions clutter up the listings, it would be nice if
they were grouped the way that classes are.
I tried @defgroup but it had now effect on this page.

Thanks,
John.

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
> > 
> 

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

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

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

> -----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

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

[Doxygen-users] Doxygen-1.2.14-20020224 in CVS

[Dimitri v. H. <di...@st...>]

Hi,

I've added binaries for version 1.2.14 for MacOSX & Solaris to the 
download page and committed the following changes to CVS:
-------------------------------------------------------------------------------
+ CHG: On request of Richard Stallman and others I replaced all 
       generated GIF images with PNG images.
       See http://www.burnallgifs.org for the motivation.
+ CHG: The Documentation of function definitions and declarations are now
       always merged. References/Referenced by relations are now equal
       for function declarations and definitions.
+ CHG: When @retval commands are used to document parameters doxygen will
       no longer produce a warning message for that parameter. @retval can
       still be used to document non parameters such as the return values
       of a function.
+ CHG: #define A(x) x /**< a define */  
       will document a define, while
       #define A(x) /** an argument */ x 
       will document the argument of the define
+ ADD: Included language update for Russian.
+ BUG: Using "@param x,y,z" resulted bogus warnings about undocumented
       parameters.
-------------------------------------------------------------------------------
Enjoy,
  Dimitri

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

[Evil K. <evi...@ya...>]

Hi everyone,

	I've just started to document my Game Engine, called Fusion.  It's built 
of a static lib which is linked against any application which is using 
Fusion, then a set of DLL modules which accompany the exe to provide the 
functionality of fusion, the implementation if you will.

	I wanted to provide documentation which would group in terms of Fusion 
Core, then each of the DLL modules separately, but at the moment, it's 
extracting all the classes into one big list, I want to break that list up, 
into chunks according to how they are related, Fusion objects within the 
Fusion Core, would be grouped under Fusion for example, then the Graphics 
Subsystem would list all the classes it had under it, etc, etc, etc.

Example:

Fusion
	FusionCore
	FusionObject

Graphics
	OGLGraphics
		OGLSurface
	DG8Graphics
		OGLSurface
	NoArch
		Mesh
		Vertex3f
		Vertex2f
		Colour3f
		Colour4f
Sound
	ISound
	ISoundBuffer
	FMODSound
		FMODSoundBuffer
	SDLSound
		SDLSoundBuffer

something like this, but I'm having trouble, whenever I try @defgroup for 
the fusion core object for example, using these doxygen tags

/** @defgroup FusionGroup Fusion Core object
  * @{
  */

some global pieces of data

/** @class FusionCore
  * description
  */
class FusionCore{
etc etc etc
};

/** @} */

then it does create a module called Fusion, but when you go into it, only 
the global variables are there, the fusion class isnt, it's containing in a 
link, which is repeated twice to the class definition.

I think the reason for the duplicated link, is that doxygen doesnt 
understand predeclared classes, as in, to get around circular #include'ing

anyone know what I should do, or suggestions on how I should organise this, 
would be helpful!

thanks

kosh


_________________________________________________________
Do You Yahoo!?
Get your free @yahoo.com address at http://mail.yahoo.com

[Doxygen-users] Re: Documenting enums of an IDL file

[Don M. <dmc...@in...>]

>I have tried Doxygen 1.2.6 on my IDL file, but it didn't work.
>Therefore I cannot yet blame this on a problem in the recent
>version. It must be because I'm doing something wrong. I don't
>think it's my enum definition itself, because simply moving my
>enums into an interface definition makes Doxygen recognize them.
>
>Perhaps it is generated but I don't see it? I have followed every
>HTML link, but I never found it.  A "Something.idl File Reference"
>link? I don't see this in my generated documentation.

If you're using standard HTML output, on the index across the top, click on
File List. On that page, you should see the name of your IDL file, for
example I'll call it "Something.idl". Click on that link, and you will see a
page titled "Something.idl File Reference". This page should list all your
interfaces, then all your enumerations.

Don

RE: [Doxygen-users] Re: Documenting enums of an IDL file

[Francois St-A. <fst...@do...>]

Don,

First, sorry about the HTML; it's out of my control. I *am* writing =
this in
plain text, but it will most certainly be transformed to HTML by our
Exchange Server (I have informed our Admins, but they are not always =
quick
to act on such "details"...)

Well, I'm glad you are having success. It is encouraging, because it =
tells
me that it can be done! However, it's frustrating because I can't get =
it to
work myself. If only I had a complete example...

I have tried Doxygen 1.2.6 on my IDL file, but it didn't work. =
Therefore I
cannot yet blame this on a problem in the recent version. It must be =
because
I'm doing something wrong. I don't think it's my enum definition =
itself,
because simply moving my enums into an interface definition makes =
Doxygen
recognize them.

Perhaps it is generated but I don't see it? I have followed every HTML =
link,
but I never found it.  A "Something.idl File Reference" link? I don't =
see
this in my generated documentation.=20

Except for comments, my enum definition is the first thing in my IDL =
file.

I now strongly suspect either something is missing from my IDL or =
Doxyfile.

Fran=E7ois St-Arnaud.

> -----Original Message-----
> From: Don McClimans [mailto:dmc...@in...]
> Sent: Tuesday, February 19, 2002 5:26 PM
> To: dox...@li...
> Subject: [Doxygen-users] Re: Documenting enums of an IDL file
>=20
>=20
> Francois,
>=20
> First, I for one would appreciate it if you (and others)=20
> would not post HTML messages to the group.

<snip>

>=20
> Now, regarding enums in IDL. I have no problems getting=20
> Doxygen to generate
> documentation for global enums in an IDL file. This is in an=20
> ATL project, as
> well. However, I am still using Doxygen 1.2.6, because there's been =
no
> reason for me to upgrade. So perhaps it is a problem in newer=20
> versions? Or
> perhaps there is something slightly "wrong" (different) about=20
> your enum
> declaration? Or perhaps it is actually there but you haven't seen it
> (because it is with other global objects, not on an interface=20
> documentation
> page)?
>=20

<snip>

> This is before the first interface definition, not inside it, as you
> describe. Works fine. Because it's a global, the enum=20
> documentation shows up
> on the "Something.idl File Reference" page, but it's=20
> correctly hyper-linked
> where it's used, so that doesn't bother me much.
>=20
<snip>

RE: [Doxygen-users] Doxygen XML to DocBook stylesheet

[Prikryl,Petr <PRI...@sk...>]

Hi TJ,

I am not going to use DocBook very soon, but 
I am learning it to produce other parts of our project 
documentation.

I was thinking about DocBook XML as about one
of the wished output format of doxygen. One of the 
pros is that it should solve national character encoding
problems. I guess that solving all details will be rather
long-term task; however, your proposal seems to be
very interesting -- at least for having some testbed for
development of doxygen XML internal structure and
for adding some human-language related features.

I am too green (concerning DocBook XML), but I am
willing to help with this in future.

Petr


> -----Original Message-----
> From:	T.J. Mather [SMTP:tjm...@tj...]
> Sent:	Tuesday, February 19, 2002 5:51 AM
> To:	dox...@li...
> Subject:	[Doxygen-users] Doxygen XML to DocBook stylesheet
> 
> Hi,
> 
> I'm interested in writing a stylesheet that converts the XML 
> output of Doxygen to DocBook/XML.  This is for the Apache Xerces project, 
> to generate documentation for the Perl wrapper.
[...]

AW: [Doxygen-users] Re: Documenting enums of an IDL file

[<Kla...@it...>]

I used the attached input filter to produce a VB like documentation from
IDL. Just in case someone is interested.=20

- Klaus

> -----Urspr=FCngliche Nachricht-----
> Von: Don McClimans [mailto:dmc...@in...]
> Gesendet: Mittwoch, 20. Februar 2002 01:36
> An: dox...@li...
> Cc: Glenn Maxey
> Betreff: RE: [Doxygen-users] Re: Documenting enums of an IDL file
>=20
>=20
[...]
> What I would really like for IDL properties
> would be *one* signature to come out of Doxygen, that covers=20
> both get and
> put. If there's no "put" function, you would mark the property as
> "read-only".
>=20
> I have considered pre-processing our IDL into pseudo-C++, so=20
> that we might
> get something like this. But I haven't done it (yet). :)
>=20
> Don
>=20
>=20
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>=20

RE: [Doxygen-users] Re: Documenting enums of an IDL file

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

> -----Original Message-----
> From: Don McClimans [mailto:dmc...@in...]
> Sent: Tuesday, February 19, 2002 5:36 PM
> To: dox...@li...
> Cc: Glenn Maxey
> Subject: RE: [Doxygen-users] Re: Documenting enums of an IDL file
>=20
>=20
> [Don]
> Well, we already use groups to separate the "methods" from=20
> the "properties".
> You can't nest groups, unfortunately, so we can't then group=20
> each property get and put function.

Actually, you can nest groups. (1) You just can't specify the top level =
and a lower level at the same time on a given code item. (2) The code =
item will be documented in one place, but you could get the brief =
summaries in multiple places.

/** @defgroup class_name **/

/** @defgroup m_<class_name> Methods of <class_name>
    @ingroup class_name=20
 **/

/** @defgroup p_<class_name> Properties of <class_name>
    @ingroup class_name=20
 **/

/** @brief my code item
    @ingroup m_<class_name>
 **/
my code ....

/** @brief my code property
    @ingroup p_<class_name>
 **/
my code2 ...


Admittedly, your naming scheme could become involved, whereby each class =
would have a parent group as well as two nested groups.

I'm not sure if the following would work completely...

/** @defgroup all_methods **/
/** @defgroup all_properties **/
/** @defgroup class_name **/

/** @defgroup m_<class_name> Methods of <class_name>
    @ingroup class_name all_methods
 **/

/** @defgroup p_<class_name> Properties of <class_name>
    @ingroup class_name all_properties
 **/

/** @brief my code item
    @ingroup m_<class_name>
 **/
my code ....

/** @brief my code property
    @ingroup p_<class_name>
 **/
my code2 ...

> You can do things like this, but it's not really=20
> satisfactory, in my opinion at least.=20

I agree.

I have gotten nesting to work, but I haven't always gotten what I =
desired when more than one group was assigned to @ingroup (as I show =
above).

Glenn

RE: [Doxygen-users] Re: Documenting enums of an IDL file

[Don M. <dmc...@in...>]

[Don McClimans]
> Doxygen does not lump the propget and
> propput signatures into one "property" in the documentation,
> which makes the generated documentation confusing, and is annoying if you
> only want to write the documentation once and have it apply to both get
and put
> (no way to do that).

[Glenn Maxey]
>If you defined groups (@defgroup) and assigned groups (@ingroup) to the
appropriate
>code items as part of the doxygen comment blocks, you might get better
control over
>what things appear together. You can go beyond organization by file or by
code, to an
>organization by higher concepts defined by your application.

[Don]
Well, we already use groups to separate the "methods" from the "properties".
You can't nest groups, unfortunately, so we can't then group each property
get and put function.

You can do things like this, but it's not really satisfactory, in my opinion
at least. I did experiment with using grouping to place the put and get
functions together. But if every property is a separate group, the
formatting looks ugly, because a "group" is meant to cover more than two
essentially identical functions. What I would really like for IDL properties
would be *one* signature to come out of Doxygen, that covers both get and
put. If there's no "put" function, you would mark the property as
"read-only".

I have considered pre-processing our IDL into pseudo-C++, so that we might
get something like this. But I haven't done it (yet). :)

Don

RE: [Doxygen-users] Re: Documenting enums of an IDL file

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

> -----Original Message-----
> From: Don McClimans [mailto:dmc...@in...]
> Sent: Tuesday, February 19, 2002 3:26 PM
> To: dox...@li...
> Subject: [Doxygen-users] Re: Documenting enums of an IDL file
>=20
>=20
<snip>

> Doxygen does not lump the propget and
> propput signatures into one "property" in the documentation,=20
> which makes the generated documentation confusing, and is annoying if =
you=20
> only want to write the documentation once and have it apply to both =
get and put=20
> (no way to do that).=20

<snip>

If you defined groups (@defgroup) and assigned groups (@ingroup) to the =
appropriate code items as part of the doxygen comment blocks, you might =
get better control over what things appear together. You can go beyond =
organization by file or by code, to an organization by higher concepts =
defined by your application.

[Doxygen-users] Re: Documenting enums of an IDL file

[Don M. <dmc...@in...>]

Francois,

First, I for one would appreciate it if you (and others) would not post HTML
messages to the group. If you subscribe to the digest form of the list, as I
do, you can't get HTML messages (well, you can, but if you select that
option then they all end up as separate messages again, kind of defeating
the purpose). HTML messages are difficult to read if you aren't reading them
in html. Thanks.

Now, regarding enums in IDL. I have no problems getting Doxygen to generate
documentation for global enums in an IDL file. This is in an ATL project, as
well. However, I am still using Doxygen 1.2.6, because there's been no
reason for me to upgrade. So perhaps it is a problem in newer versions? Or
perhaps there is something slightly "wrong" (different) about your enum
declaration? Or perhaps it is actually there but you haven't seen it
(because it is with other global objects, not on an interface documentation
page)?

As an example, we use:

  /** Enum for visibility of a scalar in the UI and/or results database. */
  typedef [uuid(e1933138-11cb-11d5-93e6-00a024d4dc52)] enum enumVisibility
  {
    Enabled = 0,		///< Visible and enabled
    Disabled = 1,		///< Visible, but disabled (grayed)
    Hidden = 2		///< Not visible
  } enumVisibility;

This is before the first interface definition, not inside it, as you
describe. Works fine. Because it's a global, the enum documentation shows up
on the "Something.idl File Reference" page, but it's correctly hyper-linked
where it's used, so that doesn't bother me much.

For what it's worth, there are other problems with using Doxygen to process
Microsoft IDL files, that make it perhaps not the best tool (and that I
think are bigger issues than enums). Doxygen does not lump the propget and
propput signatures into one "property" in the documentation, which makes the
generated documentation confusing, and is annoying if you only want to write
the documentation once and have it apply to both get and put (no way to do
that). And the documentation shows C++ syntax, so it is not very useful to,
say, VB programmers.

Depending on your project, you might consider:
a. Using a preprocessing (or post-processing) script to make the
documentation better.
b. Making changes to Doxygen itself.
c. Looking at other tools. I have seen tools that produce documentation
based in the "helpstring" entry in the IDL file.

I haven't tried any of these myself.

The advantage of Doxygen for IDL files is the excellent hyper-linking. Our
IDL describes a large number of objects (interfaces), which make up a
complex object model for our system. Objects contain collections of other
objects, etc. It's nice to be able to click on the parameter to one method
in an interface, and immediately jump to the definition of that object's
interface.

Good luck.

Don McClimans

[Doxygen-users] Documenting enums of an IDL file

[Francois St-A. <fst...@do...>]

Hello all,

Although I have used JavaDoc in Java development, I am quite new to =
using
Doxygen with IDL files. I'm hoping that someone on this list can help =
me
solve my problem generating API documentation for this ATL COM DLL IDL
(wow!) compiled with MS VC++ 6.0.

In a previous revision of the IDL file, I used to be able to get =
Doxygen to
generate documentation for enums in the IDL. At that point, the code =
looked
something like this:

	/**
	 * @mainpage
	 * Main page.
	 */

	import "oaidl.idl";
	import "ocidl.idl";

	[
		object,
		uuid(714D28AC-BF4C-49B8-9974-FA767789A962),
		dual,
		helpstring("IInstallerApiCtrl Interface"),
		pointer_default(unique)
	]

	/**
	 * This interface ...
	 */
	interface IInstallerApiCtrl : IDispatch
	{
		/**
		 * Result codes.
		 */
		typedef enum
		{

			/**
			 * The method executed successfully.
			 */
			SUCCESS =3D 0

		} ResultCode;

		/**
		 * Returns the number of un-configured U-520 series devices
in the
		 * Network Database.
		 *
		 * @retval psCount The number of un-configured U-520 series
devices.
		 *
		 * @return IInstallerApiCtrl::SUCCESS
		 *
		 * @see GetUnconfiguredU510Count
		 * @see GetUnconfiguredU520
		 * @see GetUnconfiguredU510
		 */
		[id(1), helpstring("method GetUnconfiguredU520Count")]
HRESULT
			GetUnconfiguredU520Count([out] short * psCount,
[out,retval] short * psResult);

	};


However, the code has now changed to:


	/**
	 * @mainpage
	 * Main page.
	 */

	/**
	 * Result codes.
	 */
	[uuid(714D28B1-BF4C-49B8-9974-FA767789A962)]
	enum ResultCode
	{

		/**
		 * The method executed successfully.
		 */
		SUCCESS =3D 0

	} ResultCode;

	import "oaidl.idl";
	import "ocidl.idl";

	[
		object,
		uuid(714D28AC-BF4C-49B8-9974-FA767789A962),
		dual,
		helpstring("IInstallerApiCtrl Interface"),
		pointer_default(unique)
	]

	/**
	 * This interface ...
	 */
	interface IInstallerApiCtrl : IDispatch
	{
		/**
		 * Returns the number of un-configured U-520 series devices
in the
		 * Network Database.
		 *
		 * @retval psCount The number of un-configured U-520 series
devices.
		 *
		 * @return IInstallerApiCtrl::SUCCESS
		 *
		 * @see GetUnconfiguredU510Count
		 * @see GetUnconfiguredU520
		 * @see GetUnconfiguredU510
		 */
		[id(1), helpstring("method GetUnconfiguredU520Count")]
HRESULT
			GetUnconfiguredU520Count([out] short * psCount,
[out,retval] short * psResult);

	};

Basically, the enum definitions are now defined outside of the =
interface and
have their own UIDs, instead of being defined within the interface. In =
this
configuration, Doxygen no longer generates documentation for the enums. =
I'm
not sure what is the best way to declare enums in an IDL file for an =
ATL COM
DLL. Programmers here have not much experience with this technology, =
but
they feel confident (from research on newsgroups) that this second =
approach
is the way to go. I am not debating this issue because I have no =
previous
experience with ATL COM DLLs and IDL files. But, if the file compiles =
and
seems to solve a problem the programmers had, that's great. But, I just =
need
to find a trick to get Doxygen to extract the enum comments and add =
these to
the generated docs.

I would love to get in touch with someone who has experienced similar
problems.

Regards,

Fran=E7ois St-Arnaud (Eng.), Senior Software Developer, =
fst...@do...
585 Charest Blvd E., 7th Floor, Quebec, QC, Canada, G1K 3J2
Tel: 418 681-8022/0006 x243  Fax: 681-8015
Visit our new website and see the benefits of our PowerBus(tm) =
Technology @
www.domosys.com
We've moved!  Please update your contact info for us, click for more =
info

RE: [Doxygen-users] Doxygen XML to DocBook stylesheet

[Gisbert A. <gi...@we...>]

Hi,

that's interesting, of course. I'm working on the move of our whole,
serverbased automated documentation (several languages) to DocBook XML to
get one consistent base for data mining and knowledge management. That
includes Doxygen we're using to document the APIs of our C++ libraries.

Unfortunately I haven't got the time yet to get really familiar with
Doxygen, but this is in my queue. Nevertheless I could help bringing in my
XSLT experience (and on this way taking off with Doxygen ;-).

Perhaps you should post your request also on the DocBook-list; I'm quite
sure you'll find some others to help there, especially for the DocBook XML
to POD conversion.

BTW: We use the Apache Stylebook Format for inhouse documentation and I'm
working on a Stylebook to DocBook conversion aswell, mainly based on XSL
Transformation. Perhaps that ist interesting for you at the Xerces project,
too.

Greez
Gisbert Amm
http://web.de


> -----Original Message-----
> From: T.J. Mather [mailto:tjm...@tj...]
> Sent: Tuesday, February 19, 2002 5:51 AM
> To: dox...@li...
> Subject: [Doxygen-users] Doxygen XML to DocBook stylesheet
> 
> 
> Hi,
> 
> I'm interested in writing a stylesheet that converts the XML 
> output of Doxygen to DocBook/XML.  This is for the Apache 
> Xerces project, 
> to generate documentation for the Perl wrapper.
> 
> The plan is to start with Doxygen XML, convert it to DocBook XML, then
> convert it by another sytlesheet to Perl's Native POD format.
> 
> Would a Doxygen XML to DocBook stylesheet be generally useful for the 
> Doxygen project?
> If not, I will probably simply write a Doxygen XML to POD 
> stylesheet, as 
> that would be much simpler.
> If so, is anybody else working on this, or interested in helping out?
> 
> Thanks,
> TJ
> 
> 
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
> 

[Doxygen-users] Doxygen XML to DocBook stylesheet

[T.J. M. <tjm...@tj...>]

Hi,

I'm interested in writing a stylesheet that converts the XML 
output of Doxygen to DocBook/XML.  This is for the Apache Xerces project, 
to generate documentation for the Perl wrapper.

The plan is to start with Doxygen XML, convert it to DocBook XML, then
convert it by another sytlesheet to Perl's Native POD format.

Would a Doxygen XML to DocBook stylesheet be generally useful for the 
Doxygen project?
If not, I will probably simply write a Doxygen XML to POD stylesheet, as 
that would be much simpler.
If so, is anybody else working on this, or interested in helping out?

Thanks,
TJ

[Doxygen-users] Doxygen 1.2.14 in CVS

[Dimitri v. H. <di...@st...>]

Hi,

Release 1.2.14 is now available from CVS. Here is the changelog
for this week:
---------------------------------------------------------------------------
+ ADD: Included language update for German (Thanks to Oliver Brandt).
+ ADD: Added "list of all members" to the XML output.
+ ADD: Added option DOT_IMAGE_FORMAT that can be used to set the image
       format of images generated by dot (possible formats: gif, png, jpg).
+ BUG: The version number in config files generated by doxywizard was 
       always 0.1.
+ BUG: Having a macro function and typedef with the same name confused doxygen.
+ BUG: An \endverbatim command at the end of a \name section was not parsed.
+ BUG: Stars (*) at the start of a line in /**< ... */ style comments 
       after a parameter were included in the result.
+ BUG: Putting a C-style comment in a @code block was not handled properly.
---------------------------------------------------------------------------
Enjoy,
  Dimitri