doxygen-users — List for users of doxygen

Re: [Doxygen-users] xml

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

On Thu, Oct 18, 2001 at 10:03:47PM +0200, Schreib, Dirk, VTC-BPI wrote:
> > From: Dimitri van Heesch [mailto:di...@st...] 
> > No, it is just something that could be used as a starting 
> > point ;-) Any help on writing a proper DTD is highly welcomed.
> 
> Hello Dimitri,
> 
> forget about DTD. XML-Schema is easier (native XML syntax),
> has much more possibilities (e.g. AnyElement, etc.) and is
> not deprecated...

I've been looking into this as well (that's why I didn't do
much work on the DTD yet :-). If you know any (preferable non-Java) 
open-source tools that can validate XML schema 1.0 docs please let
me know.

Regards,
  Dimitri

RE: [Doxygen-users] xml

[Schreib, D. VTC-B. <dir...@vo...>]

> From: Dimitri van Heesch [mailto:di...@st...] 
> No, it is just something that could be used as a starting 
> point ;-) Any help on writing a proper DTD is highly welcomed.

Hello Dimitri,

forget about DTD. XML-Schema is easier (native XML syntax),
has much more possibilities (e.g. AnyElement, etc.) and is
not deprecated...

Dirk


---------------------------------------------------------
This Mail has been checked for Viruses
Attention: Encrypted mails can NOT be checked!

**

Diese Mail wurde auf Viren geprueft
Hinweis: Verschluesselte mails koennen NICHT auf Viren geprueft werden!
---------------------------------------------------------

Re: [Doxygen-users] xml

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

On Thu, Oct 18, 2001 at 10:26:00AM -0700, Hunter Marshall wrote:
> Ok, I found the "XML" option in the config file. It successfully ran
> against a codebase that produces about 230 pages of LaTeX output
> producing a 1.8 MB xml file.
> 
> I will begin working with a smaller case. Is the doxygen.dtd file in
> doxygen-1.2.11.1/addon/xmlparse the associated DTD? 

No, it is just something that could be used as a starting point ;-)
Any help on writing a proper DTD is highly welcomed.

> I'm not an XML
> expert, what would be a useful next step? XSLT experiments?

You could try that, I would be interested in the results. 

My priorities w.r.t. XML are:
1) get all the information collected by doxygen in the XML output.
2) write a parser library (xmlparse) that could be used by other 
   C++ programmers as a convenient API for writing new front-ends for 
   doxygen.

Regards,
  Dimitri

Re: [Doxygen-users] xml

[Hunter M. <hma...@vi...>]

Ok, I found the "XML" option in the config file. It successfully ran
against a codebase that produces about 230 pages of LaTeX output
producing a 1.8 MB xml file.

I will begin working with a smaller case. Is the doxygen.dtd file in
doxygen-1.2.11.1/addon/xmlparse the associated DTD? I'm not an XML
expert, what would be a useful next step? XSLT experiments?

	hunter



On Wed, Oct 17, 2001 at 03:37:25PM -0700, Hunter Marshall wrote:
> I know there has been on-going work toward xml output, but I have been
> too busy to dig into it. I could have some time on my hands and would
> like to see what I can do with the xml aspect of doxygen. I'm not sure
> I have the skills but maybe I could somehow help out, if only in
> trying to use what's there (if useable).
> 
> Could someone give some hints or references? Thanks for any info. 
> 
> 	hunter
> 
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
> 

[Doxygen-users] xml

[Hunter M. <hma...@vi...>]

I know there has been on-going work toward xml output, but I have been
too busy to dig into it. I could have some time on my hands and would
like to see what I can do with the xml aspect of doxygen. I'm not sure
I have the skills but maybe I could somehow help out, if only in
trying to use what's there (if useable).

Could someone give some hints or references? Thanks for any info. 

	hunter

[Doxygen-users] Multiple versions of a method: order and references

[Christopher B. <bre...@ya...>]

I asked a question too generally before. I have
multiple versions of some methods (as many as six) and
they have separate documentation. I would like to
control the order in which the methods appear on the
help page, and be able to refer to a particular
version. I'd like to say something like "this version
works like version 2 except that...". And I'd also
like to link to one version and not another. Any ways
to do these things?

