Skip to content

Commit 55d36e3

Browse files
wsfultonwsfulton
committed
Merge branch 'Issue-1632'
* Issue-1632: Minor workaround in doxygen_basic_translate_style3 test Add new test doxygen_basic_translate_style3.i Fix for newline handling in doxygen "///" style comments
2 parents 9cfeb59 + e46e165 commit 55d36e3

File tree

5 files changed

+306
-0
lines changed

5 files changed

+306
-0
lines changed

‎Examples/test-suite/common.mk

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -627,6 +627,7 @@ DOXYGEN_TEST_CASES += \
627627
doxygen_basic_notranslate \
628628
doxygen_basic_translate \
629629
doxygen_basic_translate_style2 \
630+
doxygen_basic_translate_style3 \
630631
doxygen_ignore \
631632
doxygen_misc_constructs \
632633
doxygen_nested_class \

‎Examples/test-suite/doxygen_basic_translate_style3.i

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
%module doxygen_basic_translate_style3
2+
3+
%include "doxygen_basic_translate.h"
4+
5+
%inline %{
6+
7+
/// \brief
8+
/// Brief description.
9+
///
10+
/// The comment text.
11+
///
12+
/// \author Some author
13+
///
14+
/// \return Some number
15+
///
16+
/// \sa function2
17+
int function()
18+
{
19+
return 0;
20+
}
21+
22+
/// A test of a very very very very very very very very very very very very very very very very
23+
/// very very very very very long comment string.
24+
void function2()
25+
{
26+
}
27+
28+
/// A test for overloaded functions
29+
/// This is function \b one
30+
void function3(int a)
31+
{
32+
}
33+
34+
/// A test for overloaded functions
35+
/// This is function \b two
36+
void function3(int a, int b)
37+
{
38+
}
39+
40+
/// A test of some mixed tag usage
41+
/// \if CONDITION
42+
/// This \a code fragment shows us something \.
43+
/// \par Minuses:
44+
/// \arg it's senseless
45+
/// \arg it's stupid
46+
/// \arg it's null
47+
///
48+
/// \warning This may not work as expected
49+
/// \code
50+
/// int main() { while(true); }
51+
///
52+
/// int testBlankLine() {}
53+
/// \endcode
54+
/// \endif
55+
void function4()
56+
{
57+
// Note: a comment in the above code block will not get processed
58+
// correctly with this doxygen comment style, because
59+
// DoxygenParser::tokenizeDoxygenComment strips out the leading
60+
// comment characters. Whereas it works in the other doxygen
61+
// comment styles (as shown in the other variations of
62+
// doxygen_basic_translate), this test is modified to remove the
63+
// comment within the code block.
64+
}
65+
66+
67+
void function5(int a)
68+
{
69+
}
70+
///< This is a post comment.
71+
72+
/// Test for default args
73+
/// @param a Some parameter, default is 42
74+
void function6(int a=42)
75+
{
76+
}
77+
78+
class Shape
79+
{
80+
public:
81+
typedef Shape* superType;
82+
};
83+
84+
/// Test for a parameter with difficult type
85+
/// (mostly for python)
86+
/// @param a Very strange param
87+
void function7(Shape::superType *a[10])
88+
{
89+
}
90+
91+
/// Multiple parameters test.
92+
///
93+
/// @param y Vertical coordinate.
94+
/// @param x Horizontal coordinate.
95+
/// @return Arc tangent of @c y/x.
96+
double Atan2(double y, double x)
97+
{
98+
return 0;
99+
}
100+
101+
/// Comment at the end of file should be ignored.
102+
%}

