doxygen-users

RE: [Doxygen-users] Multiple comments -combining

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

You might be able to get this to work if you added a prototype line to
the description to force the comment to go where you want. The only
problem with this is that the line with the prototype has to be
maintained. If you change your code without changing this line, it will
break.

For example, assume that you have a class with a member function
HHH::bogus(int doofus) defined. It appears in the header and source
file. Let's assume that you want the source file to be the "master". To
any comment blocks in the header file that are to appear with the
"master" documentation in the source file, you would add at the
beginning:

// h file
/** @fn bogus(int doofus)
 ** Additional comments about bogus.
 ** More comments about bogus.
 **/
HHH::bogus(int)

// cpp file
/** @brief this is all about bogus.
 ** @param doofus is not important.
 **/
HHH::bogus(int doofus)

I may have this backwards in terms of what you have to use as the
master.

I do know that by adding a prototype statement to a comment block, I can
"route" the comment from the closest, logical code element to another
code element that was defined.

I'm not sure how this will work when you want it to go to essentially
the same thing. This is why something "non-standard" might help. If you
cpp file had the complete definition including variable name but your h
file only had the variable type, the @fn prototype statement won't be
confused as to where it belongs.

The two obvious problems are: (1) your h/cpp definitions differ, (2)
your adding another prototype definition that has to be maintained.

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: jan...@co...
> [mailto:jan...@co...]
> Sent: Wednesday, November 14, 2001 8:27 AM
> To: dox...@li...
> Subject: [Doxygen-users] Multiple comments -combining
>=20
>=20
> Hi All
>=20
> Is there any possibility to join multiple comments into one=20
> description?
> I would like to have possibility to add the comments in header and in=20
> source code.
> The rule that only one description is allowed is pretty limiting :-(.
> I agree with the rule of only one brief description, but the detailed=20
> description should be possible to expand.
> For example I would like to add some comments to the source=20
> code that is=20
> not my and I want to have comments in separated file.
> If the consistency would be an issue there can be option in=20
> Doxyfile to=20
> turn this thing on/off.
>=20
> Thanks
>=20
> 	Honza
>=20
>=20
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>=20

RE: [Doxygen-users] Multiple comments -combining

[Wagner, V. <VW...@se...>]

If this were to be implemented (and it looks like the start of a pretty good
idea), I would like to see the comments from the source code being
optionally added.  I reason thusly:

The header file is "public".  Everyone who has access to it can read the
comments there if desired.
The implementation file (.c, .cpp, whatever) is generally information for
the developers.  Not everyone has access to this file.
At our office we generate two versions of Doxygen output... one for "users"
the other for "developers".
The ability to add information to the comments _must_, IMO, be selectable.

For generality here, I offer three different possibilities, two of which
require the comments processor to be given a new optional numeric argument.

1) the config file adds a numeric value which (if the 'number' on the
comments is < than the config, the comments will be added).  I choose
smaller, so that you can add more and more 'secret' comments to your hearts
content.

2) the config file adds a numeric value which if ANDED with the comment
argument results in a non-zero value, the comments will be added.  This
would allow for a set of up to (32??) "classes" of elements which could be
arbitrarily selected.

3) pretty complete generality:  Change the comments processor to accept an
arbitrary list of "ID"s to identify the "class"(es) to which this comment
belongs.  The config would also add an arbitrary list of "ID"s to identify
which "class"(es) of comments to include.


-----Original Message-----
From: jan...@co...
[mailto:jan...@co...]
Sent: Wednesday, 2001 November 14 10:27
To: dox...@li...
Subject: [Doxygen-users] Multiple comments -combining


Hi All

