Support doxygen \param[] commands

Recognize \param[in], \param[out], and \param[in,out].  Currently they
are all treated the same as \param, but the information is now
available for inclusion in the translated comments.  This is done
using new utility functions getBaseCommand and getEndOfWordCommand,
which will also generalize to treatment of code command options,
e.g. \code{.py}.  Preliminary treatment of the extended version of
\code is already in place in these functions.

Added examples of all three new \param commands to the
doxygen_translate_all_tags test and updated the python and java
expected output.

Examples/test-suite/doxygen_translate_all_tags.i

@@ -262,6 +262,9 @@ void func06(int a)
  * \paragraph someParagraph Paragraph title
  *
  * \param a the first param
+ * \param[in] b parameter with intent(in)
+ * \param[out] c parameter with intent(out)
+ * \param[in,out] d parameter with intent(in,out)
  * 
  * \post Some description
  *
@@ -273,7 +276,7 @@ void func06(int a)
  *
  * \property someVar
  */
-void func07(int a)
+void func07(int a, int b, int c, int d)
 {
 }
 

Examples/test-suite/java/doxygen_translate_all_tags_runme.java

@@ -104,7 +104,7 @@ public class doxygen_translate_all_tags_runme {
     		" {@link someMember Some description follows }\n" +
     		" This will only appear in man\n");
     
-    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func07(int)",
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func07(int, int, int, int)",
                        " Comment for <b>func07()</b>.\n" +
                        " Note: Here \n" +
     		" is the note! \n" +
@@ -115,7 +115,10 @@ public class doxygen_translate_all_tags_runme {
     		" The paragraph text. \n" +
     		" Maybe even multiline \n" +
     		" </p>\n" +
-                " @param a the first param\n");
+                " @param a the first param\n" +
+                " @param b parameter with intent(in)\n" +
+                " @param c parameter with intent(out)\n" +
+		" @param d parameter with intent(in,out)\n");
     
     wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func08(int)",
                        "<a id=\"someAnchor\"></a>\n" +

Examples/test-suite/python/doxygen_translate_all_tags_runme.py

@@ -209,7 +209,13 @@ Maybe even multiline
 
 
 :type a: int
-:param a: the first param""")
+:param a: the first param
+:type b: int
+:param b: parameter with intent(in)
+:type c: int
+:param c: parameter with intent(out)
+:type d: int
+:param d: parameter with intent(in,out)""")
 
 comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func08),
 r"""Text after anchor.

Source/Doxygen/doxyparser.cxx

@@ -34,6 +34,30 @@ std::set<std::string> DoxygenParser::doxygenSectionIndicators;
 const int TOKENSPERLINE = 8; //change this to change the printing behaviour of the token list
 const std::string END_HTML_TAG_MARK("/");
 
+std::string getBaseCommand(const std::string &cmd) {
+  if (cmd.substr(0,5) == "param")
+    return "param";
+  else if (cmd.substr(0,4) == "code")
+    return "code";
+  else
+    return cmd;
+}
+
+// Find the first position beyond the word command.  Extra logic is
+// used to avoid putting the characters "," and "." in
+// DOXYGEN_WORD_CHARS.
+static size_t getEndOfWordCommand(const std::string &line, size_t pos) {
+  size_t endOfWordPos = line.find_first_not_of(DOXYGEN_WORD_CHARS, pos);
+  if (line.substr(pos, 6) == "param[")
+    // include ",", which can appear in param[in,out]
+    endOfWordPos = line.find_first_not_of(string(DOXYGEN_WORD_CHARS)+ ",", pos);  
+  else if (line.substr(pos, 5) == "code{")
+    // include ".", which can appear in e.g. code{.py}
+    endOfWordPos = line.find_first_not_of(string(DOXYGEN_WORD_CHARS)+ ".", pos);
+  return endOfWordPos;
+}
+
+
 DoxygenParser::DoxygenParser(bool noisy) : noisy(noisy) {
   fillTables();
 }
@@ -118,7 +142,7 @@ void DoxygenParser::printTree(const DoxygenEntityList &rootList) {
 }
 
 DoxygenParser::DoxyCommandEnum DoxygenParser::commandBelongs(const std::string &theCommand) {
-  DoxyCommandsMapIt it = doxygenCommands.find(stringToLower(theCommand));
+  DoxyCommandsMapIt it = doxygenCommands.find(stringToLower(getBaseCommand(theCommand)));
 
   if (it != doxygenCommands.end()) {
     return it->second;
@@ -312,7 +336,7 @@ DoxygenParser::TokenListCIt DoxygenParser::getEndOfParagraph(const TokenList &to
 
     } else if (endOfParagraph->m_tokenType == COMMAND) {
 
-      if (isSectionIndicator(endOfParagraph->m_tokenString)) {
+      if (isSectionIndicator(getBaseCommand(endOfParagraph->m_tokenString))) {
         return endOfParagraph;
       } else {
         endOfParagraph++;
@@ -1154,7 +1178,7 @@ bool DoxygenParser::processEscapedChars(size_t &pos, const std::string &line) {
  */
 void DoxygenParser::processWordCommands(size_t &pos, const std::string &line) {
   pos++;
-  size_t endOfWordPos = line.find_first_not_of(DOXYGEN_WORD_CHARS, pos);
+  size_t endOfWordPos = getEndOfWordCommand(line, pos);
 
   string cmd = line.substr(pos, endOfWordPos - pos);
   addDoxyCommand(m_tokenList, cmd);

Source/Doxygen/doxyparser.h

@@ -21,6 +21,11 @@
 
 #include "doxyentity.h"
 
+// Utility function to return the base part of a command that may
+// include options, e.g. param[in] -> param
+std::string getBaseCommand(const std::string &cmd);
+
+
 class DoxygenParser {
 private:
 

Source/Doxygen/javadoc.cxx

@@ -334,7 +334,7 @@ std::string JavaDocConverter::translateSubtree(DoxygenEntity &doxygenEntity) {
 void JavaDocConverter::translateEntity(DoxygenEntity &tag, std::string &translatedComment) {
 
   std::map<std::string, std::pair<tagHandler, std::string> >::iterator it;
-  it = tagHandlers.find(tag.typeOfEntity);
+  it = tagHandlers.find(getBaseCommand(tag.typeOfEntity));
 
   if (it != tagHandlers.end()) {
     (this->*(it->second.first))(tag, translatedComment, it->second.second);

Source/Doxygen/pydoc.cxx

@@ -456,7 +456,7 @@ std::string PyDocConverter::translateSubtree(DoxygenEntity &doxygenEntity) {
 void PyDocConverter::translateEntity(DoxygenEntity &doxyEntity, std::string &translatedComment) {
   // check if we have needed handler and call it
   std::map<std::string, std::pair<tagHandler, std::string> >::iterator it;
-  it = tagHandlers.find(doxyEntity.typeOfEntity);
+  it = tagHandlers.find(getBaseCommand(doxyEntity.typeOfEntity));
   if (it != tagHandlers.end())
     (this->*(it->second.first)) (doxyEntity, translatedComment, it->second.second);
 }