From 37013523af44938263b92188a89a11a51866fd7b Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Mon, 29 Jul 2024 23:42:43 +0100 Subject: [PATCH] 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 | 36 +++++++++++++ Examples/test-suite/doxygen_parsing_enums.i | 8 ++- .../doxygen_parsing_enums_proper_runme.java | 6 +++ .../doxygen_parsing_enums_simple_runme.java | 5 ++ .../doxygen_parsing_enums_typesafe_runme.java | 6 +++ ...oxygen_parsing_enums_typeunsafe_runme.java | 6 +++ .../java/doxygen_parsing_runme.java | 32 +++++++++++ Source/Modules/csharp.cxx | 54 +++++++------------ Source/Modules/swigmod.h | 1 + 9 files changed, 118 insertions(+), 36 deletions(-) diff --git a/Examples/test-suite/doxygen_parsing.i b/Examples/test-suite/doxygen_parsing.i index ddb9961ad..2fb092ad9 100644 --- a/Examples/test-suite/doxygen_parsing.i +++ b/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 diff --git a/Examples/test-suite/doxygen_parsing_enums.i b/Examples/test-suite/doxygen_parsing_enums.i index b7a39871f..7f073c989 100644 --- a/Examples/test-suite/doxygen_parsing_enums.i +++ b/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 }; /** diff --git a/Examples/test-suite/java/doxygen_parsing_enums_proper_runme.java b/Examples/test-suite/java/doxygen_parsing_enums_proper_runme.java index 6b1e2b08e..88417d2cd 100644 --- a/Examples/test-suite/java/doxygen_parsing_enums_proper_runme.java +++ b/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" + diff --git a/Examples/test-suite/java/doxygen_parsing_enums_simple_runme.java b/Examples/test-suite/java/doxygen_parsing_enums_simple_runme.java index 1e0dd74ee..f0693352d 100644 --- a/Examples/test-suite/java/doxygen_parsing_enums_simple_runme.java +++ b/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" + diff --git a/Examples/test-suite/java/doxygen_parsing_enums_typesafe_runme.java b/Examples/test-suite/java/doxygen_parsing_enums_typesafe_runme.java index 7cf3b17ef..6b208997e 100644 --- a/Examples/test-suite/java/doxygen_parsing_enums_typesafe_runme.java +++ b/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" + ""); diff --git a/Examples/test-suite/java/doxygen_parsing_enums_typeunsafe_runme.java b/Examples/test-suite/java/doxygen_parsing_enums_typeunsafe_runme.java index 3a41fe56f..900bde913 100644 --- a/Examples/test-suite/java/doxygen_parsing_enums_typeunsafe_runme.java +++ b/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", diff --git a/Examples/test-suite/java/doxygen_parsing_runme.java b/Examples/test-suite/java/doxygen_parsing_runme.java index 05828f226..3bb5c8985 100644 --- a/Examples/test-suite/java/doxygen_parsing_runme.java +++ b/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.
\n" + "
\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)", diff --git a/Source/Modules/csharp.cxx b/Source/Modules/csharp.cxx index d1be9294a..f9db34f08 100644 --- a/Source/Modules/csharp.cxx +++ b/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, - * or there is an autodoc flag set + * Check for Doxygen comments *--------------------------------------------------------------------*/ bool have_docstring(Node *n) { @@ -4767,9 +4759,7 @@ public: /* ------------------------------------------------------------ * docstring() * - * Get the docstring text, stripping off {} if necessary, - * and enclose in triple double quotes. If autodoc is also - * set then it will build a combined docstring. + * Get documentation comments, if any *--------------------------------------------------------------------*/ 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 - * 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 + * Return new dosucmentation 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 { diff --git a/Source/Modules/swigmod.h b/Source/Modules/swigmod.h index c146d17ac..943ee3980 100644 --- a/Source/Modules/swigmod.h +++ b/Source/Modules/swigmod.h @@ -40,6 +40,7 @@ extern String *argc_template_string; /* Miscellaneous stuff */ +#define tab0 "" #define tab2 " " #define tab4 " " #define tab8 " "