XS-MLVP
/
swig
mirror of https://github.com/swig/swig
5
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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.
This commit is contained in:
William S Fulton 2024-07-29 23:42:43 +01:00
parent 9eb9f5ee1f
commit 37013523af
9 changed files with 118 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
Examples/test-suite/doxygen_parsing.i
View File

@ -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

8
Examples/test-suite/doxygen_parsing_enums.i
View File

@ -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
};
/**

6
Examples/test-suite/java/doxygen_parsing_enums_proper_runme.java
View File

@ -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" +

5
Examples/test-suite/java/doxygen_parsing_enums_simple_runme.java
View File

@ -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" +

6
Examples/test-suite/java/doxygen_parsing_enums_typesafe_runme.java
View File

@ -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" +
"");

6
Examples/test-suite/java/doxygen_parsing_enums_typeunsafe_runme.java
View File

@ -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",

32
Examples/test-suite/java/doxygen_parsing_runme.java
View File

@ -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)",

54
Source/Modules/csharp.cxx
View File

@ -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 {

1
Source/Modules/swigmod.h
View File

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