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