On 13/08/14 14:49, Vadim Zeitlin wrote:
On Tue, 12 Aug 2014 19:19:33 +0100 William S Fulton <wsf@fultondesigns.co.uk> wrote:

WSF> Isn't there any way to process/tweak/transform/control in some way the
WSF> doxygen comments other than by command line options?

  Sorry, I'm not sure what do you mean. Currently there is no way to tweak
the comments at all, neither by command line options nor in any other way.

WSF> I'd imagine there are plenty of ways that a user might want to modify
WSF> the comments, other than a simple use or ignore all of the comment.
WSF> There ought to be a generic doxygen feature matching to do comment
WSF> customisations. I'd imagine it would use SWIG's %feature, or something
WSF> akin to it, so that customisations can be done on a per symbol level.

  How would this work, exactly? Even taking the simplest possible example in
which we'd like to exclude some part of the comment which is C++-specific
from Python documentation, how could you possibly describe what needs to be
done using SWIG %feature? I just don't see it...

WSF> Do you know if there is much documentation for users?

  Well, there is

        https://github.com/vadz/swig/blob/doxygen/Doc/Manual/Doxygen.html

but it doesn't say anything about this because nothing like this currently
exists.

  The only thing you can do right now is, indeed, to "ignore all of the
comment" by using (Python-specific, I don't think anything like this exists
for Java) %feature("docstring") to override it.

  Please let me know if I completely missed your point (which is the
impression I have right now...).

There are features documented such as "doxygen:nolinktranslate" and "doxygen:nostripparams" "doxygen:notranslate" to transform and modify the doxygen comments. These look like standard SWIG features, so could be used like:

%feature("doxygen:nolinktranslate") Klass::Method;

hence targetting individual or global symbols (as SWIG features were designed to do).

A generic doxygen tag ignore could be implemented:

%feature("doxygen:ignoretag", "pythononly:endpythononly");

This is be a global feature, so would apply globally, but you could equally well get it to filter out specific tags on specific symbols, such as hiding the authors for a particular function:

%feature("doxygen:ignoretag", "authors") Klass::Method;

As some tags have a start and an end and some do not, I suggest using something like ":" to indicate the tag is a begin...end type tag, such as "pythononly:endpythononly" above.

William