Doxygen comments formatting fixes for multi-line comments

Also remove stray static method comments from being incorrectly
generated into the PINVOKE class.

Add some missing multi-line tests for static methods, variables and
constants.

Examples/test-suite/doxygen_parsing.i

@@ -42,6 +42,12 @@ int someVar=42;
  */
 #define CONSTANT_VALUE 4242
 
+/**
+ * A two line
+ * constant comment
+ */
+#define CONSTANT_VALUE_TWO_LINE 5353
+
 /// SomeAnotherClass description
 class SomeAnotherClass
 {
@@ -63,6 +69,12 @@ public:
 	int classAttr3; ///< The class attribute post-comment
 									//!< with details
 
+	/**
+	 * The class attribute comment with
+	 * two lines of comments
+	 */
+	int classAttr4;
+
 	/**
 	 * The class method comment.
          *
@@ -105,6 +117,12 @@ struct SomeAnotherStruct
 	int structAttr3; ///< The struct attribute post-comment
 									 //!< with details
 
+	/**
+	 * The struct attribute comment with
+	 * two lines of comments
+	 */
+	int structAttr4;
+
 	/**
 	 * The struct method comment
 	 */
@@ -131,6 +149,24 @@ struct SomeAnotherStruct
 	void structMethodExtended2(int a, int b)
 	{
 	}
+
+	/**
+	 * The struct static method one line comment
+	 */
+	static void structStaticMethod(int xxx, int yyy)
+	{
+	}
+
+	/**
+	 * The struct static method with parameters
+	 * Two lines of comments
+	 *
+	 * @param aaa Parameter aaa
+	 * @param bbb Parameter bbb
+	 */
+	static void structStaticMethod2(int aaa, int bbb)
+	{
+	}
 };
 
 struct Foo1636

Examples/test-suite/doxygen_parsing_enums.i

