From dc045640233962f69219cda73eab24898768fc48 Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Mon, 5 Dec 2022 19:47:59 +0000 Subject: [PATCH] Improved handling of Doxygen comments in parameter lists Fix garbled Doxygen post comments in parameter lists. Fix syntax error parsing a trailing Doxygen comment in parameter lists. Closes #2023 --- CHANGES.current | 4 + Examples/test-suite/doxygen_misc_constructs.i | 21 +++++ .../java/doxygen_misc_constructs_runme.java | 32 +++++++- Source/CParse/parser.y | 79 +++++++++---------- 4 files changed, 92 insertions(+), 44 deletions(-) diff --git a/CHANGES.current b/CHANGES.current index 93c8a99be..c03b376c8 100644 --- a/CHANGES.current +++ b/CHANGES.current @@ -7,6 +7,10 @@ the issue number to the end of the URL: https://github.com/swig/swig/issues/ Version 4.2.0 (in progress) =========================== +2022-12-05: wsfulton + #2023 Fix garbled Doxygen post comments in parameter lists. + Fix syntax error parsing a trailing Doxygen comment in parameter lists. + 2022-12-03: wsfulton #1609 Fix syntax error parsing of Doxygen comments after last enum item. diff --git a/Examples/test-suite/doxygen_misc_constructs.i b/Examples/test-suite/doxygen_misc_constructs.i index 56e4fbdac..4702a9ae0 100644 --- a/Examples/test-suite/doxygen_misc_constructs.i +++ b/Examples/test-suite/doxygen_misc_constructs.i @@ -138,6 +138,27 @@ }; }; + /// SIOBeam struct description + struct SIOBeam { + + /** testfunction - testing extra trailing doc comment */ + void testfunction( + /** testfunction aaa parm */ + int testf_aaa, + /** testfunction bbb parm */ + double testf_bbb, + /** testfunction ccc parm */ + bool testf_ccc /** testfunction more for two parm */ + ) {} + + /// Constructor for input from an existing SIO file + explicit SIOBeam( + const char * filename, ///< Name of input SIO file. + int elevationOrder=1, ///< Interpolation order (0-3) in elevation + int bearingOrder=1 ///< Interpolation order (0-3) in bearing + ) {} + }; + /// @return This is a bad place for this tag, but it should be ignored. struct StructWithReturnComment {}; diff --git a/Examples/test-suite/java/doxygen_misc_constructs_runme.java b/Examples/test-suite/java/doxygen_misc_constructs_runme.java index 18cc5d901..765baeb01 100644 --- a/Examples/test-suite/java/doxygen_misc_constructs_runme.java +++ b/Examples/test-suite/java/doxygen_misc_constructs_runme.java @@ -122,9 +122,6 @@ public class doxygen_misc_constructs_runme { wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENestedOdd.ODD_THREE", " desc of odd_three\n"); - wantedComments.put("doxygen_misc_constructs.StructWithReturnComment", - " @return This is a bad place for this tag, but it should be ignored."); - wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENestedOddPartial1", " ENestedOddPartial1 description.\n" + "\n"); @@ -158,6 +155,35 @@ public class doxygen_misc_constructs_runme { wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.TESTENUM.TEST_TWO", " something for two something more for two\n"); + wantedComments.put("doxygen_misc_constructs.SIOBeam", + " SIOBeam struct description\n" + + "\n"); + + wantedComments.put("doxygen_misc_constructs.SIOBeam.testfunction(int, double, boolean)", + " testfunction - testing extra trailing doc comment
\n" + + " @param testf_aaa testfunction aaa parm
\n" + + " @param testf_bbb testfunction bbb parm
\n" + + " @param testf_ccc testfunction ccc parm testfunction more for two parm\n" + + "\n"); + + wantedComments.put("doxygen_misc_constructs.SIOBeam(java.lang.String, int, int)", + " Constructor for input from an existing SIO file
\n" + + " @param filename Name of input SIO file.
\n" + + " @param elevationOrder Interpolation order (0-3) in elevation
\n" + + " @param bearingOrder Interpolation order (0-3) in bearing\n" + + "\n"); + + wantedComments.put("doxygen_misc_constructs.SIOBeam(java.lang.String, int)", + " Constructor for input from an existing SIO file
\n" + + " @param filename Name of input SIO file.
\n" + + " @param elevationOrder Interpolation order (0-3) in elevation
\n" + + "\n"); + + wantedComments.put("doxygen_misc_constructs.SIOBeam(java.lang.String)", + " Constructor for input from an existing SIO file
\n" + + " @param filename Name of input SIO file.
\n" + + "\n"); + wantedComments.put("doxygen_misc_constructs.StructWithReturnComment", " @return This is a bad place for this tag, but it should be ignored."); diff --git a/Source/CParse/parser.y b/Source/CParse/parser.y index 41d805c28..f5311373c 100644 --- a/Source/CParse/parser.y +++ b/Source/CParse/parser.y @@ -76,12 +76,11 @@ static int template_reduce = 0; static int cparse_externc = 0; int ignore_nested_classes = 0; int kwargs_supported = 0; + /* ----------------------------------------------------------------------------- * Doxygen Comment Globals * ----------------------------------------------------------------------------- */ static String *currentDeclComment = NULL; /* Comment of C/C++ declaration. */ -static Node *previousNode = NULL; /* Pointer to the previous node (for post comments) */ -static Node *currentNode = NULL; /* Pointer to the current node (for post comments) */ /* ----------------------------------------------------------------------------- * Assist Functions @@ -96,9 +95,6 @@ static void yyerror (const char *e) { static Node *new_node(const_String_or_char_ptr tag) { Node *n = Swig_cparse_new_node(tag); - /* Remember the previous node in case it will need a post-comment */ - previousNode = currentNode; - currentNode = n; return n; } @@ -1680,7 +1676,7 @@ static String *add_qualifier_to_declarator(SwigType *type, SwigType *qualifier) %type identifier; %type initializer cpp_const exception_specification cv_ref_qualifier qualifiers_exception_specification; %type storage_class extern_string; -%type parms ptail rawparms varargs_parms ; +%type parms rawparms varargs_parms ; %type templateparameterstail; %type

