Adding test for second doxygen comment style

This style looks like:

/** Line 1
 *  Line 2
 */

This is needed to verify fixes to some of the indentation in the
translated comments.

The test is copied from doxygen_basic_translate.i.  One adjustment was
made to change the comment style on the last function that left out
the intermediate "*" characters.  This does not produce correct output
when combined with this style of starting the text on the first
comment line.

Test results are copied directly from doxygen_basic_translate.  A
minor difference in the Python results will be updated in a subsequent
commit.

Examples/test-suite/common.mk

@@ -620,6 +620,7 @@ DOXYGEN_TEST_CASES += \
 	doxygen_alias \
 	doxygen_basic_notranslate \
 	doxygen_basic_translate \
+	doxygen_basic_translate_style2 \
 	doxygen_ignore \
 	doxygen_misc_constructs \
 	doxygen_nested_class \

Examples/test-suite/doxygen_basic_translate_style2.i

@@ -0,0 +1,105 @@
+%module doxygen_basic_translate_style2
+
+%include "doxygen_basic_translate.h"
+
+// This test demonstrates a doxygen comment style that starts on the
+// first line and so uses extra spacing in subsequent lines.
+
+%inline %{
+
+/** \brief
+ *  Brief description.
+ * 
+ *  The comment text.
+ *
+ *  \author Some author
+ *
+ *  \return Some number
+ *
+ *  \sa function2
+ */
+int function()
+{
+    return 0;
+}
+
+/** A test of a very very very very very very very very very very very very very very very very
+ *  very very very very very long comment string.
+ */
+void function2()
+{
+}
+
+/** A test for overloaded functions
+ *  This is function \b one
+ */
+void function3(int a)
+{
+}
+
+/** A test for overloaded functions
+ *  This is function \b two
+ */
+void function3(int a, int b)
+{
+}
+
+/** A test of some mixed tag usage
+ *  \if CONDITION
+ *  This \a code fragment shows us something \.
+ *  \par Minuses:
+ *  \arg it's senseless
+ *  \arg it's stupid
+ *  \arg it's null
+ *
+ *  \warning This may not work as expected
+ *  \code
+ *  int main() { while(true); }
+ *  \endcode
+ *  \endif
+ */
+void function4()
+{
+}
+
+
+void function5(int a)
+{
+}
+/**< This is a post comment. */
+
+/** Test for default args
+ *  @param a Some parameter, default is 42
+ */
+void function6(int a=42)
+{
+}
+
+class Shape
+{
+public:
+  typedef Shape* superType;
+};
+
+/** Test for a parameter with difficult type
+ *  (mostly for python)
+ *  @param a Very strange param
+ */
+void function7(Shape::superType *a[10])
+{
+}
+
+/** Multiple parameters test.
+ *
+ *  @param y Vertical coordinate.
+ *  @param x Horizontal coordinate.
+ *  @return Arc tangent of @c y/x.
+ */
+double Atan2(double y, double x)
+{
+    return 0;
+}
+
+/** Comment at the end of file should be ignored.
+ */
+%}

Examples/test-suite/java/doxygen_basic_translate_style2_runme.java

@@ -0,0 +1,99 @@
+
+import doxygen_basic_translate_style2.*;
+import com.sun.javadoc.*;
+import java.util.HashMap;
+
+public class doxygen_basic_translate_style2_runme {
+  static {
+    try {
+      System.loadLibrary("doxygen_basic_translate_style2");
+    } 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_basic_translate_style2 runtime test",
+                                       "CommentParser",
+                                       new String[]{"-quiet", "doxygen_basic_translate_style2"});
+
+    HashMap<String, String> wantedComments = new HashMap<String, String>();
+    
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function()",
+    		" \n" +
+    		" Brief description.\n" +
+    		" \n" +
+    		" The comment text.\n" +
+    		" @author Some author\n" +
+    		" @return Some number\n" +
+    		" @see function2\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function2()",
+    		" A test of a very very very very very very very very very very very very very very very very \n" +
+    		" very very very very very long comment string. \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function4()",
+    		" A test of some mixed tag usage \n" +
+    		" If: CONDITION {\n" +
+    		" This <i>code </i>fragment shows us something . \n" +
+    		" <p alt=\"Minuses: \">\n" +
+    		" <li>it's senseless \n" +
+    		" </li><li>it's stupid \n" +
+    		" </li><li>it's null \n" +
+    		" \n" +
+    		" </li></p>Warning: This may not work as expected \n" +
+    		" \n" +
+    		" {@code \n" +
+    		"int main() { while(true); } \n" +
+    		" }\n" +
+    		" }\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function3(int)",
+    		" A test for overloaded functions \n" +
+    		" This is function <b>one </b>\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function5(int)",
+    		" This is a post comment. \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function6(int)",
+    		" Test for default args \n" +
+    		" @param a Some parameter, default is 42" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function6()",
+    		" Test for default args \n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function7(doxygen_basic_translate_style2.SWIGTYPE_p_p_p_Shape)",
+    		" Test for a parameter with difficult type \n" +
+    		" (mostly for python) \n" +
+    		" @param a Very strange param \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function3(int, int)",
+    		" A test for overloaded functions \n" +
+    		" This is function <b>two </b>\n" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.Atan2(double, double)",
+    		" Multiple parameters test.\n" +
+    		" \n" +
+    		" @param y Vertical coordinate.\n" +
+    		" @param x Horizontal coordinate.\n" +
+    		" @return Arc tangent of <code>y/x</code>.\n" +
+    		"");
+
+    // and ask the parser to check comments for us
+    System.exit(parser.check(wantedComments));
+  }
+}

Examples/test-suite/python/doxygen_basic_translate_style2_runme.py

@@ -0,0 +1,82 @@
+import doxygen_basic_translate_spaced
+import inspect
+import string
+import sys
+import comment_verifier
+
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function),
+    """\
+Brief description.
+
+The comment text.
+
+Author: Some author
+
+:rtype: int
+:return: Some number
+
+See also: function2"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function2),
+    """\
+A test of a very very very very very very very very very very very very very very very very
+very very very very very long comment string."""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function3),
+    """*Overload 1:*
+
+A test for overloaded functions
+This is function **one**
+
+|
+
+*Overload 2:*
+
+A test for overloaded functions
+This is function **two**"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function4),
+    """\
+A test of some mixed tag usage
+If: CONDITION {
+This *code* fragment shows us something .
+Title: Minuses:
+* it\'s senseless
+* it\'s stupid
+* it\'s null
+
+Warning: This may not work as expected
+
+.. code-block:: c++
+
+    int main() { while(true); }
+}"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function5),
+    """This is a post comment."""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function6),
+    """\
+Test for default args
+:type a: int
+:param a: Some parameter, default is 42"""
+)
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.function7),
+    """\
+Test for a parameter with difficult type
+(mostly for python)
+:type a: :py:class:`Shape`
+:param a: Very strange param"""
+)
+
+comment_verifier.check(inspect.getdoc(doxygen_basic_translate_spaced.Atan2),
+    """\
+Multiple parameters test.
+
+:type y: float
+:param y: Vertical coordinate.
+:type x: float
+:param x: Horizontal coordinate.
+:rtype: float
+:return: Arc tangent of ``y/x``."""
+)