@@ -5,6 +5,7 @@
 
 	/**
 	 * Testing comments before enum items
+	 * Including two line comments
 	 */
 	enum SomeAnotherEnum
 	{
@@ -19,7 +20,12 @@
 		/**
 		 * The comment for the third item
 		 */
-		SOME_ITEM_3
+		SOME_ITEM_3,
+		/**
+		 * The comment for the fourth item
+		 * over two lines
+		 */
+		SOME_ITEM_4
 	};
 
 	/**

Examples/test-suite/java/doxygen_parsing_enums_proper_runme.java

@@ -27,6 +27,7 @@ public class doxygen_parsing_enums_proper_runme {
     		"");
     wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum",
     		" Testing comments before enum items \n" +
+    		" Including two line comments \n" +
     		" \n" +
     		"");
     wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum2.SOME_ITEM_30",
@@ -36,6 +37,11 @@ public class doxygen_parsing_enums_proper_runme {
     		" Testing comments after enum items \n" +
     		" \n" +
     		"");
+    wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum.SOME_ITEM_4",
+    		" The comment for the fourth item \n" +
+    		" over two lines \n" +
+    		" \n" +
+    		"");
     wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum.SOME_ITEM_3",
     		" The comment for the third item \n" +
     		" \n" +

Examples/test-suite/java/doxygen_parsing_enums_simple_runme.java

@@ -25,6 +25,11 @@ public class doxygen_parsing_enums_simple_runme {
     		" The comment for the third item \n" +
     		" \n" +
     		"");
+    wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_4",
+    		" The comment for the fourth item \n" +
+    		" over two lines \n" +
+    		" \n" +
+    		"");
     wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_2",
     		" The comment for the second item \n" +
     		" \n" +

Examples/test-suite/java/doxygen_parsing_enums_typesafe_runme.java

@@ -35,6 +35,7 @@ public class doxygen_parsing_enums_typesafe_runme {
     		"");
     wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum",
     		" Testing comments before enum items \n" +
+    		" Including two line comments \n" +
     		" \n" +
     		"");
     wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum2.SOME_ITEM_10",
@@ -44,6 +45,11 @@ public class doxygen_parsing_enums_typesafe_runme {
     		" The comment for the third item \n" +
     		" \n" +
     		"");
+    wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum.SOME_ITEM_4",
+    		" The comment for the fourth item \n" +
+    		" over two lines \n" +
+    		" \n" +
+    		"");
     wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum2.SOME_ITEM_30",
     		"Post comment for the third item \n" +
     		"");

Examples/test-suite/java/doxygen_parsing_enums_typeunsafe_runme.java

@@ -26,6 +26,11 @@ public class doxygen_parsing_enums_typeunsafe_runme {
     		" The comment for the third item \n" +
     		" \n" +
     		"");
+    wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum.SOME_ITEM_4",
+    		" The comment for the fourth item \n" +
+    		" over two lines \n" +
+    		" \n" +
+    		"");
     wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum.SOME_ITEM_1",
     		" The comment for the first item \n" +
     		" \n" +
@@ -35,6 +40,7 @@ public class doxygen_parsing_enums_typeunsafe_runme {
     		"");
     wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum",
     		" Testing comments before enum items \n" +
+    		" Including two line comments \n" +
     		" \n" +
     		"");
     wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum2",

Examples/test-suite/java/doxygen_parsing_runme.java

@@ -31,9 +31,17 @@ public class doxygen_parsing_runme {
     wantedComments.put("doxygen_parsing.SomeAnotherClass.setClassAttr3(int)",
     		"The class attribute post-comment with details \n" +
     		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherClass.setClassAttr4(int)",
+	        " The class attribute comment with \n" + 
+	        " two lines of comments \n" + 
+    		"");
     wantedComments.put("doxygen_parsing.SomeAnotherStruct.setStructAttr3(int)",
     		"The struct attribute post-comment with details \n" +
     		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.setStructAttr4(int)",
+	        " The struct attribute comment with \n" + 
+	        " two lines of comments \n" + 
+    		"");
     wantedComments.put("doxygen_parsing.SomeAnotherClass.classMethodExtended2(int, int)",
     		" The class method with parameter \n" +
     		" \n" +
@@ -90,6 +98,10 @@ public class doxygen_parsing_runme {
     wantedComments.put("doxygen_parsing.SomeAnotherStruct.getStructAttr3()",
     		"The struct attribute post-comment with details \n" +
     		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.getStructAttr4()",
+	        " The struct attribute comment with \n" + 
+	        " two lines of comments \n" + 
+    		"");
     wantedComments.put("doxygen_parsing.doxygen_parsing.getSomeVar()",
     		" The var comment \n" +
     		" \n" +
@@ -114,6 +126,10 @@ public class doxygen_parsing_runme {
     wantedComments.put("doxygen_parsing.SomeAnotherClass.getClassAttr3()",
     		"The class attribute post-comment with details \n" +
     		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherClass.getClassAttr4()",
+	        " The class attribute comment with \n" + 
+	        " two lines of comments \n" + 
+    		"");
     wantedComments.put("doxygen_parsing.SomeAnotherClass.classMethod()",
     		" The class method comment.<br>\n" +
                 " <br>\n" +
@@ -126,12 +142,28 @@ public class doxygen_parsing_runme {
     		" @param b Parameter b \n" +
     		" \n" +
     		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.structStaticMethod(int, int)",
+	        " The struct static method one line comment \n" + 
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_parsing.SomeAnotherStruct.structStaticMethod2(int, int)",
+	        " The struct static method with parameters \n" +
+	        " Two lines of comments \n" +
+    		" \n" +
+    		" @param aaa Parameter aaa \n" +
+    		" @param bbb Parameter bbb \n" +
+    		" \n" +
+    		"");
     wantedComments.put("doxygen_parsing.SomeAnotherClass.setClassAttr2(int)",
     		"The class attribute post-comment \n" +
     		"");
     wantedComments.put("doxygen_parsing.doxygen_parsingConstants.CONSTANT_VALUE",
     		"The constant comment \n" +
     		"");
+    wantedComments.put("doxygen_parsing.doxygen_parsingConstants.CONSTANT_VALUE_TWO_LINE",
+                " A two line \n" +
+                " constant comment \n" +
+    		"");
     wantedComments.put("doxygen_parsing.Foo1636.getGroupmember1()",
 	        "groupmember1 description");
     wantedComments.put("doxygen_parsing.Foo1636.setGroupmember1(int)",

Source/Modules/csharp.cxx

@@ -1212,9 +1212,9 @@ public:
       EnumFeature enum_feature = decodeEnumFeature(n);
       String *typemap_lookup_type = Getattr(n, "name");
 
-      // Translate and write comment if flagged
+      // Translate documentation comments
       if (have_docstring(n)) {
-	String *ds = docstring(n, tab4, true);
+	String *ds = docstring(n, tab0, true);
 	Printv(enum_code, ds, NIL);
 	Delete(ds);
       }
@@ -1424,9 +1424,9 @@ public:
 	if (csattributes)
 	  Printf(enum_code, "  %s\n", csattributes);
 
-	// Translate and write comment if flagged
+	// Translate documentation comments
 	if (have_docstring(n)) {
-	  String *ds = docstring(n, tab4, true);
+	  String *ds = docstring(n, tab2, true);
 	  Printv(enum_code, ds, NIL);
 	  Delete(ds);
 	}
@@ -1580,9 +1580,9 @@ public:
     const String *methodmods = Getattr(n, "feature:cs:methodmodifiers");
     methodmods = methodmods ? methodmods : (is_public(n) ? public_string : protected_string);
 
-    // Translate and write comment if flagged
+    // Translate documentation comments
     if (have_docstring(n)) {
-      String *ds = docstring(n, tab4, true);
+      String *ds = docstring(n, tab2, true);
       Printv(constants_code, ds, NIL);
       Delete(ds);
     }
@@ -2260,9 +2260,9 @@ public:
 
     Language::classHandler(n);
 
-    // Translate and write comment if flagged
+    // Translate documentation comments
     if (have_docstring(n)) {
-      String *ds = docstring(n, tab4, true);
+      String *ds = docstring(n, tab0, true);
       Printv(proxy_class_def, ds, NIL);
       Delete(ds);
     }
@@ -2420,13 +2420,6 @@ public:
     }
     static_flag = false;
 
-    // NO EFFECT
-    if (have_docstring(n)) {
-      String *ds = docstring(n, tab4, true);
-      Printv(module_class_code, ds, NIL);
-      Delete(ds);
-    }
-
     return SWIG_OK;
   }
 
@@ -2648,9 +2641,9 @@ public:
     if (is_interface)
       Printf(interface_class_code, ");\n");
 
-    // Translate and write comment if flagged
+    // Translate documentation comments
     if (have_docstring(n)) {
-      String *ds = docstring(n, tab4, true);
+      String *ds = docstring(n, tab2, true);
       Printv(comment_code, ds, NIL);
       Delete(ds);
     }
@@ -2749,9 +2742,9 @@ public:
 	if (!methodmods)
 	  methodmods = (is_public(n) ? public_string : protected_string);
 
-	// Translate and write comment if flagged
+	// Translate documentation comments
 	if (have_docstring(n)) {
-	  String *ds = docstring(n, tab4, true);
+	  String *ds = docstring(n, tab2, true);
 	  Printv(proxy_class_code, ds, NIL);
 	  Delete(ds);
 	}
@@ -3015,9 +3008,9 @@ public:
         Replaceall(function_code, "$imcall", imcall);
       }
 
-      // Translate and write comment if flagged
+      // Translate documentation comments
       if (have_docstring(n)) {
-	String *ds = docstring(n, tab4, true);
+	String *ds = docstring(n, tab2, true);
 	Printv(comment_code, ds, NIL);
 	Delete(ds);
       }
@@ -3205,9 +3198,9 @@ public:
     const String *methodmods = Getattr(n, "feature:cs:methodmodifiers");
     methodmods = methodmods ? methodmods : (is_public(n) ? public_string : protected_string);
 
-    // Translate and write comment if flagged
+    // Translate documentation comments
     if (have_docstring(n)) {
-      String *ds = docstring(n, tab4, true);
+      String *ds = docstring(n, tab2, true);
       Printv(function_code, ds, NIL);
       Delete(ds);
     }
@@ -4748,8 +4741,7 @@ public:
   /* ------------------------------------------------------------
    * have_docstring()
    *
-   * Check if there is a docstring directive and it has text,
+   * Check for Doxygen comments
-   * or there is an autodoc flag set
    *--------------------------------------------------------------------*/
 
   bool have_docstring(Node *n) {
@@ -4767,9 +4759,7 @@ public:
   /* ------------------------------------------------------------
    * docstring()
    *
-   * Get the docstring text, stripping off {} if necessary,
+   * Get documentation comments, if any
-   * and enclose in triple double quotes.  If autodoc is also
-   * set then it will build a combined docstring.
    *--------------------------------------------------------------------*/
 
   String *docstring(Node *n, const String *indent, bool low_level = false) {
@@ -4784,12 +4774,7 @@ public:
   /* ------------------------------------------------------------
    * build_combined_docstring()
    *
-   * Build the full docstring which may be a combination of the
+   * Return new dosucmentation string to be deleted by caller (never NIL but
-   * explicit docstring and autodoc string or, if none of them
-   * is specified, obtained by translating Doxygen comment to
-   * Python.
-   *
-   * Return new string to be deleted by caller (never NIL but
    * may be empty if there is no docstring).
    *--------------------------------------------------------------------*/
 
@@ -4812,7 +4797,6 @@ public:
     if (Strchr(docstr, '\n')) {
       String *tmp = NewString("");
       Append(tmp, indent_docstring(docstr, indent));
-      Append(tmp, indent);
       Delete(docstr);
       docstr = tmp;
     } else {

Source/Modules/swigmod.h

@@ -40,6 +40,7 @@ extern String *argc_template_string;
 
 /* Miscellaneous stuff */
 
+#define  tab0   ""
 #define  tab2   "  "
 #define  tab4   "    "
 #define  tab8   "        "