Add a possibility to flexibly ignore custom Doxygen tags.

Add %feature("doxygen:ignore:<command>") implementation, documentation and
test case.

This feature allows to use custom tags in C++ Doxygen comments for
C++-specific things that don't make sense in the context of the target
language and also allows to insert contents specific to the target language in
the C++ comments using (different) custom commands, which is very useful in
practice to explain the particularities of the API wrappers.

Examples/test-suite/common.mk

@@ -551,6 +551,7 @@ $(eval HAS_DOXYGEN := $($(LANGUAGE)_HAS_DOXYGEN))
 ifdef HAS_DOXYGEN
 DOXYGEN_TEST_CASES += \
 	doxygen_parsing \
+	doxygen_ignore \
 	doxygen_basic_translate \
 	doxygen_basic_notranslate \
 	doxygen_translate \

Examples/test-suite/doxygen_ignore.i

@@ -0,0 +1,41 @@
+%module doxygen_ignore
+
+%feature("doxygen:ignore:transferfull");
+%feature("doxygen:ignore:compileroptions", range="line");
+%feature("doxygen:ignore:forcpponly", range="end");
+
+#ifdef SWIGJAVA
+%feature("doxygen:ignore:beginJavaOnly", range="end:endJavaOnly", contents="parse");
+%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly");
+#elif defined(SWIGPYTHON)
+%feature("doxygen:ignore:beginJavaOnly", range="end:endJavaOnly");
+%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse");
+#else
+%feature("doxygen:ignore:beginJavaOnly", range="end:endJavaOnly");
+%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly");
+#endif
+
+%inline %{
+
+/**
+    A contrived example of ignoring too many commands in one comment.
+
+    @forcpponly
+    This is C++-specific.
+    @endforcpponly
+
+    @beginJavaOnly
+    This is specific to @e Java.
+    @endJavaOnly
+
+    @beginPythonOnly
+    This is specific to @b Python.
+    @endPythonOnly
+
+    @transferfull Command ignored, but anything here is still included.
+
+    @compileroptions This function must be compiled with /EHa when using MSVC.
+ */
+void func() { }
+
+%}

Examples/test-suite/java/doxygen_ignore_runme.java

@@ -0,0 +1,44 @@
+
+import doxygen_ignore.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_ignore_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_ignore");
+    } catch (UnsatisfiedLinkError e) {
+      System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e);
+      System.exit(1);
+    }
+  }
+
+  public static void main(String argv[]) 
+  {
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_ignore runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_ignore"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    wantedComments.put("doxygen_ignore.doxygen_ignore.func()",
+      "     A contrived example of ignoring too many commands in one comment.<br>\n" +
+      " <br>\n" +
+      "     <br>\n" +
+      " <br>\n" +
+      "     <br>\n" +
+      "     This is specific to <i>Java</i>.<br>\n" +
+      "     <br>\n" +
+      " <br>\n" +
+      "     <br>\n" +
+      " <br>\n" +
+      "     Command ignored, but anything here is still included.<br>\n" +
+      " <br>\n" +
+      "\n" +
+      "\n" +
+      "\n" +
+      "");
+
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/python/doxygen_ignore_runme.py

@@ -0,0 +1,21 @@
+#!/usr/bin/python
+
+import doxygen_ignore
+import commentVerifier
+
+commentVerifier.check(doxygen_ignore.func.__doc__,
+    r"""
+    A contrived example of ignoring too many commands in one comment.
+
+
+
+
+
+
+    This is specific to **Python**.
+
+
+    Command ignored, but anything here is still included.
+
+
+    """)