‎Examples/test-suite/java/doxygen_basic_translate_style3_runme.java

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
2+
import doxygen_basic_translate_style3.*;
3+
import com.sun.javadoc.*;
4+
import java.util.HashMap;
5+
6+
public class doxygen_basic_translate_style3_runme {
7+
static {
8+
try {
9+
System.loadLibrary("doxygen_basic_translate_style3");
10+
} catch (UnsatisfiedLinkError e) {
11+
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);
12+
System.exit(1);
13+
}
14+
}
15+
16+
public static void main(String argv[])
17+
{
18+
/*
19+
Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
20+
and calls the start() method of that class with parsed information.
21+
*/
22+
CommentParser parser = new CommentParser();
23+
com.sun.tools.javadoc.Main.execute("doxygen_basic_translate_style3 runtime test",
24+
"CommentParser",
25+
new String[]{"-quiet", "doxygen_basic_translate_style3"});
26+
27+
HashMap<String, String> wantedComments = new HashMap<String, String>();
28+
29+
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function()",
30+
" \n" +
31+
" Brief description.\n" +
32+
" \n" +
33+
" The comment text.\n" +
34+
" @author Some author\n" +
35+
" @return Some number\n" +
36+
" @see function2\n" +
37+
" \n" +
38+
"");
39+
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function2()",
40+
" A test of a very very very very very very very very very very very very very very very very \n" +
41+
" very very very very very long comment string. \n" +
42+
" \n" +
43+
"");
44+
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function4()",
45+
" A test of some mixed tag usage \n" +
46+
" If: CONDITION {\n" +
47+
" This <i>code </i>fragment shows us something . \n" +
48+
" <p alt=\"Minuses: \">\n" +
49+
" <li>it's senseless \n" +
50+
" </li><li>it's stupid \n" +
51+
" </li><li>it's null \n" +
52+
" \n" +
53+
" </li></p>Warning: This may not work as expected \n" +
54+
" \n" +
55+
" {@code \n" +
56+
"int main() { while(true); } \n" +
57+
"\n" +
58+
"int testBlankLine() {} \n" +
59+
" }\n" +
60+
" }\n" +
61+
" \n" +
62+
"");
63+
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function3(int)",
64+
" A test for overloaded functions \n" +
65+
" This is function <b>one </b>\n" +
66+
" \n" +
67+
"");
68+
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function5(int)",
69+
" This is a post comment. \n" +
70+
"");
71+
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function6(int)",
72+
" Test for default args \n" +
73+
" @param a Some parameter, default is 42" +
74+
" \n" +
75+
"");
76+
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function6()",
77+
" Test for default args \n" +
78+
" \n" +
79+
"");
80+
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function7(doxygen_basic_translate_style3.SWIGTYPE_p_p_p_Shape)",
81+
" Test for a parameter with difficult type \n" +
82+
" (mostly for python) \n" +
83+
" @param a Very strange param \n" +
84+
"");
85+
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function3(int, int)",
86+
" A test for overloaded functions \n" +
87+
" This is function <b>two </b>\n" +
88+
" \n" +
89+
"");
90+
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.Atan2(double, double)",
91+
" Multiple parameters test.\n" +
92+
" \n" +
93+
" @param y Vertical coordinate.\n" +
94+
" @param x Horizontal coordinate.\n" +
95+
" @return Arc tangent of <code>y/x</code>.\n" +
96+
"");
97+
98+
// and ask the parser to check comments for us
99+
System.exit(parser.check(wantedComments));
100+
}
101+
}

‎Examples/test-suite/python/doxygen_basic_translate_style3_runme.py

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
import doxygen_basic_translate_style3
2+
import inspect
3+
import string
4+
import sys
5+
import comment_verifier
6+
7+
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function),
8+
"""\
9+
Brief description.
10+
11+
The comment text.
12+
13+
Author: Some author
14+
15+
:rtype: int
16+
:return: Some number
17+
18+
See also: function2"""
19+
)
20+
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function2),
21+
"""\
22+
A test of a very very very very very very very very very very very very very very very very
23+
very very very very very long comment string."""
24+
)
25+
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function3),
26+
"""*Overload 1:*
27+
A test for overloaded functions
28+
This is function **one**
29+
30+
|
31+
32+
*Overload 2:*
33+
A test for overloaded functions
34+
This is function **two**"""
35+
)
36+
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function4),
37+
"""\
38+
A test of some mixed tag usage
39+
If: CONDITION {
40+
This *code* fragment shows us something .
41+
Title: Minuses:
42+
* it\'s senseless
43+
* it\'s stupid
44+
* it\'s null
45+
46+
Warning: This may not work as expected
47+
48+
.. code-block:: c++
49+
50+
int main() { while(true); }
51+
52+
int testBlankLine() {}
53+
}"""
54+
)
55+
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function5),
56+
"""This is a post comment."""
57+
)
58+
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function6),
59+
"""\
60+
Test for default args
61+
:type a: int
62+
:param a: Some parameter, default is 42"""
63+
)
64+
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function7),
65+
"""\
66+
Test for a parameter with difficult type
67+
(mostly for python)
68+
:type a: :py:class:`Shape`
69+
:param a: Very strange param"""
70+
)
71+
72+
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.Atan2),
73+
"""\
74+
Multiple parameters test.
75+
76+
:type y: float
77+
:param y: Vertical coordinate.
78+
:type x: float
79+
:param x: Horizontal coordinate.
80+
:rtype: float
81+
:return: Arc tangent of ``y/x``."""
82+
)

‎Source/CParse/cscanner.c

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -433,6 +433,19 @@ static int yylook(void) {
433433
Scanner_locator(scan, cmt);
434434
}
435435
if (scan_doxygen_comments) { /* else just skip this node, to avoid crashes in parser module*/
436+
437+
int slashStyle = 0; /* Flag for "///" style doxygen comments */
438+
if (strncmp(loc, "///", 3) == 0) {
439+
slashStyle = 1;
440+
if (Len(cmt) == 3) {
441+
/* Modify to make length=4 to ensure that the empty comment does
442+
get processed to preserve the newlines in the original
443+
comments. */
444+
cmt = NewStringf("%s ", cmt);
445+
loc = Char(cmt);
446+
}
447+
}
448+
436449
/* Check for all possible Doxygen comment start markers while ignoring
437450
comments starting with a row of asterisks or slashes just as
438451
Doxygen itself does. Also skip empty comment (slash-star-star-slash),
@@ -462,6 +475,13 @@ static int yylook(void) {
462475
Setline(yylval.str, Scanner_start_line(scan));
463476
Setfile(yylval.str, Scanner_file(scan));
464477
} else {
478+
if (slashStyle) {
479+
/* Add a newline to the end of each doxygen "///" comment,
480+
since they are processed individually, unlike the
481+
slash-star style, which gets processed as a block with
482+
newlines included. */
483+
Append(yylval.str, "\n");
484+
}
465485
Append(yylval.str, str);
466486
}
467487

0 commit comments

Comments
 (0)