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