Christopher Brewster

__________________________________________________
Do You Yahoo!?
Make a great connection at Yahoo! Personals.
http://personals.yahoo.com

[Doxygen-users] [bug ?] Sorting pb in the Alphabetical List

[Sebastien B. <seb...@ba...>]

Hi

If you have a look at our nightly generated doc (version 1.2.10):
http://public.kitware.com/VTK/doc/nightly/html/classes.html

You will notice that  this sequence:
	AFBCSMCFCDEFDFGHIFIJKLMNOROPQRMRSTUVWX
is the alphabetized class ordering in the Alphabetical List...

Check the 'F' section (the first one :)

We use that Doxygen setting:

# In case all classes in a project start with a common prefix, all classes
# will be put under the same header in the alphabetical index. The
# IGNORE_PREFIX tag can be use to specify a prefix that should be ignored
# while generating the index headers.

IGNORE_PREFIX = vtk

so vtkFieldData::BasicIterator is definitely under 'F'... But seems to have 
been plugged into 'B' because of BasicIterator.

Weird.

[Doxygen-users] Re: Getting macro expansion to work

[Simon W. <sim...@ma...>]

FROM: Dimitri van Heesch
DATE: 10/14/2001 11:14:02
> On Thu, Oct 11, 2001 at 10:46:09AM +0000, Simon Watts wrote:
> > I just cant seem to get a C++ #define'd macro to be expanded before
> > documentation.  I have set:
> > > MACRO_EXPANSION = YES
> > EXPAND_ONLY_PREDEF = YES
> > EXPAND_AS_DEFINED = ((macros))
> > > So my EXPAND_AS_DEFINED field is
> > > EXPAND_AS_DEFINED = "ACCESS_STRING(NAME,FIELD,LENGTH)" \
> > "ITERATOR(NAME,TYPE,INFO)"
> Please try
> EXPAND_AS_DEFINED = ACCESS_STRING ITERATOR
> So just macro names without the arguments. This should work.


I have tried this, but I still get the Macros appearing as-if methods in
the classes.

I am driving doxygen from a make file, which builds the config as a
variable string echoed to doxygen on stdin.  Other parameters in the
config appear to be working.  I need to do it this way, rather than
having a dedicated config file, because I am building a framework in
make which will be used on several modules by different people, and I
want to limit others need to know the internals.

The make variable is build up incrementally, thus:

DOXYFILE += EXPAND_AS_DEFINED\=ACCESS_STRING ITERATOR\\n

which produces the right effects with

  echo -ne $(DOXYFILE) | $(DOXYGEN) -

Which echos as (editing for anonymity):

 @INCLUDE_PATH=/path/to/make/system
 @INCLUDE=default-doxyfile
 INCLUDE_PATH=/master/include /project/include
 PERL_PATH=/usr/bin/perl
 HAVE_DOT=YES
 DOT_PATH=/usr/bin
 PROJECT_NAME=My Project
 PROJECT_NUMBER=0.0.0
 EXPAND_AS_DEFINED=ACCESS_STRING ITERATOR
 INPUT= ...<snip>

Other stuff is defined in the "default-doxyfile" at
"/path/to/make/system".  I'll attach that file anyway -- its mainly the
default config with some options enabled (comments stripped for size).


The macros are used within class definition body in the various headers,
and expand to be inline methods of the class.  eg,

class Foo {
  ...
  ACCESS_STRING (name,m_name,17);
  ...
};

gives

class Foo {
  ...
  string get_name () { return string (data.m_name, 17); };
  ...
};

((
I know that the trailing comma after the function inline isnt C++, but
GCC 2.96 does not complain, and it seems to help Doxygen parse the
macros in the first place.  Without it, it gets confused and following
lines in the header vanish.  I actually define the macro as ending in 
"//" in case this hides the ";".
))



Si.


-- 
Simon A Watts
Software Engineer
Marconi Medical Systems
mailto:sim...@ma...
tel: +44(0) 1252 747 311

[Doxygen-users] Using Tag files and core dumps @ 1.2.8.1 and 1.2.9.1

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

