Merge branch 'doxy/commands'

* doxy/commands:
  Update documentation for doxygen tags
  Fix doxygen translation of \p command for python
  Fix doxygen handling of \em tag for python
  Minor formatting updates to doxygen docs
  Reformat tag lists in doxygen documentation
  Add doxygen_code_blocks_runme.java
  Special handling for python doctest code blocks
  Add new doxygen test doxygen_code_blocks
  Handle doxygen code command with language option
  Improve doxygen parser handling of \code content
  Flag optional arguments in doxygen pydoc output
  Add parameter direction to doxygen pydoc output
  Support doxygen \param[] commands

Examples/test-suite/common.mk

@@ -635,6 +635,7 @@ DOXYGEN_TEST_CASES += \
 	doxygen_translate \
 	doxygen_translate_all_tags \
 	doxygen_translate_links \
+	doxygen_code_blocks \
 
 $(DOXYGEN_TEST_CASES:=.cpptest): SWIGOPT += -doxygen
 

Examples/test-suite/doxygen_code_blocks.i

@@ -0,0 +1,62 @@
+%module doxygen_code_blocks
+
+// This test is only used with Python
+
+%inline %{
+
+/**
+ * \brief Test for code blocks
+ *
+ * \code
+ * simple code block
+ * \endcode
+ *
+ * More advanced usage with C++ characters:
+ * \code
+ * std::vector<int> first;                                // empty vector of ints
+ * std::vector<int> second (4,100);                       // four ints with value 100
+ * std::vector<int> third (second.begin(),second.end());  // iterating through second
+ * std::vector<int> fourth (third);                       // a copy of third
+ *  // the iterator constructor can also be used to construct from arrays:
+ * int myints[] = {16,2,77,29};
+ * std::vector<int> fifth (myints, myints + sizeof(myints) / sizeof(int) );
+ *
+ * std::cout << "The contents of fifth are:";
+ * for (std::vector<int>::iterator it = fifth.begin(); it != fifth.end(); ++it)
+ *   std::cout << ' ' << *it;
+ * std::cout << '\n'; 
+ * \endcode
+ *
+ * A code block for C:
+ * \code{.c}
+ * printf("hello world");
+ * \endcode
+ *
+ * A code block for Java:
+ * \code{.java}
+ * public class HelloWorld {
+ *     public static void main(String[] args) {
+ *         // Prints "Hello, World" to the terminal window.
+ *         System.out.println("Hello, World");
+ *     }
+ * }
+ * \endcode
+ * 
+ * A code block for python:
+ * \code{.py}
+ * print('hello world')
+ * \endcode
+ *
+ * A python doctest example:
+ * \code{.py}
+ * >>> 1 + 1
+ * 2
+ * \endcode
+ */
+int function()
+{
+    return 0;
+}  
+
+
+%}

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_code_blocks_runme.java

@@ -0,0 +1,83 @@
+
+import doxygen_code_blocks.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_code_blocks_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_code_blocks");
+    } 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[]) 
+  {
+    /*
+      Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
+      and calls the start() method of that class with parsed information.
+    */
+    CommentParser parser = new CommentParser();
+    com.sun.tools.javadoc.Main.execute("doxygen_code_blocks runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_code_blocks"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_code_blocks.doxygen_code_blocks.function()",
+		       " Test for code blocks\n \n" +
+		       " \n \n" +
+		       " {@code  \n" +
+		       " simple code block \n" +
+		       " }\n \n" +
+		       " \n \n" +
+		       " More advanced usage with C++ characters:\n \n" +
+		       " {@code  \n" +
+		       " std::vector<int> first;                                // empty vector of ints \n" +
+		       " std::vector<int> second (4,100);                       // four ints with value 100 \n" +
+		       " std::vector<int> third (second.begin(),second.end());  // iterating through second \n" +
+		       " std::vector<int> fourth (third);                       // a copy of third \n" +
+		       " // the iterator constructor can also be used to construct from arrays: \n" +
+		       " int myints[] = {16,2,77,29}; \n" +
+		       " std::vector<int> fifth (myints, myints + sizeof(myints) / sizeof(int) ); \n" +
+		       "  \n" +
+		       " std::cout << \"The contents of fifth are:\"; \n" +
+		       " for (std::vector<int>::iterator it = fifth.begin(); it != fifth.end(); ++it) \n" +
+		       " std::cout << \' \' << *it; \n" +
+		       " std::cout << \'\\n\';  \n" +
+		       " }\n \n" +
+		       " \n \n" +
+		       " A code block for C:\n \n" +
+		       " {@code  \n" +
+		       " printf(\"hello world\"); \n" +
+		       " }\n \n" +
+		       " \n \n" +
+		       " A code block for Java:\n \n" +
+		       " {@code  \n" +
+		       " public class HelloWorld { \n" +
+		       " public static void main(String[] args) { \n" +
+		       " // Prints \"Hello, World\" to the terminal window. \n" +
+		       " System.out.println(\"Hello, World\"); \n" +
+		       " } \n" +
+		       " } \n" +
+		       " }\n \n" +
+		       " \n \n" +
+		       " A code block for python:\n \n" +
+		       " {@code  \n" +
+		       " print(\'hello world\') \n" +
+		       " }\n \n" +
+		       " \n \n" +
+		       " A python doctest example:\n \n" +
+		       " {@code  \n" +
+		       " >>> 1 + 1 \n" +
+		       " 2 \n" +
+		       " } \n" +
+		       " \n" +
+		       "");
+
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/java/doxygen_translate_all_tags_runme.java

@@ -96,7 +96,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" +
@@ -107,7 +107,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_basic_translate_runme.py

@@ -60,7 +60,7 @@ comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function5),
 comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function6),
     """\
 Test for default args
-:type a: int
+:type a: int, optional
 :param a: Some parameter, default is 42"""
 )
 comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function7),

