jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge branch 'Issue-1632'

Browse source 
* 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
This commit is contained in:
William S Fulton 2020-01-16 07:19:29 +00:00
commit 55d36e3fd3
5 changed files with 306 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1
Examples/test-suite/common.mk
View file

@ -627,6 +627,7 @@ DOXYGEN_TEST_CASES += \
doxygen_basic_notranslate \
doxygen_basic_translate \
doxygen_basic_translate_style2 \
doxygen_basic_translate_style3 \
doxygen_ignore \
doxygen_misc_constructs \
doxygen_nested_class \

102
Examples/test-suite/doxygen_basic_translate_style3.i Normal file
View file

@ -0,0 +1,102 @@
%module doxygen_basic_translate_style3
%include "doxygen_basic_translate.h"
%inline %{
/// \brief
/// Brief description.
///
/// The comment text.
///
/// \author Some author
///
/// \return Some number
///
/// \sa function2
int function()
{
return 0;
}
/// A test of a very very very very very very very very very very very very very very very very
/// very very very very very long comment string.
void function2()
{
}
/// A test for overloaded functions
/// This is function \b one
void function3(int a)
{
}
/// A test for overloaded functions
/// This is function \b two
void function3(int a, int b)
{
}
/// A test of some mixed tag usage
/// \if CONDITION
/// This \a code fragment shows us something \.
/// \par Minuses:
/// \arg it's senseless
/// \arg it's stupid
/// \arg it's null
///
/// \warning This may not work as expected
/// \code
/// int main() { while(true); }
///
/// int testBlankLine() {}
/// \endcode
/// \endif
void function4()
{
// Note: a comment in the above code block will not get processed
// correctly with this doxygen comment style, because
// DoxygenParser::tokenizeDoxygenComment strips out the leading
// comment characters. Whereas it works in the other doxygen
// comment styles (as shown in the other variations of
// doxygen_basic_translate), this test is modified to remove the
// comment within the code block.
}
void function5(int a)
{
}
///< This is a post comment.
/// Test for default args
/// @param a Some parameter, default is 42
void function6(int a=42)
{
}
class Shape
{
public:
typedef Shape* superType;
};
/// Test for a parameter with difficult type
/// (mostly for python)
/// @param a Very strange param
void function7(Shape::superType *a[10])
{
}
/// Multiple parameters test.
///
/// @param y Vertical coordinate.
/// @param x Horizontal coordinate.
/// @return Arc tangent of @c y/x.
double Atan2(double y, double x)
{
return 0;
}
/// Comment at the end of file should be ignored.
%}

101
Examples/test-suite/java/doxygen_basic_translate_style3_runme.java Normal file
View file

@ -0,0 +1,101 @@
import doxygen_basic_translate_style3.*;
import com.sun.javadoc.*;
import java.util.HashMap;
public class doxygen_basic_translate_style3_runme {
static {
try {
System.loadLibrary("doxygen_basic_translate_style3");
} catch (UnsatisfiedLinkError e) {
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);
System.exit(1);
}
}
public static void main(String argv[])
{
/*
Here we are using internal javadoc tool, it accepts the name of the class as paramterer,
and calls the start() method of that class with parsed information.
*/
CommentParser parser = new CommentParser();
com.sun.tools.javadoc.Main.execute("doxygen_basic_translate_style3 runtime test",
"CommentParser",
new String[]{"-quiet", "doxygen_basic_translate_style3"});
HashMap<String, String> wantedComments = new HashMap<String, String>();
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function()",
" \n" +
" Brief description.\n" +
" \n" +
" The comment text.\n" +
" @author Some author\n" +
" @return Some number\n" +
" @see function2\n" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function2()",
" A test of a very very very very very very very very very very very very very very very very \n" +
" very very very very very long comment string. \n" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function4()",
" A test of some mixed tag usage \n" +
" If: CONDITION {\n" +
" This <i>code </i>fragment shows us something . \n" +
" <p alt=\"Minuses: \">\n" +
" <li>it's senseless \n" +
" </li><li>it's stupid \n" +
" </li><li>it's null \n" +
" \n" +
" </li></p>Warning: This may not work as expected \n" +
" \n" +
" {@code \n" +
"int main() { while(true); } \n" +
"\n" +
"int testBlankLine() {} \n" +
" }\n" +
" }\n" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function3(int)",
" A test for overloaded functions \n" +
" This is function <b>one </b>\n" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function5(int)",
" This is a post comment. \n" +
"");
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function6(int)",
" Test for default args \n" +
" @param a Some parameter, default is 42" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function6()",
" Test for default args \n" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function7(doxygen_basic_translate_style3.SWIGTYPE_p_p_p_Shape)",
" Test for a parameter with difficult type \n" +
" (mostly for python) \n" +
" @param a Very strange param \n" +
"");
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.function3(int, int)",
" A test for overloaded functions \n" +
" This is function <b>two </b>\n" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style3.doxygen_basic_translate_style3.Atan2(double, double)",
" Multiple parameters test.\n" +
" \n" +
" @param y Vertical coordinate.\n" +
" @param x Horizontal coordinate.\n" +
" @return Arc tangent of <code>y/x</code>.\n" +
"");
// and ask the parser to check comments for us
System.exit(parser.check(wantedComments));
}
}

