Add support for doxygen:alias feature

This allows to replace non-standard Doxygen commands with some (fixed) text
instead of just ignoring them, as was already possible with the feature
doxygen:ignore.

Doc/Manual/Doxygen.html

@@ -226,13 +226,58 @@ instead of the corresponding language tool (<tt>javadoc</tt>, <tt>sphinx</tt>,
 </p>
 
 
+<h4>doxygen:alias:&lt;command-name&gt;</h4>
+
+<p>
+Specify an alias for a Doxygen command with the given name. This can be useful
+for custom Doxygen commands which can be defined using <tt>ALIASES</tt> option
+for Doxygen itself but which are unknown to SWIG. <tt>"command-name"</tt> is the
+name of the command in the Doxyfile, e.g. if it contains
+</p>
+
+<div class="code"><pre>
+ALIASES = "sideeffect=\par Side Effects:\n"
+</pre></div>
+
+<p>
+Then you could also the same expansion for SWIG with:
+</p>
+
+<div class="code"><pre>
+%feature("doxygen:alias:sideeffect") "\par Side Effects:\n"
+</pre></div>
+
+<p>
+Please note that command arguments are not currently supported with this
+feature.
+</p>
+
+<p>
+Notice that it is perfectly possible and potentially useful to define the alias
+expansion differently depending on the target language, e.g. with
+</p>
+
+<div class="code"><pre>
+#ifdef SWIGJAVA
+%feature("doxygen:alias:not_for_java") "This functionality is not available for Java"
+#else
+%feature("doxygen:alias:not_for_java") ""
+#endif
+</pre></div>
+
+<p>
+you could use <tt>@not_for_java</tt> in the documentation comments of all
+functions which can't, for whatever reason, be currently exposed in Java
+wrappers of the C++ API.
+</p>
+
+
 <h4>doxygen:ignore:&lt;command-name&gt;</h4>
 
 <p>
-Specify that the Doxygen command with the given name should be ignored. This is
+This feature allows to just ignore an unknown Doxygen command, instead of
-useful for custom Doxygen commands which can be defined using <tt>ALIASES</tt>
+replacing it with a predefined text as <tt>doxygen:alias</tt> features allows to
-option for Doxygen itself but which are unknown to SWIG. <tt>"command-name"</tt>
+do. For example, you could use
-is the real name of the command, e.g. you could use
 </p>
 
 <div class="code"><pre>

Examples/test-suite/common.mk

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

Examples/test-suite/doxygen_alias.i

@@ -0,0 +1,22 @@
+%module doxygen_alias
+
+#ifdef SWIGJAVA
+%feature("doxygen:alias:nullptr") "null"
+#elif defined(SWIGPYTHON)
+%feature("doxygen:alias:nullptr") "None"
+#else
+%feature("doxygen:alias:nullptr") "NULL"
+#endif
+
+%inline %{
+
+class Something {};
+
+/**
+    A function returning something.
+
+    @returns A new object which may be @nullptr.
+ */
+Something* make_something() { return 0; }
+
+%}

Examples/test-suite/java/doxygen_alias_runme.java

@@ -0,0 +1,32 @@
+
+import doxygen_alias.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_alias_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_alias");
+    } 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_alias runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_alias"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    wantedComments.put("doxygen_alias.doxygen_alias.make_something()",
+      "     A function returning something.<br>\n" +
+      " <br>\n" +
+      "     @return A new object which may be null.\n" +
+      "");
+
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/python/doxygen_alias_runme.py

@@ -0,0 +1,12 @@
+#!/usr/bin/python
+
+import doxygen_alias
+import inspect
+import commentVerifier
+
+commentVerifier.check(inspect.getdoc(doxygen_alias.make_something),
+    """\
+A function returning something.
+
+:rtype: :py:class:`Something`
+:return: A new object which may be None.""")

Source/DoxygenTranslator/src/DoxygenParser.cpp

@@ -137,6 +137,11 @@ DoxygenParser::commandBelongs(const std::string &theCommand)
     return it->second;
   }
 
+  // Check if this command is defined as an alias.
+  if (String* const alias = Getattr(m_node, ("feature:doxygen:alias:" + theCommand).c_str())) {
+    return COMMAND_ALIAS;
+  }
+
   // Check if this command should be ignored.
   if (String* const ignore = getIgnoreFeature(theCommand)) {
     // Check that no value is specified for this feature ("1" is the implicit
@@ -895,6 +900,18 @@ DoxygenParser::addCommandUnique(const std::string &theCommand,
   }
 }
 
+void
+DoxygenParser::aliasCommand(const std::string& theCommand,
+                            const TokenList& /* tokList */,
+                            DoxygenEntityList &doxyList)
+{
+  String* const alias = Getattr(m_node, ("feature:doxygen:alias:" + theCommand).c_str());
+  if (!alias)
+    return;
+
+  doxyList.push_back(DoxygenEntity("plainstd::string", Char(alias)));
+}
+
 String* DoxygenParser::getIgnoreFeature(const std::string& theCommand,
                                         const char* argument) const
 {
@@ -1052,6 +1069,9 @@ DoxygenParser::addCommand(const std::string &commandString,
   case COMMAND_HTML_ENTITY:
     addCommandHtmlEntity(theCommand, tokList, doxyList);
     break;
+  case COMMAND_ALIAS:
+    aliasCommand(commandString, tokList, doxyList);
+    break;
   case COMMAND_IGNORE:
     ignoreCommand(commandString, tokList, doxyList);
     break;

Source/DoxygenTranslator/src/DoxygenParser.h

@@ -39,6 +39,7 @@ private:
     COMMANDUNIQUE,
     COMMAND_HTML,
     COMMAND_HTML_ENTITY,
+    COMMAND_ALIAS,
     COMMAND_IGNORE,
     END_LINE,
     PARAGRAPH_END,
@@ -346,6 +347,13 @@ private:
                        const TokenList &tokList,
                        DoxygenEntityList &doxyList);
 
+  /*
+   * Replace the given command with its predefined alias expansion.
+   */
+  void aliasCommand(const std::string& theCommand,
+		    const TokenList &tokList,
+		    DoxygenEntityList &doxyList);
+
   /*
    * Simply ignore the given command, possibly with the word following it or
    * until the matching end command.