Examples/test-suite/python/doxygen_basic_translate_style2_runme.py

@@ -58,7 +58,7 @@ comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function5),
 comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function6),
     """\
 Test for default args
-:type a: int
+:type a: int, optional
 :param a: Some parameter, default is 42"""
 )
 comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function7),

Examples/test-suite/python/doxygen_code_blocks_runme.py

@@ -0,0 +1,58 @@
+import doxygen_code_blocks
+import inspect
+import string
+import sys
+import comment_verifier
+
+comment_verifier.check(inspect.getdoc(doxygen_code_blocks.function),
+    """\
+Test for code blocks
+
+.. code-block:: c++
+
+    simple code block
+
+More advanced usage with C++ characters:
+
+.. code-block:: c++
+
+    std::vector<int> first;                                // empty vector of ints
+    std::vector<int> second (4,100);                       // four ints with value 100
+    std::vector<int> third (second.begin(),second.end());  // iterating through second
+    std::vector<int> fourth (third);                       // a copy of third
+     // the iterator constructor can also be used to construct from arrays:
+    int myints[] = {16,2,77,29};
+    std::vector<int> fifth (myints, myints + sizeof(myints) / sizeof(int) );
+
+    std::cout << "The contents of fifth are:";
+    for (std::vector<int>::iterator it = fifth.begin(); it != fifth.end(); ++it)
+      std::cout << ' ' << *it;
+    std::cout << '\\n';
+
+A code block for C:
+
+.. code-block:: c
+
+    printf("hello world");
+
+A code block for Java:
+
+.. code-block:: java
+
+    public class HelloWorld {
+        public static void main(String[] args) {
+            // Prints "Hello, World" to the terminal window.
+            System.out.println("Hello, World");
+        }
+    }
+
+A code block for python:
+
+.. code-block:: python
+
+    print('hello world')
+
+A python doctest example:
+
+>>> 1 + 1
+2""")

Examples/test-suite/python/doxygen_misc_constructs_runme.py

@@ -12,7 +12,7 @@ comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.getAddress),
 :param fileName: name of the file, where the source line is located
 :type line: int
 :param line: line number
-:type isGetSize: boolean
+:type isGetSize: boolean, optional
 :param isGetSize: if set, for every object location both address and size are returned
 
 Connection::getId() """)

Examples/test-suite/python/doxygen_translate_all_tags_runme.py

@@ -82,7 +82,7 @@ r"""Comment for **func03()**.
 
 *italicword*
 
-emphazedWord
+*emphazedWord*
 
 
 
@@ -196,7 +196,7 @@ is the note!
 This is an overloaded member function, provided for convenience.
 It differs from the above function only in what argument(s) it accepts.
 
-someword
+``someword``
 
 
 
@@ -209,7 +209,13 @@ Maybe even multiline
 
 
 :type a: int
-:param a: the first param""")
+:param a: the first param
+:type b: int, in
+:param b: parameter with intent(in)
+:type c: int, out
+:param c: parameter with intent(out)
+:type d: int, in/out
+:param d: parameter with intent(in,out)""")
 
 comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func08),
 r"""Text after anchor.

Examples/test-suite/python/doxygen_translate_runme.py

@@ -80,7 +80,7 @@ is the note!
 This is an overloaded member function, provided for convenience.
 It differs from the above function only in what argument(s) it accepts.
 
-someword
+``someword``