Problem: Doxygen projects that use tag files tend to core out for
Doxygen versions greater than 1.2.7. They core out in the build process
and no installdox perl script is generated to resolve hyperlinks.=20

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

Simplified Background:=20

BAPI doxygen project (ivx_bapi.dox with HTML output to
doc_publish/cref_ivx_bapi) has:

TAGFILES               =3D=20
GENERATE_TAGFILE       =3D x_bapi.tag

Voyeng doxygen project (att_voyeng.dox with HTML output to
doc_publish/cref_voyeng) has:

TAGFILES               =3D x_bapi.tag
GENERATE_TAGFILE       =3D x_voyeng.tag

My script file for creating just a portion of the system has:

echo "Remove files from last run"
rm x*.tag
rm doc_publish/cref_ivx_bapi/*
rm doc_publish/cref_voyeng/*
/zulu/tmp/doxygen-1.2.7/bin/doxygen ivx_bapi.dox=20
/zulu/tmp/doxygen-1.2.7/bin/doxygen att_voyeng.dox    =20
echo "Resolve hyperlinks..."
cd doc_publish/cref_voyeng
installdox -l x_bapi.tag@zz_go_parallel_zz/cref_ivx_bapi
cd ../..

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

The above settings work when I run Doxygen 1.2.7. The SME who supports
me has upgraded Doxygen several times. We're now running Doxygen
1.2.9.1. I'm noticing that the HTML output craps out for these projects
that include tag files. When I go back and test at 1.2.8.1, I'm getting
a version of the same error.

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

With version 1.2.9.1, I get:

<much cranking deleted>
...
Determining which enums are documented
Computing member references...
Computing member relations...
Adding classes to their packages...
Adding members to member groups.
Distributing member group documentation.
Building full member lists recursively...
Inheriting documentation...
Adding source references...
Adding todo/test/bug list item...
Segmentation Fault - core dumped

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

Has anybody been experiencing problems with tag files and installdox not
working properly at newer versions of Doxygen? Are there any workarounds
short of going back versions?

Any insight will be appreciate.

In the meantime, we'll be upgrading our Doxygen version to the latest
and greatest.

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

[Doxygen-users] Source browser in latex?

[<nb...@fr...>]

I have

SOURCE_BROWSER         = YES

The source is there in the HTML, but not LaTeX.  I need the LaTeX
version for a printed output.

This is doxygen-1.2.11.1.  Is it supposed to work this way?

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.0.4 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.6 and Gnu Privacy Guard <http://www.gnupg.org/>

mQGiBDZa9ZcRBACYGMoAmHIBUR19lDLZNJhgxGtqVchV7OiwniGIE0UpwRj08fDX
/KO7/cXgXDZqFEgHF98e6Gbm4efyyC7seP4Ye8Av3n8h8PMv307lQieJd5qQVvwx
vwJWGHsX1EOsv/Suzb2ZcYllU4dgrdBIkRLQ5tsJPiWtxjsfBsONGqWmIwCghmQA
GayzNTFUUy0JkGP8SEJRycED/0GvchcxrSnN0FDe5HqM2YzNOnQYGEasAgRSNoG7
O87uudA3j+Hh4GQSD7VgleYArCXqfaNd8pj+EY0ykGjcTJk07aAl+Ib8UrQ8eNk/
RON0+/ZRN6QGqte1lokR969AgVFDQaHV0IctElZdpRg+JbKUiBn3iYaY7xfYYr1z
M6l/A/4v7HkRTfoMsEae+vhuatmekXpV7rrcmhAjLdaUWbamNrkp7N6fnDMQcRjJ
DA/9VBV8qjokGu2PEj+HQGZb52y1+/S+wmUbKlS/EkYMME9gEDuUBFhHlC6xbYg1
akcddicTFhNHtwNQ9GFliIaJzU1Mt7LumB03/Cy0A9PouNUhv7QhTmVhbCBELiBC
ZWNrZXIgPG5iZWNrZXJAZnJlZC5uZXQ+iFcEExECABcFAjZa9ZcDCwQDBRUDAgYB
AxYCAQIXgAAKCRCtdGDCLVoO090GAJsFFd/nUF315R0Snt97iV39JP/OTQCeNAaU
5MsmAJHGFcXXj9AkMRoguzu5AQ0ENlr1pRAEAKpFYKuYC++L4RuzreeuKObO15SS
LXgUo0A/q9Hm3VFQw/FaWShBilVKjw6C7lUFnajx0uzy3EhczjitdcHewXyOH/9T
1WyqtiJG9CJTRgQkA1vDSgLBqLQ8so4saOF0bT/66iaiBE9Rbl1yRvjJh5lIULJr
BG2WhHfh/xWl2KS/AAMFBACQ/DrlJe9ooOQAuuUFK8P1A1t4zN5u9gvVMLhpxnr+
KYFa4+GdP3939lRTb7smtVxh9gote66kTmH776sqx7Sn8/Vsx5DOEKpikTlQ9IPR
mXu8Oe9skh+rJcOrjSOH7fSsYqqH7O1GArw0l82bBwA6Xz86vWfyHj/Slo0YXxey
QohGBBgRAgAGBQI2WvWlAAoJEK10YMItWg7TDiEAn3kIiU3z9lbtF4UexjL8zWIv
QszbAJ4om+wo1penO8/y9uI0UOgJQZUtJg==
=Q5Ab
-----END PGP PUBLIC KEY BLOCK-----

[Doxygen-users] New build for OSX, please.

[<jan...@co...>]

hi all

Can anybody make a new  build for OSX, please.
The last binary download is 1.2.8.1 :-( .
Please, I promise that I will test it.

Honza

Re: [Doxygen-users] Getting macro expansion to work

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

On Thu, Oct 11, 2001 at 10:46:09AM +0000, Simon Watts wrote:
> I just cant seem to get a C++ #define'd macro to be expanded before
> documentation.  I have set:
> 
> 	MACRO_EXPANSION = YES
> 	EXPAND_ONLY_PREDEF = YES
> 	EXPAND_AS_DEFINED = ((macros))
> 
> So my EXPAND_AS_DEFINED field is
> 
> 	EXPAND_AS_DEFINED = "ACCESS_STRING(NAME,FIELD,LENGTH)" \
> 	                    "ITERATOR(NAME,TYPE,INFO)"

Please try

EXPAND_AS_DEFINED = ACCESS_STRING ITERATOR

So just macro names without the arguments. This should work.

Regards,
  Dimitri

[Doxygen-users] Doxygen-1.2.11-20011014 in CVS

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

Hi,

The changelog since 1.2.11.1 looks as follows:
----------------------------------------------------------------------------
+ CHG: Improved the speed of the todo/test/bug list generation considerably.
+ ADD: Added new option HIDE_UNDOC_RELATIONS that can be set to NO to show
       any undocumented inheritance and usage relations from the various
       graphs.
+ ADD: Updated the graph legend page.
+ BUG: Fixed more RTF problems and added an RTF integrity check that
       is performed on the generated RTF output (bracket matching).
+ BUG: Refined the macro detection in the preprocessor a little, so it does 
       not match constructors and functions so easily.
+ BUG: the % prefix didn't work for scoped items.
----------------------------------------------------------------------------
Enjoy,
  Dimitri

[Doxygen-users] Handling multiple versions of methods

[Christopher B. <bre...@ya...>]

In the system I'm documenting, several methods come in
multiple versions. I'm replacing an older help system
(done in Robohelp), in which the writer sometimes made
a separate help page for each version, and at other
times made a single page showing the syntaxes for all
versions of the method. I would like to know if other
Dox users have this situation, and what solutions
people have used.

Christopher Brewster

__________________________________________________
Do You Yahoo!?
Make a great connection at Yahoo! Personals.
http://personals.yahoo.com

[Doxygen-users] Divided comments

[Fabian C. <Cen...@in...>]

Hi

I have a problem I thought it isn't :)

Is it possible to have a comment block for a function in the .h as well as 
in the .cpp, both with several infos?

Example:

in Test.h:
... bla bla... file.. class

    /*! \brief Short comment on my function.
       \param P1 That's parameter 1.
    */
    int MyFunc(int P1);


