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

Merge branch 'doxy/space'

Browse source 
* doxy/space:
  Ensure empty line before code and math blocks in doxygen pydoc
  Remove extra newline before code block in doxygen python output
  Clarify python doxygen code block indentation handling
  Cleanup of pydoc translator newline trimming
  Correction to recently added doxygen python test case
  Adjust expected python output for doxygen style2 test
  Adding test for second doxygen comment style
  Fix bug in doxygen python code block indent
  Eliminate extra newlines around doxygen python block math
  Eliminate extra newlines in doxygen python \verbatim blocks
  Remove extra newline from end of doxygen python \code command
  Remove extra newline in beginning of doxygen python \code command
  Fix python doxygen indentation for inline \code command
This commit is contained in:
William S Fulton 2019-06-28 19:50:39 +01:00
commit 1204297a1b
11 changed files with 400 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -620,6 +620,7 @@ DOXYGEN_TEST_CASES += \
doxygen_alias \
doxygen_basic_notranslate \
doxygen_basic_translate \
doxygen_basic_translate_style2 \
doxygen_ignore \
doxygen_misc_constructs \
doxygen_nested_class \

105
Examples/test-suite/doxygen_basic_translate_style2.i Normal file
View file

@ -0,0 +1,105 @@
%module doxygen_basic_translate_style2
%include "doxygen_basic_translate.h"
// This test demonstrates a doxygen comment style that starts on the
// first line and so uses extra spacing in subsequent lines.
%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); }
* \endcode
* \endif
*/
void function4()
{
}
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.
*/
%}

10
Examples/test-suite/doxygen_translate_all_tags.i
View file

@ -38,6 +38,10 @@
* \cite citationword
* \class someClass headerFile.h headerName
* \code some test code \endcode
*
* Code immediately following text. Pydoc translation must add an
* empty line before:
* \code more test code \endcode
*/
void func01(int a)
{
@ -121,6 +125,12 @@ void func03(int a)
* \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
* \f}
*
* Math immediately following text. Pydoc translation must add an
* empty line before:
* \f[
* \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
* \f]
*
* \file file.h
*
* \fn someFn

99
Examples/test-suite/java/doxygen_basic_translate_style2_runme.java Normal file
View file

@ -0,0 +1,99 @@
import doxygen_basic_translate_style2.*;
import com.sun.javadoc.*;
import java.util.HashMap;
public class doxygen_basic_translate_style2_runme {
static {
try {
System.loadLibrary("doxygen_basic_translate_style2");
} 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_style2 runtime test",
"CommentParser",
new String[]{"-quiet", "doxygen_basic_translate_style2"});
HashMap<String, String> wantedComments = new HashMap<String, String>();
wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.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_style2.doxygen_basic_translate_style2.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_style2.doxygen_basic_translate_style2.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" +
" }\n" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function3(int)",
" A test for overloaded functions \n" +
" This is function <b>one </b>\n" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function5(int)",
" This is a post comment. \n" +
"");
wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function6(int)",
" Test for default args \n" +
" @param a Some parameter, default is 42" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function6()",
" Test for default args \n" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.function7(doxygen_basic_translate_style2.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_style2.doxygen_basic_translate_style2.function3(int, int)",
" A test for overloaded functions \n" +
" This is function <b>two </b>\n" +
" \n" +
"");
wantedComments.put("doxygen_basic_translate_style2.doxygen_basic_translate_style2.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));
}
}

12
Examples/test-suite/java/doxygen_translate_all_tags_runme.java
View file

@ -40,7 +40,10 @@ public class doxygen_translate_all_tags_runme {
" Not everything works right now...\n" +
" <code>codeword</code>\n\n\n\n\n\n" +
" <i>citationword</i>\n" +
" {@code some test code }\n");
" {@code some test code }\n\n" +
" Code immediately following text. Pydoc translation must add an\n" +
" empty line before:\n" +
" {@code more test code }");
wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func02(int)",
" Conditional comment: SOMECONDITION \n" +
@ -63,8 +66,11 @@ public class doxygen_translate_all_tags_runme {
" @exception SuperError \n" +
" \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" +
" \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" +
" \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" +
" This will only appear in hmtl \n");
" \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n\n" +
"Math immediately following text. Pydoc translation must add an\n" +
"empty line before:\n\n" +
" \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\n" +
" This will only appear in hmtl \n");
wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func05(int)",
" If: ANOTHERCONDITION {\n" +

2
Examples/test-suite/python/doxygen_basic_translate_runme.py
View file

@ -49,9 +49,7 @@ Warning: This may not work as expected
.. code-block:: c++
int main() { while(true); }
}"""
)
comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function5),

80
Examples/test-suite/python/doxygen_basic_translate_style2_runme.py Normal file
View file

@ -0,0 +1,80 @@
import doxygen_basic_translate_style2
import inspect
import string
import sys
import comment_verifier
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.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_style2.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_style2.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_style2.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); }
}"""
)
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function5),
"""This is a post comment."""
)
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function6),
"""\
Test for default args
:type a: int
:param a: Some parameter, default is 42"""
)
comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.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_style2.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``."""
)

17
Examples/test-suite/python/doxygen_translate_all_tags_runme.py
View file

@ -34,10 +34,16 @@ Not everything works right now...
'citationword'
.. code-block:: c++
some test code
Code immediately following text. Pydoc translation must add an
empty line before:
.. code-block:: c++
some test code""")
more test code""")
comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func02),
r"""Conditional comment: SOMECONDITION
@ -90,12 +96,16 @@ r""":raises: SuperError
:math:`\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}`
.. math::
\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
.. math::
\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
Math immediately following text. Pydoc translation must add an
empty line before:
.. math::
@ -111,7 +121,6 @@ r""":raises: SuperError
This will only appear in hmtl""")
comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func05),
@ -283,13 +292,11 @@ r"""TODO: Some very important task
very long
text with tags <sometag>
Version: 0.0.0.2
Warning: This is senseless!

6
Examples/test-suite/python/doxygen_translate_runme.py
View file

@ -20,11 +20,9 @@ Author: Zubr
'citationword'
.. code-block:: c++
some test code
some test code
Conditional comment: SOMECONDITION
Some conditional comment
@ -121,11 +119,9 @@ TODO: Some very important task
:type b: float
:param b: B is mentioned again...
very long
text with tags <sometag>
Version: 0.0.0.2
Warning: This is senseless!