Is there any possibility to join multiple comments into one description?
I would like to have possibility to add the comments in header and in 
source code.
The rule that only one description is allowed is pretty limiting :-(.
I agree with the rule of only one brief description, but the detailed 
description should be possible to expand.
For example I would like to add some comments to the source code that is 
not my and I want to have comments in separated file.
If the consistency would be an issue there can be option in Doxyfile to 
turn this thing on/off.

Thanks

	Honza


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

RE: [Doxygen-users] Multiple comments -combining

[Stephen G. <ste...@el...>]

The simple combining of comments is a feature that I'd certainly use.

As others (eg, Victor Wagner) do, we generate two lots of documentation
from the sources for one library - one set from the public headers,
detailing the API and examples for users, one with all the
implementation detail for maintainers.

We decide what files are read for each set of docs by which directories
are scanned by Doxygen (so there are two Doxygen configuration files).
So to selectively add in comments one just has to decide which directory
to put them into: the configuration files I write basically discourage
putting public headers files and private implementation files into the
same directory. You could get the same effect by writing the
configuration files to match the specifics of your code: anything that
lets you list the public files in one config and then all the files in
the other config (continue for however many sets of docs you want to
generate).

I guess I'm saying I don't understand the need for the additional
complexity of the scheme as described by Victor: perhaps some
explanation as to why the existing mechanisms for selectively including
comments (by selecting files) aren't enough if Doxygen just gains a
simple ability to combine comments.

Stephen Goudge


> -----Original Message-----
> From: dox...@li...
> [mailto:dox...@li...] On Behalf
> Of Wagner, Victor
> Sent: 14 November 2001 16:37
> To: 'jan...@co...';
> dox...@li...
> Subject: RE: [Doxygen-users] Multiple comments -combining
>
>
> If this were to be implemented (and it looks like the start
> of a pretty good idea), I would like to see the comments from
> the source code being optionally added.  I reason thusly:
>
> The header file is "public".  Everyone who has access to it
> can read the comments there if desired. The implementation
> file (.c, .cpp, whatever) is generally information for the
> developers.  Not everyone has access to this file. At our
> office we generate two versions of Doxygen output... one for
> "users" the other for "developers". The ability to add
> information to the comments _must_, IMO, be selectable.
>
> For generality here, I offer three different possibilities,
> two of which require the comments processor to be given a new
> optional numeric argument.
>
> 1) the config file adds a numeric value which (if the
> 'number' on the comments is < than the config, the comments
> will be added).  I choose smaller, so that you can add more
> and more 'secret' comments to your hearts content.
>
> 2) the config file adds a numeric value which if ANDED with
> the comment argument results in a non-zero value, the
> comments will be added.  This would allow for a set of up to
> (32??) "classes" of elements which could be arbitrarily selected.
>
> 3) pretty complete generality:  Change the comments processor
> to accept an arbitrary list of "ID"s to identify the
> "class"(es) to which this comment belongs.  The config would
> also add an arbitrary list of "ID"s to identify which
> "class"(es) of comments to include.
>
>
> -----Original Message-----
> From: jan...@co...
> [mailto:jan...@co...]
> Sent: Wednesday, 2001
> November 14 10:27
> To: dox...@li...
> Subject: [Doxygen-users] Multiple comments -combining
>
>
> Hi All
>
> Is there any possibility to join multiple comments into one
> description? I would like to have possibility to add the
> comments in header and in source code. The rule that only one
> description is allowed is pretty limiting :-(. I agree with
> the rule of only one brief description, but the detailed
> description should be possible to expand. For example I would
> like to add some comments to the source code that is not my
> and I want to have comments in separated file. If the
> consistency would be an issue there can be option in Doxyfile
> to turn this thing on/off.
>
> Thanks
>
> 	Honza
>
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>

Re: [Doxygen-users] Multiple comments -combining

[Ted D. <ted...@ea...>]

It seems to me that this is already available.  Use the doxygen
preprocessor option and it becomes very easy to do all these things.  I've
written several python scripts that filter comments based on different
conditions.  Based on different tags in the comments (which I defined),
the script either passes the comment through to doxygen or removes the
doxygen prefix so that the comment is skipped.  When developers write the
comments, they insert the tags depending on who the audience is for the
comments.  You can even have multiple sections in the comments that are
passed through or removed depending on the flags.  This isn't very hard so
I don't think there's any need to change doxygen at all.  

In fact my project was using a different doc tool (perceps) in which we
defined our own commenting style that was expressive enough for our needs,
extremely easy to write, and without long and complicated code words so
that it's easy to read in the source files.  When we discovered doxygen,
which is a much superior tool, we switched.  Rather that convert our
commenting style (which we really liked), I wrote a python script that
converts our comment format into what doxygen expects and set it is the
doxygen preprocessor.  It was very simple to do and allows us to define
our own commenting style.

Ted

On Thu, 15 Nov 2001 08:13:10 -0000
"Stephen Goudge" <ste...@el...> wrote:

> The simple combining of comments is a feature that I'd certainly use.
> 
> As others (eg, Victor Wagner) do, we generate two lots of documentation
> from the sources for one library - one set from the public headers,
> detailing the API and examples for users, one with all the
> implementation detail for maintainers.
> 
> We decide what files are read for each set of docs by which directories
> are scanned by Doxygen (so there are two Doxygen configuration files).
> So to selectively add in comments one just has to decide which directory
> to put them into: the configuration files I write basically discourage
> putting public headers files and private implementation files into the
> same directory. You could get the same effect by writing the
> configuration files to match the specifics of your code: anything that
> lets you list the public files in one config and then all the files in
> the other config (continue for however many sets of docs you want to
> generate).
> 
> I guess I'm saying I don't understand the need for the additional
> complexity of the scheme as described by Victor: perhaps some
> explanation as to why the existing mechanisms for selectively including
> comments (by selecting files) aren't enough if Doxygen just gains a
> simple ability to combine comments.
> 
> Stephen Goudge
> 
> 
> > -----Original Message-----
> > From: dox...@li...
> > [mailto:dox...@li...] On Behalf
> > Of Wagner, Victor
> > Sent: 14 November 2001 16:37
> > To: 'jan...@co...';
> > dox...@li...
> > Subject: RE: [Doxygen-users] Multiple comments -combining
> >
> >
> > If this were to be implemented (and it looks like the start
> > of a pretty good idea), I would like to see the comments from
> > the source code being optionally added.  I reason thusly:
> >
> > The header file is "public".  Everyone who has access to it
> > can read the comments there if desired. The implementation
> > file (.c, .cpp, whatever) is generally information for the
> > developers.  Not everyone has access to this file. At our
> > office we generate two versions of Doxygen output... one for
> > "users" the other for "developers". The ability to add
> > information to the comments _must_, IMO, be selectable.
> >
> > For generality here, I offer three different possibilities,
> > two of which require the comments processor to be given a new
> > optional numeric argument.
> >
> > 1) the config file adds a numeric value which (if the
> > 'number' on the comments is < than the config, the comments
> > will be added).  I choose smaller, so that you can add more
> > and more 'secret' comments to your hearts content.
> >
> > 2) the config file adds a numeric value which if ANDED with
> > the comment argument results in a non-zero value, the
> > comments will be added.  This would allow for a set of up to
> > (32??) "classes" of elements which could be arbitrarily selected.
> >
> > 3) pretty complete generality:  Change the comments processor
> > to accept an arbitrary list of "ID"s to identify the
> > "class"(es) to which this comment belongs.  The config would
> > also add an arbitrary list of "ID"s to identify which
> > "class"(es) of comments to include.
> >
> >
> > -----Original Message-----
> > From: jan...@co...
> > [mailto:jan...@co...]
> > Sent: Wednesday, 2001
> > November 14 10:27
> > To: dox...@li...
> > Subject: [Doxygen-users] Multiple comments -combining
> >
> >
> > Hi All
> >
> > Is there any possibility to join multiple comments into one
> > description? I would like to have possibility to add the
> > comments in header and in source code. The rule that only one
> > description is allowed is pretty limiting :-(. I agree with
> > the rule of only one brief description, but the detailed
> > description should be possible to expand. For example I would
> > like to add some comments to the source code that is not my
> > and I want to have comments in separated file. If the
> > consistency would be an issue there can be option in Doxyfile
> > to turn this thing on/off.
> >
> > Thanks
> >
> > 	Honza
> >
> >
> > _______________________________________________
> > Doxygen-users mailing list
> > Dox...@li...
> > https://lists.sourceforge.net/lists/listinfo/doxygen-users
> >
> > _______________________________________________
> > Doxygen-users mailing list
> > Dox...@li...
> > https://lists.sourceforge.net/lists/listinfo/doxygen-users
> >
> >
> 
> 
> 
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users

RE: [Doxygen-users] Multiple comments -combining

[Stephen G. <ste...@el...>]

Preprocessing like that does eliminate any need to change Doxygen to add
in any form of 'priority' or selecting comments based on conditions,
_but_ how do you propose that the comments are combined once the
pre-processing step has decided which ones to pass on to Doxygen and
which ones to eliminate?

What you describe will let you choose that comments are passed through,
but aren't you still left with the original question from Jan, that you
could have selected a comment sitting in the header and also one sitting
in the main source code and these will fight rather than just being
joined together?

Aside: If the script just "removes the doxygen prefix" but leaves the
bulk of the comment in place won't it just disappear from the formatted
documentation but re-appear in the copy of the source code that Doxygen
generates? Would the result be neater if the script just eliminated the
comment entirely?

Stephen Goudge

> -----Original Message-----
> From: dox...@li...
> [mailto:dox...@li...] On Behalf
> Of Ted Drain
> Sent: 15 November 2001 16:45
> To: Stephen Goudge
> Cc: dox...@li...
> Subject: Re: [Doxygen-users] Multiple comments -combining
>
>
> It seems to me that this is already available.  Use the
> doxygen preprocessor option and it becomes very easy to do
> all these things.  I've written several python scripts that
> filter comments based on different conditions.  Based on
> different tags in the comments (which I defined), the script
> either passes the comment through to doxygen or removes the
> doxygen prefix so that the comment is skipped.  When
> developers write the comments, they insert the tags depending
> on who the audience is for the comments.  You can even have
> multiple sections in the comments that are passed through or
> removed depending on the flags.  This isn't very hard so I
> don't think there's any need to change doxygen at all.
>
<snip>
>
> Ted
>
> On Thu, 15 Nov 2001 08:13:10 -0000
> "Stephen Goudge" <ste...@el...> wrote:
>
> > The simple combining of comments is a feature that I'd
> certainly use.
> >
> > As others (eg, Victor Wagner) do, we generate two lots of
> > documentation from the sources for one library - one set from the
> > public headers, detailing the API and examples for users,
> one with all
> > the implementation detail for maintainers.
> >
> > We decide what files are read for each set of docs by which
> > directories are scanned by Doxygen (so there are two Doxygen
> > configuration files). So to selectively add in comments one
> just has
> > to decide which directory to put them into: the
> configuration files I
> > write basically discourage putting public headers files and private
> > implementation files into the same directory. You could get
> the same
> > effect by writing the configuration files to match the specifics of
> > your code: anything that lets you list the public files in
> one config
> > and then all the files in the other config (continue for
> however many
> > sets of docs you want to generate).
> >
<snip>
> >
> > Stephen Goudge
> >
<snip>
> > >
> > > -----Original Message-----
> > > From: jan...@co...
> > > [mailto:jan...@co...]
> > > Sent: Wednesday, 2001
> > > November 14 10:27
> > > To: dox...@li...
> > > Subject: [Doxygen-users] Multiple comments -combining
> > >
> > >
> > > Hi All
> > >
> > > Is there any possibility to join multiple comments into one
> > > description? I would like to have possibility to add the
> comments in
> > > header and in source code. The rule that only one description is
> > > allowed is pretty limiting :-(. I agree with the rule of only one
> > > brief description, but the detailed description should be
> possible
> > > to expand. For example I would like to add some comments to the
> > > source code that is not my and I want to have comments in
> separated
> > > file. If the consistency would be an issue there can be option in
> > > Doxyfile to turn this thing on/off.
> > >
> > > Thanks
> > >
> > > 	Honza
> > >

Re: [Doxygen-users] Multiple comments -combining

[Ted D. <ted...@ea...>]

You're right, it doesn't help if you have two sets of comments in
different places.  I hadn't actually read that far down the email.  If the
HTML is the primary documentation source, you could combine these
different blocks into blocks in one location and then use a script to
filter them.  If you MUST have the comments in two locations, it doesn't
seem like there's a good way to deal w/ this short of modifying doxygen.

Ted

On Thu, 15 Nov 2001 17:45:29 -0000
"Stephen Goudge" <ste...@el...> wrote:

> Preprocessing like that does eliminate any need to change Doxygen to add
> in any form of 'priority' or selecting comments based on conditions,
> _but_ how do you propose that the comments are combined once the
> pre-processing step has decided which ones to pass on to Doxygen and
> which ones to eliminate?
> 
> What you describe will let you choose that comments are passed through,
> but aren't you still left with the original question from Jan, that you
> could have selected a comment sitting in the header and also one sitting
> in the main source code and these will fight rather than just being
> joined together?
> 
> Aside: If the script just "removes the doxygen prefix" but leaves the
> bulk of the comment in place won't it just disappear from the formatted
> documentation but re-appear in the copy of the source code that Doxygen
> generates? Would the result be neater if the script just eliminated the
> comment entirely?
> 
> Stephen Goudge
> 
> > -----Original Message-----
> > From: dox...@li...
> > [mailto:dox...@li...] On Behalf
> > Of Ted Drain
> > Sent: 15 November 2001 16:45
> > To: Stephen Goudge
> > Cc: dox...@li...
> > Subject: Re: [Doxygen-users] Multiple comments -combining
> >
> >
> > It seems to me that this is already available.  Use the
> > doxygen preprocessor option and it becomes very easy to do
> > all these things.  I've written several python scripts that
> > filter comments based on different conditions.  Based on
> > different tags in the comments (which I defined), the script
> > either passes the comment through to doxygen or removes the
> > doxygen prefix so that the comment is skipped.  When
> > developers write the comments, they insert the tags depending
> > on who the audience is for the comments.  You can even have
> > multiple sections in the comments that are passed through or
> > removed depending on the flags.  This isn't very hard so I
> > don't think there's any need to change doxygen at all.
> >
> <snip>
> >
> > Ted
> >
> > On Thu, 15 Nov 2001 08:13:10 -0000
> > "Stephen Goudge" <ste...@el...> wrote:
> >
> > > The simple combining of comments is a feature that I'd
> > certainly use.
> > >
> > > As others (eg, Victor Wagner) do, we generate two lots of
> > > documentation from the sources for one library - one set from the
> > > public headers, detailing the API and examples for users,
> > one with all
> > > the implementation detail for maintainers.
> > >
> > > We decide what files are read for each set of docs by which
> > > directories are scanned by Doxygen (so there are two Doxygen
> > > configuration files). So to selectively add in comments one
> > just has
> > > to decide which directory to put them into: the
> > configuration files I
> > > write basically discourage putting public headers files and private
> > > implementation files into the same directory. You could get
> > the same
> > > effect by writing the configuration files to match the specifics of
> > > your code: anything that lets you list the public files in
> > one config
> > > and then all the files in the other config (continue for
> > however many
> > > sets of docs you want to generate).
> > >
> <snip>
> > >
> > > Stephen Goudge
> > >
> <snip>
> > > >
> > > > -----Original Message-----
> > > > From: jan...@co...
> > > > [mailto:jan...@co...]
> > > > Sent: Wednesday, 2001
> > > > November 14 10:27
> > > > To: dox...@li...
> > > > Subject: [Doxygen-users] Multiple comments -combining
> > > >
> > > >
> > > > Hi All
> > > >
> > > > Is there any possibility to join multiple comments into one
> > > > description? I would like to have possibility to add the
> > comments in
> > > > header and in source code. The rule that only one description is
> > > > allowed is pretty limiting :-(. I agree with the rule of only one
> > > > brief description, but the detailed description should be
> > possible
> > > > to expand. For example I would like to add some comments to the
> > > > source code that is not my and I want to have comments in
> > separated
> > > > file. If the consistency would be an issue there can be option in
> > > > Doxyfile to turn this thing on/off.
> > > >
> > > > Thanks
> > > >
> > > > 	Honza
> > > >
> 
> 
> 
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users