in Test.cpp:
... bla bla... file

    /*! Long comment on my function.
    */
    int MyFunc(int P1) {}

This works without the \param (or anything else) in the header, but as soon 
as I add this or more info, the long comment disappears from the generated 
docu (HTML). I tried from version 1.2.8 to 1.2.11 without success. I used 
the standard config file, except of course INPUT and OUTPUT.

Thank you for a hint.

bye  Fabi

[Doxygen-users] \var how to use?

[<jan...@co...>]

I'm using the doxygen  1.2.8.1 to document some C source.
I tried to attach detailed documentation to  structure member outside of 
the structure definition by using \var, but during compilation doxygen 
complains:

/x.h:95-Warning: documented function `agent_entry_s name Name of the 
agent s child The value is used for invoking the child' was not defined.
  <and likewise for other \var s.>

The piece of code is attached here:

/** structure for keeping the information about agent's child */
struct agent_entry_s{
     char name [MAX_AGENT_NAME];    /**< \brief agent's name */
     char fifo[MAX_AGENT_FIFO];    /**< \brief agent's fifo */
     char dir[MAX_AGENT_DIR];    /**< \brief agent's directory*/

};
/** \var agent_entry_s::name  Name of the agent's child. The value is 
used for invoking the child
*/
/** \var agent_entry_s::fifo Name of the agent's fifo. The agents child 
uses this name to communicate with the agent.
*/
/** \var agent_entry_s::dir The directory where the child is executed
*/


How can i do this?
Thanks
	Honza

Re: [Doxygen-users] Re: Behaviors of `gcc -E -C'