parm_no_dox parm valparm rawvalparms valparms valptail ; %type

typemap_parm tm_list tm_tail ; @@ -4455,16 +4451,12 @@ template_parms : templateparameter templateparameterstail { templateparameter : templcpptype def_args { $$ = NewParmWithoutFileLineInfo(NewString($1), 0); - previousNode = currentNode; - currentNode = $$; Setfile($$, cparse_file); Setline($$, cparse_line); Setattr($$, "value", $2.rawval ? $2.rawval : $2.val); } | TEMPLATE LESSTHAN template_parms GREATERTHAN cpptype idcolon def_args { $$ = NewParmWithoutFileLineInfo(NewStringf("template< %s > %s %s", ParmList_str_defaultargs($3), $5, $6), $6); - previousNode = currentNode; - currentNode = $$; Setfile($$, cparse_file); Setline($$, cparse_line); if ($7.val) { @@ -4473,8 +4465,6 @@ templateparameter : templcpptype def_args { } | TEMPLATE LESSTHAN template_parms GREATERTHAN cpptype def_args { $$ = NewParmWithoutFileLineInfo(NewStringf("template< %s > %s", ParmList_str_defaultargs($3), $5), 0); - previousNode = currentNode; - currentNode = $$; Setfile($$, cparse_file); Setline($$, cparse_line); if ($6.val) { @@ -5167,35 +5157,47 @@ parms : rawparms { } ; -rawparms : parm ptail { - set_nextSibling($1,$2); - $$ = $1; +/* rawparms constructs parameter lists and deal with quirks of doxygen post strings (after the parameter's comma */ +rawparms : parm { + $$ = $1; } - | empty { + | parm DOXYGENPOSTSTRING { + set_comment($1, $2); + $$ = $1; + } + | parm DOXYGENSTRING { + /* Misplaced doxygen string, attach it to previous parameter, like Doxygen does */ + set_comment($1, $2); + $$ = $1; + } + | parm COMMA parms { + if ($3) { + set_nextSibling($1, $3); + } + $$ = $1; + } + | parm DOXYGENPOSTSTRING COMMA parms { + if ($4) { + set_nextSibling($1, $4); + } + set_comment($1, $2); + $$ = $1; + } + | parm COMMA DOXYGENPOSTSTRING parms { + if ($4) { + set_nextSibling($1, $4); + } + set_comment($1, $3); + $$ = $1; + } + | empty { $$ = 0; - previousNode = currentNode; - currentNode=0; - } - ; - -ptail : COMMA parm ptail { - set_nextSibling($2,$3); - $$ = $2; - } - | COMMA DOXYGENPOSTSTRING parm ptail { - set_comment(previousNode, $2); - set_nextSibling($3, $4); - $$ = $3; - } - | empty { $$ = 0; } - ; - + } + ; parm_no_dox : rawtype parameter_declarator { SwigType_push($1,$2.type); $$ = NewParmWithoutFileLineInfo($1,$2.id); - previousNode = currentNode; - currentNode = $$; Setfile($$,cparse_file); Setline($$,cparse_line); if ($2.defarg) { @@ -5205,8 +5207,6 @@ parm_no_dox : rawtype parameter_declarator { | ELLIPSIS { SwigType *t = NewString("v(...)"); $$ = NewParmWithoutFileLineInfo(t, 0); - previousNode = currentNode; - currentNode = $$; Setfile($$,cparse_file); Setline($$,cparse_line); } @@ -5219,10 +5219,6 @@ parm : parm_no_dox { $$ = $2; set_comment($2, $1); } - | parm_no_dox DOXYGENPOSTSTRING { - $$ = $1; - set_comment($1, $2); - } ; valparms : rawvalparms { @@ -6481,6 +6477,7 @@ enumlist : enumlist_item { } | enumlist_item DOXYGENSTRING { Setattr($1, "_last", $1); + /* Misplaced doxygen string, attach it to previous parameter, like Doxygen does */ set_comment($1, $2); $$ = $1; }