82
Examples/test-suite/python/doxygen_basic_translate_style3_runme.py Normal file
View file

@ -0,0 +1,82 @@
import doxygen_basic_translate_style3
import inspect
import string
import sys
import comment_verifier
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function),
"""\
Brief description.
The comment text.
Author: Some author
:rtype: int
:return: Some number
See also: function2"""
)
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function2),
"""\
A test of a very very very very very very very very very very very very very very very very
very very very very very long comment string."""
)
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function3),
"""*Overload 1:*
A test for overloaded functions
This is function **one**
|
*Overload 2:*
A test for overloaded functions
This is function **two**"""
)
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function4),
"""\
A test of some mixed tag usage
If: CONDITION {
This *code* fragment shows us something .
Title: Minuses:
* it\'s senseless
* it\'s stupid
* it\'s null
Warning: This may not work as expected
.. code-block:: c++
int main() { while(true); }
int testBlankLine() {}
}"""
)
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function5),
"""This is a post comment."""
)
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function6),
"""\
Test for default args
:type a: int
:param a: Some parameter, default is 42"""
)
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.function7),
"""\
Test for a parameter with difficult type
(mostly for python)
:type a: :py:class:`Shape`
:param a: Very strange param"""
)
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style3.Atan2),
"""\
Multiple parameters test.
:type y: float
:param y: Vertical coordinate.
:type x: float
:param x: Horizontal coordinate.
:rtype: float
:return: Arc tangent of ``y/x``."""
)

20
Source/CParse/cscanner.c
View file

@ -433,6 +433,19 @@ static int yylook(void) {
Scanner_locator(scan, cmt);
}
if (scan_doxygen_comments) { /* else just skip this node, to avoid crashes in parser module*/
int slashStyle = 0; /* Flag for "///" style doxygen comments */
if (strncmp(loc, "///", 3) == 0) {
slashStyle = 1;
if (Len(cmt) == 3) {
/* Modify to make length=4 to ensure that the empty comment does
get processed to preserve the newlines in the original
comments. */
cmt = NewStringf("%s ", cmt);
loc = Char(cmt);
}
}
/* Check for all possible Doxygen comment start markers while ignoring
comments starting with a row of asterisks or slashes just as
Doxygen itself does. Also skip empty comment (slash-star-star-slash),
@ -462,6 +475,13 @@ static int yylook(void) {
Setline(yylval.str, Scanner_start_line(scan));
Setfile(yylval.str, Scanner_file(scan));
} else {
if (slashStyle) {
/* Add a newline to the end of each doxygen "///" comment,
since they are processed individually, unlike the
slash-star style, which gets processed as a block with
newlines included. */
Append(yylval.str, "\n");
}
Append(yylval.str, str);
}