Re: [Swig-devel] Fwd: RFD: How to handle C++ specific parts of Doxygen comments?

[William S F. <ws...@fu...>]

On 22 August 2014 18:28, Vadim Zeitlin <vz...@ze...> wrote:

> On Wed, 20 Aug 2014 22:24:20 +0100 William S Fulton <
> ws...@fu...> wrote:
>
> WSF> A generic doxygen tag ignore could be implemented:
> WSF>
> WSF> %feature("doxygen:ignoretag", "pythononly:endpythononly");
>
>  Perhaps I'm not grasping completely how does %feature work, but AFAICS
> this is not ideal because I want to be able to ignore multiple tags but
> the next occurrence of %feature would overwrite the previous one. So it
> seems to me that we'd rather need an uglier
>
>         %feature("doxygen:ignore:tag1");
>         %feature("doxygen:ignore:tag2");
>
>  We could still also have
>
>         %feature("doxygen:ignore:begintag:endtag");
>
> of course, but I don't see how could we use the same feature name for
> different tags, am I missing anything?
>
> Not at all. I overlooked the need to ignore multiple tags.

We could take the same approach as %warnfilter and use a comma separated
list. Some examples:

        %feature("doxygen:ignore", "tag1");
        %feature("doxygen:ignore", "tag2");
        %feature("doxygen:ignore", "tag1,tag2");

        %feature("doxygen:ignore", "begintag:endtag,tag1,tag2");

But then it isn't too user friendly with regard to adding in multiple tag
ignores, as you'd have to build up the list of tags to ignore if you want
to handle a particular symbol differently to say a global rule. Overall,
this is probably no good.

The problem with the syntax you suggested, is that the feature names are
not variable, I'm pretty sure they are all known at compile time. If we
introduce a variable number of names, we'd need add in some support
functions to get the list of all the feature:doxygen:xxxx. Probably this
isn't a big deal because I'd presume the list of tags attached to each node
is somehow stored elsewhere, so you could iterate through them all calling
Getattr("feature:doxygen:" + tagname). But for tags that have a start and
an end, then you'd need to a variable name lookup. We could circumvent this
problem, by using alternative syntax, such as:

        %feature("doxygen:ignore:begintag", end="endtag");

This results in the following in the parse tree:

| feature:doxygen:ignore:begintag:end - "endtag"
| feature:doxygen:ignore:begintag - "1"

so if Getattr("feature:ignore:" + tagname) works, you can call
Getattr("feature:ignore" + tagname + ":end") to get the name of the end tag.

Putting this into a macro is probably the way forward:

#define %doxygenignore(TAG) %feature("doxygen:ignore:" ## TAG)

and I think with some vararg macro jiggery pokery, you can add in the
optional end attribute.

William