[Patrick O. <Pat...@pa...>]

On Thu, Oct 11, 2001 at 08:27:25PM -0700, Zack Weinberg wrote:
> On Mon, Oct 08, 2001 at 07:10:12PM +0100, Neil Booth wrote:
> > There are various issues with -C which are not good.  It saves
> > comments within a macro expansion, so that each invocation reproduces
> > the comment.
> 
> I don't remember why we tried to do this in the first place.  Until
> someone can remember why, turning them off again seems like a sensible
> plan.

I really like the idea of seeing the comments inside a macro after
expansion, because we are forced to use C and substitute templates
with some heavy use of the preprocessor. Debugging this is a nightmare,
and comments in the expanded code would help a lot.

I have tried it a while ago with egcs 2.91.66, which didn't work all
that well, but it seems that I should give it a second go with a more recent
version. Please, if you can keep this feature alive, then try it -
it is appreciated ;-)

-- 
Freundliche Gruesse / Best Regards

Patrick Ohly
Software Engineer
--------------------------------------------------------------------
//// pallas 
Pallas GmbH / Hermuelheimer Str. 10 / 50321 Bruehl / Germany
Pat...@pa... / www.pallas.com
Tel +49-2232-1896-30 / Fax +49-2232-1896-29
--------------------------------------------------------------------

[Doxygen-users] Re: Behaviors of `gcc -E -C'

[Neil B. <ne...@da...>]

Zack Weinberg wrote:-

> I don't remember why we tried to do this in the first place.  Until
> someone can remember why, turning them off again seems like a sensible
> plan.

The NetBSD project added a -CC option to cccp, which would preserve
comments in macros so that they are output wherever the macro is used,
rather than not at all or only where the macro is defined (I can't
remember what cccp does).  Which seems like a not unreasonable
improvement, to me at least.  Mainline CPP drops comments in
directives completely, even with -C, including #define.

> All very doable.
> 
> I'd kind of like to see directives call a different function from
> cpp_get_token, but for a different reason: right now profiling the
> preprocessor is hindered by the gargantuan recursive cycle between all
> the directive handlers (and their children) and cpp_get_token.  If
> there were an internal version that did do macro expansion but
> didn't do directive processing, and they used it, the cycle would go
> away.

Hmmm.  Directive processing is presently handled at the lexer level
rather than at the get_token / macro expansion level, since the
indicator of a directive is a '#' at the beginning of a logical line.
In other words, it's natural that directive processing can't happen in
directives, because in a directive you're not at the start of the
line.

So I'm not sure there is an clean split like that.

Neil.

[Doxygen-users] Re: Behaviors of `gcc -E -C'

