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