[Zack W. <za...@co...>]

On Mon, Oct 08, 2001 at 07:10:12PM +0100, Neil Booth wrote:
> There are various issues with -C which are not good.  It saves
> comments within a macro expansion, so that each invocation reproduces
> the comment.

I don't remember why we tried to do this in the first place.  Until
someone can remember why, turning them off again seems like a sensible
plan.

> These are fixable, if someone persuades me it's worth retaining the
> comments in macro expansions.  We could convert C++ comments to C
> comments when saving them, and have directives call a new function
> _cpp_get_dtoken that filters out comment tokens.

All very doable.

I'd kind of like to see directives call a different function from
cpp_get_token, but for a different reason: right now profiling the
preprocessor is hindered by the gargantuan recursive cycle between all
the directive handlers (and their children) and cpp_get_token.  If
there were an internal version that did do macro expansion but
didn't do directive processing, and they used it, the cycle would go
away.

zw

[Doxygen-users] \internal

[Bernd G. <be...@ph...>]

Apparently the INTERNAL_DOCS configuration option only affects 
whether documentation in a section with \internal is included
in the documentation. Is it also possible to completely remove
classes from the documentation which are marked as internal?
(i.e. they don't appear in the hierarchy or in the class list).

Bernd.

[Doxygen-users] Re: Getting macro expansion to work

[Simon W. <sim...@ma...>]

...and I should mention that I have ENABLE_PREPROCESSING=YES, and am
including undocumented functions/methods in the output.


Si.


-- 
Simon A Watts
Software Engineer
Marconi Medical Systems
mailto:sim...@ma...
tel: +44(0) 1252 747 311

[Doxygen-users] Getting macro expansion to work

[Simon W. <sim...@ma...>]

I just cant seem to get a C++ #define'd macro to be expanded before
documentation.  I have set:

	MACRO_EXPANSION = YES
	EXPAND_ONLY_PREDEF = YES
	EXPAND_AS_DEFINED = ((macros))

The macros I need to expand expand to inline accessor methods in a
class, each macro giving two or three methods.

I have already set up the build to put all my header files into the
INPUTS config param (massaging g++ -MM output).

The manual section on Preprocessing give examples of the use of
PREDEFINED, but not EXPAND_AS_DEFINED.  

My macros have the form:

#define ACCESS_STRING(NAME,FIELD,LENGTH) \
	string get_ ## NAME () {\
		return string (data.FIELD, LENGTH);\
	}\
	---><8--- similar for set_

#define ITERATOR(NAME,TYPE,INFO) \
	TYPE::iterator begin_ ## NAME () {\
		return begin_tmpl < TYPE > (INFO);\
	}\
	---><8--- similar for end_ and add_

So my EXPAND_AS_DEFINED field is

	EXPAND_AS_DEFINED = "ACCESS_STRING(NAME,FIELD,LENGTH)" \
	                    "ITERATOR(NAME,TYPE,INFO)"

I have checked the C++ pre-processor output, and these are correctly
defined in the resultant .ii file.

In the Doxygen (1.2.1) output, The "ACCESS_STRING" macro appears once or
not at all in the doc (HTML).  Where it appears, it is as a method
without return, eg:

	Patient::ACCESS_STRING (name, p_name, 17)


While the "ITERATOR" macro doesnt appear in the class docs at all.  Both
are documented as macros though.

So, what is confusing Doxygen (pre-processor) here?  



Si.



-- 
Simon A Watts
Software Engineer
Marconi Medical Systems
mailto:sim...@ma...
tel: +44(0) 1252 747 311

RE: [Doxygen-users] Grouping file members

[Dan M. <dm...@Cr...>]

Oops, spoke too quickly. The 1.2.11.1 update did not fix this problem. (I
was confused by the alternate arrangements that I'd made in my own source;
testing with the example below shows no change in behavior.)

But thanks for the update anyway!

> -----Original Message-----
> From: Dan Muller 
> Sent: Monday, October 08, 2001 6:57 PM
> To: 'dox...@li...'
> Subject: RE: [Doxygen-users] Grouping file members
> 
> 
> Dimitri, thanks for the 1.2.11.1 update -- it fixed the 
> problem described below very nicely!
> 
> 
> Dan Muller [mailto:dm...@Cr...] wrote:
> >
> > I'm having trouble getting grouping to work the way I'd 
> > expect for some
> > non-member operators defined in a namespace. Following is a 
> > test case with
> > the same problematic elements as my code. I've actually run 
> this test
> > through doxygen and replicated the problem. I'm using doxygen 
> > 1.2.11 on
> > Win2k Pro.
> > 
> > /**
> >  * @file test.h
> >  * This is the file.
> >  */
> > 
> > /**
> >  * Foo is a namespace.
> >  */
> > namespace Foo {
> >   class TR;
> >   /**
> >    * Docs for Rel
> >    */
> >   class Rel { /*...*/ };
> > 
> >   //@{
> >   /**
> >    * Yadda yadda yadda.
> >    * @param r This is a Rel
> >    * @param t This is a TR.
> >    * @return Returns a result of type Rel.
> >    * @relates Rel
> >    */
> >   Rel operator&&(const Rel& r, const TR& t);
> >   Rel operator&&(const TR& t, const Rel& r);
> >   //@}
> > 
> > }
> > 
> > Because of my build setup, the configuration is built in 
> pieces. I've
> > attached all the parts (test.cfg is the file actually given 
> > to doxygen on
> > the command line). The parts of my config which I think might 
> > be relevant
> > are:
> > 
> > EXTRACT_ALL     = NO
> > HIDE_UNDOC_CLASSES = YES
> > HIDE_UNDOC_MEMBERS = YES
> > DISTRIBUTE_GROUP_DOC = YES
> > 
> > My situation seems to correspond to the last part of the last 
> > example in the
> > "Grouping" section of the doxygen manual. But the behavior 
> > doesn't seem to
> > match what's described there. I tried changing the operators 
> > to regular
> > functions, but that doesn't help.
> > 
> > I'd really like a single documentation block in the HTML 
> > output that applies
> > to both variations of the operator&&, since they do the same 
> > thing, but
> > showing both prototypes so the reader can see the symmetry 
> > that's provided.
> > I'd settle for each prototype listed separately with the 
> documentation
> > replicated. But the second operator prototype seems to be ignored by
> > doxygen. If I omit @relates, then i get the latter behavior 
> > (two entries
> > with replicated docs), but on the namespace page. 
> > 
> > Any suggestions? Is @relates just incompatible with grouping? 
> > Is there any
> > way to get the kind of grouping I'd actually like, i.e. 
> > multiple function
> > prototypes documented together?
> > 
> > 
> >  <<all.doxy>>  <<CsiDb.doxy>>  <<test.cfg>> 
> > 
> 

RE: [Doxygen-users] Grouping file members

[Dan M. <dm...@Cr...>]

Dimitri, thanks for the 1.2.11.1 update -- it fixed the problem described
below very nicely!


Dan Muller [mailto:dm...@Cr...] wrote:
>
> I'm having trouble getting grouping to work the way I'd 
> expect for some
> non-member operators defined in a namespace. Following is a 
> test case with
> the same problematic elements as my code. I've actually run this test
> through doxygen and replicated the problem. I'm using doxygen 
> 1.2.11 on
> Win2k Pro.
> 
> /**
>  * @file test.h
>  * This is the file.
>  */
> 
> /**
>  * Foo is a namespace.
>  */
> namespace Foo {
>   class TR;
>   /**
>    * Docs for Rel
>    */
>   class Rel { /*...*/ };
> 
>   //@{
>   /**
>    * Yadda yadda yadda.
>    * @param r This is a Rel
>    * @param t This is a TR.
>    * @return Returns a result of type Rel.
>    * @relates Rel
>    */
>   Rel operator&&(const Rel& r, const TR& t);
>   Rel operator&&(const TR& t, const Rel& r);
>   //@}
> 
> }
> 
> Because of my build setup, the configuration is built in pieces. I've
> attached all the parts (test.cfg is the file actually given 
> to doxygen on
> the command line). The parts of my config which I think might 
> be relevant
> are:
> 
> EXTRACT_ALL     = NO
> HIDE_UNDOC_CLASSES = YES
> HIDE_UNDOC_MEMBERS = YES
> DISTRIBUTE_GROUP_DOC = YES
> 
> My situation seems to correspond to the last part of the last 
> example in the
> "Grouping" section of the doxygen manual. But the behavior 
> doesn't seem to
> match what's described there. I tried changing the operators 
> to regular
> functions, but that doesn't help.
> 
> I'd really like a single documentation block in the HTML 
> output that applies
> to both variations of the operator&&, since they do the same 
> thing, but
> showing both prototypes so the reader can see the symmetry 
> that's provided.
> I'd settle for each prototype listed separately with the documentation
> replicated. But the second operator prototype seems to be ignored by
> doxygen. If I omit @relates, then i get the latter behavior 
> (two entries
> with replicated docs), but on the namespace page. 
> 
> Any suggestions? Is @relates just incompatible with grouping? 
> Is there any
> way to get the kind of grouping I'd actually like, i.e. 
> multiple function
> prototypes documented together?
> 
> 
>  <<all.doxy>>  <<CsiDb.doxy>>  <<test.cfg>> 
> 

[Doxygen-users] Re: Behaviors of `gcc -E -C'

[Neil B. <ne...@da...>]

There are various issues with -C which are not good.  It saves
comments within a macro expansion, so that each invocation reproduces
the comment.

This is nice, except that it doesn't work with C++ comments, since
stuff later on the line can be commented out (doh!) and it doesn't
work in directives, which don't expect comments as tokens.

These are fixable, if someone persuades me it's worth retaining the
comments in macro expansions.  We could convert C++ comments to C
comments when saving them, and have directives call a new function
_cpp_get_dtoken that filters out comment tokens.

What do you think, Zack?

In the meantime, I'm going to bootstrap the patch below, which turns
off saving comments in macro expansions, and if all is OK commit it.

As for 3.0.2, this patch plus a one-liner to fix the bug you mentioned
about comments in skipped blocks being output could be applied.  I'll
see what Mark thinks RSN.

Neil.

	* cppmacro.c (_cpp_create_definition): Leave comments off.

Index: cppmacro.c
===================================================================
RCS file: /cvs/gcc/gcc/gcc/cppmacro.c,v
retrieving revision 1.79
diff -u -p -r1.79 cppmacro.c
--- cppmacro.c	2001/10/08 06:15:13	1.79
+++ cppmacro.c	2001/10/08 18:02:46
@@ -1329,7 +1329,6 @@ _cpp_create_definition (pfile, node)
   else if (ctoken->type != CPP_EOF && !(ctoken->flags & PREV_WHITE))
     cpp_pedwarn (pfile, "ISO C requires whitespace after the macro name");
 
-  pfile->state.save_comments = ! CPP_OPTION (pfile, discard_comments);
   saved_cur_token = pfile->cur_token;
 
   if (macro->fun_like)
Index: doc/cpp.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/cpp.texi,v
retrieving revision 1.14
diff -u -p -r1.14 cpp.texi
--- cpp.texi	2001/09/24 22:53:10	1.14
+++ cpp.texi	2001/10/08 18:03:06
@@ -4228,15 +4228,11 @@ linemarkers.  @xref{Preprocessor Output}
 @item -C
 Do not discard comments.  All comments are passed through to the output
 file, except for comments in processed directives, which are deleted
-along with the directive.  Comments appearing in the expansion list of a
-macro will be preserved, and appear in place wherever the macro is
-invoked.
+along with the directive.
 
-You should be prepared for side effects when using @option{-C}; it causes
-the preprocessor to treat comments as tokens in their own right.  For
-example, macro redefinitions that were trivial when comments were
-replaced by a single space might become significant when comments are
-retained.  Also, comments appearing at the start of what would be a
+You should be prepared for side effects when using @option{-C}; it
+causes the preprocessor to treat comments as tokens in their own right.
+For example, comments appearing at the start of what would be a
 directive line have the effect of turning that line into an ordinary
 source line, since the first token on the line is no longer a @samp{#}.