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

Don't indent Doxygen doc strings in generated Python code.

Browse source 
This is unnecessary and inconsistent with "builtin" case in which the
docstrings are not indented in the generated C++ code, thus making it
impossible to write tests working in both cases.

Most of the changes in this commit simply remove the extra whitespace from the
expected values in the tests.
This commit is contained in:
Vadim Zeitlin 2014-12-15 12:58:03 +01:00
commit 410b508e9a
9 changed files with 471 additions and 535 deletions
Download patch file Download diff file Expand all files Collapse all files

11
Examples/test-suite/python/doxygen_basic_notranslate_runme.py
View file

@ -14,7 +14,6 @@ commentVerifier.check(doxygen_basic_notranslate.function.__doc__,
\author Some author \author Some author
\return Some number \return Some number
\sa function2 \sa function2
""" """
) )
@ -22,13 +21,11 @@ commentVerifier.check(doxygen_basic_notranslate.function2.__doc__,
r""" r"""
A test of a very very very very very very very very very very very very very very very very 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. very very very very very long comment string.
""" """
) )
commentVerifier.check(doxygen_basic_notranslate.function3.__doc__, commentVerifier.check(doxygen_basic_notranslate.function3.__doc__,
r""" r""" *Overload 1:*
*Overload 1:*
A test for overloaded functions A test for overloaded functions
This is function \b one This is function \b one
@ -38,8 +35,7 @@ commentVerifier.check(doxygen_basic_notranslate.function3.__doc__,
*Overload 2:* *Overload 2:*
A test for overloaded functions A test for overloaded functions
This is function \b two This is function \b two"""
"""
) )
commentVerifier.check(doxygen_basic_notranslate.function4.__doc__, commentVerifier.check(doxygen_basic_notranslate.function4.__doc__,
@ -58,7 +54,6 @@ commentVerifier.check(doxygen_basic_notranslate.function4.__doc__,
int main() { while(true); } int main() { while(true); }
\endcode \endcode
\endif \endif
""" """
) )
commentVerifier.check(doxygen_basic_notranslate.function5.__doc__, commentVerifier.check(doxygen_basic_notranslate.function5.__doc__,
@ -68,7 +63,6 @@ commentVerifier.check(doxygen_basic_notranslate.function6.__doc__,
r""" r"""
Test for default args Test for default args
@param a Some parameter, default is 42 @param a Some parameter, default is 42
""" """
) )
commentVerifier.check(doxygen_basic_notranslate.function7.__doc__, commentVerifier.check(doxygen_basic_notranslate.function7.__doc__,
@ -76,6 +70,5 @@ commentVerifier.check(doxygen_basic_notranslate.function7.__doc__,
Test for a parameter with difficult type Test for a parameter with difficult type
(mostly for python) (mostly for python)
@param a Very strange param @param a Very strange param
""" """
) )

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

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

1
Examples/test-suite/python/doxygen_ignore_runme.py
View file

@ -17,5 +17,4 @@ commentVerifier.check(doxygen_ignore.func.__doc__,
Command ignored, but anything here is still included. Command ignored, but anything here is still included.
""") """)

125
Examples/test-suite/python/doxygen_misc_constructs_runme.py
View file

@ -8,49 +8,46 @@ import commentVerifier
commentVerifier.check(doxygen_misc_constructs.getAddress.__doc__, commentVerifier.check(doxygen_misc_constructs.getAddress.__doc__,
r""" r"""
Returns address of file line. Returns address of file line.
:type fileName: int :type fileName: int
:param fileName: name of the file, where the source line is located :param fileName: name of the file, where the source line is located
:type line: int :type line: int
:param line: line number :param line: line number
:type isGetSize: boolean :type isGetSize: boolean
:param isGetSize: if set, for every object location both address and size are returned :param isGetSize: if set, for every object location both address and size are returned
Connection::getId() Connection::getId()
""")
""")
commentVerifier.check(doxygen_misc_constructs.CConnectionConfig.__doc__, commentVerifier.check(doxygen_misc_constructs.CConnectionConfig.__doc__,
r""" r"""
This class contains information for connection to winIDEA. Its methods This class contains information for connection to winIDEA. Its methods
return reference to self, so we can use it like this: return reference to self, so we can use it like this:
CConnectionConfig config = new CConnectionConfig(); CConnectionConfig config = new CConnectionConfig();
config.discoveryPort(5534).dllPath("C:\\myWinIDEA\\connect.dll").id("main"); config.discoveryPort(5534).dllPath("C:\\myWinIDEA\\connect.dll").id("main");
All parameters are optional. Set only what is required, default values are All parameters are optional. Set only what is required, default values are
used for unspecified parameters. used for unspecified parameters.
advancedWinIDEALaunching.py Python example. advancedWinIDEALaunching.py Python example.
""")
""")
commentVerifier.check(doxygen_misc_constructs.waitTime.__doc__, commentVerifier.check(doxygen_misc_constructs.waitTime.__doc__,
r""" r"""
Determines how long the ``isystem.connect`` should wait for running Determines how long the ``isystem.connect`` should wait for running
instances to respond. Only one of ``lfWaitXXX`` flags from IConnect::ELaunchFlags instances to respond. Only one of ``lfWaitXXX`` flags from IConnect::ELaunchFlags
may be specified. may be specified."""
"""
) )
commentVerifier.check(doxygen_misc_constructs.getConnection.__doc__, commentVerifier.check(doxygen_misc_constructs.getConnection.__doc__,
r""" r"""
This function returns connection id.
""" This function returns connection id."""
) )
@ -60,8 +57,7 @@ commentVerifier.check(doxygen_misc_constructs.getFirstLetter.__doc__,
commentVerifier.check(doxygen_misc_constructs.ClassWithNestedEnum.__doc__, commentVerifier.check(doxygen_misc_constructs.ClassWithNestedEnum.__doc__,
r""" r"""
Class description. Class description."""
"""
) )
commentVerifier.check(doxygen_misc_constructs.showList.__doc__, commentVerifier.check(doxygen_misc_constructs.showList.__doc__,
@ -75,22 +71,17 @@ commentVerifier.check(doxygen_misc_constructs.showList.__doc__,
is preserved. is preserved.
- And the final list item after it. - And the final list item after it.
And this is not a list item any more. And this is not a list item any more."""
"""
) )
commentVerifier.check(doxygen_misc_constructs.isNoSpaceValidA.__doc__, commentVerifier.check(doxygen_misc_constructs.isNoSpaceValidA.__doc__,
r""" r"""This comment without space after '*' is valid in Doxygen.
This comment without space after '*' is valid in Doxygen. """
"""
) )
commentVerifier.check(doxygen_misc_constructs.isNoSpaceValidB.__doc__, commentVerifier.check(doxygen_misc_constructs.isNoSpaceValidB.__doc__,
r""" r""".This comment without space after '*' is valid in Doxygen.
.This comment without space after '*' is valid in Doxygen. """
"""
) )
commentVerifier.check(doxygen_misc_constructs.isNoSpaceValidC.__doc__, commentVerifier.check(doxygen_misc_constructs.isNoSpaceValidC.__doc__,
@ -99,53 +90,50 @@ commentVerifier.check(doxygen_misc_constructs.isNoSpaceValidC.__doc__,
commentVerifier.check(doxygen_misc_constructs.backslashA.__doc__, commentVerifier.check(doxygen_misc_constructs.backslashA.__doc__,
r""" r"""
Backslash following``word`` is a valid doxygen command. Output contains Backslash following``word`` is a valid doxygen command. Output contains
'followingword' with 'word' in code font. 'followingword' with 'word' in code font."""
"""
) )
commentVerifier.check(doxygen_misc_constructs.backslashB.__doc__, commentVerifier.check(doxygen_misc_constructs.backslashB.__doc__,
r""" r"""
Doxy command without trailing space is ignored - nothing appears Doxy command without trailing space is ignored - nothing appears
on output. Standalone \ and '\' get to output. on output. Standalone \ and '\' get to output.
Standalone @ and '@' get to output. Standalone @ and '@' get to output.
Commands "in quoted \b strings are treated as plain text". Commands "in quoted \b strings are treated as plain text".
Commands not recognized by Doxygen are ignored. Commands not recognized by Doxygen are ignored.
Backslashes in DOS paths d:and words Backslashes in DOS paths d:and words
following them do not appear on output, we must quote them with following them do not appear on output, we must quote them with
double quotes: "d:\xyz\qwe\myfile", "@something". Single quotes do not help: double quotes: "d:\xyz\qwe\myfile", "@something". Single quotes do not help:
'd:'. Escaping works: d:\xyz\qwe\myfile. Unix 'd:'. Escaping works: d:\xyz\qwe\myfile. Unix
paths of course have no such problems: /xyz/qwe/myfile paths of course have no such problems: /xyz/qwe/myfile
Commands for escaped symbols: Commands for escaped symbols:
$ @ \ & ~ < > # % " . :: @text ::text $ @ \ & ~ < > # % " . :: @text ::text"""
"""
) )
commentVerifier.check(doxygen_misc_constructs.backslashC.__doc__, commentVerifier.check(doxygen_misc_constructs.backslashC.__doc__,
r""" r"""
Backslash e at end of *line* froze SWIG Backslash e at end of *line* froze SWIG
*with* old comment parser. *with* old comment parser.
See also: MyClass::fun(char, See also: MyClass::fun(char,
float) float)"""
"""
) )
commentVerifier.check(doxygen_misc_constructs.cycle.__doc__, commentVerifier.check(doxygen_misc_constructs.cycle.__doc__,
r""" r"""
The next line contains expression: The next line contains expression:
['retVal < 10', 'g_counter == 23 && g_mode & 3'] ['retVal < 10', 'g_counter == 23 && g_mode & 3']
Both words should be emphasized **isystem.connect**. Both words should be emphasized **isystem.connect**.
But not the last period. For **example**, comma should not be emphasized. But not the last period. For **example**, comma should not be emphasized.
Similar **for**: double colon. Similar **for**: double colon.
Spaces at the start of line should be taken into account: Spaces at the start of line should be taken into account:
:type id: int :type id: int
:param id: used as prefix in log :param id: used as prefix in log
statements. The default value is empty string, which is OK if statements. The default value is empty string, which is OK if
there is only one app. instance. Example: there is only one app. instance. Example:
@ -156,7 +144,6 @@ commentVerifier.check(doxygen_misc_constructs.cycle.__doc__,
main_ctrl.setBP("func1"); main_ctrl.setBP("func1");
:type fileName: string :type fileName: string
:param fileName: name of the log file :param fileName: name of the log file"""
"""
); );

67
Examples/test-suite/python/doxygen_parsing_runme.py
View file

@ -7,72 +7,61 @@ import commentVerifier
commentVerifier.check(doxygen_parsing.someFunction.__doc__, commentVerifier.check(doxygen_parsing.someFunction.__doc__,
r""" r"""
The function comment The function comment""")
""")
commentVerifier.check(doxygen_parsing.SomeClass.__doc__, commentVerifier.check(doxygen_parsing.SomeClass.__doc__,
r""" r"""
The class comment The class comment""")
""")
commentVerifier.check(doxygen_parsing.SomeStruct.__doc__, commentVerifier.check(doxygen_parsing.SomeStruct.__doc__,
r""" r"""
The struct comment The struct comment""")
""")
commentVerifier.check(doxygen_parsing.SomeAnotherClass.__init__.__doc__, commentVerifier.check(doxygen_parsing.SomeAnotherClass.__init__.__doc__,
r""" r""" *Overload 1:*
*Overload 1:*
First overloaded constructor. First overloaded constructor.
| |
*Overload 2:* *Overload 2:*
Second overloaded constructor. Second overloaded constructor.""")
""")
commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethod.__doc__, commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethod.__doc__,
r""" r"""
The class method comment. The class method comment.
SomeAnotherClass#classMethodExtended(int, int) a link text SomeAnotherClass#classMethodExtended(int, int) a link text""")
""")
commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended.__doc__, commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended.__doc__,
r""" r"""
The class method with parameter The class method with parameter
:type a: int :type a: int
:param a: Parameter a :param a: Parameter a
:type b: int :type b: int
:param b: Parameter b :param b: Parameter b"""
"""
) )
commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended2.__doc__, commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended2.__doc__,
r""" r"""
The class method with parameter The class method with parameter
:type a: int :type a: int
:param a: Parameter a :param a: Parameter a
:type b: int :type b: int
:param b: Parameter b :param b: Parameter b"""
"""
) )
commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethod.__doc__, commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethod.__doc__,
r""" r"""
The struct method comment The struct method comment""")
""")
commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended.__doc__, commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended.__doc__,
r""" r"""
The struct method with parameter The struct method with parameter
:type a: int :type a: int
:param a: Parameter a :param a: Parameter a
:type b: int :type b: int
:param b: Parameter b :param b: Parameter b"""
"""
) )
commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended2.__doc__, commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended2.__doc__,
r""" r"""
The struct method with parameter The struct method with parameter
:type a: int :type a: int
:param a: Parameter a :param a: Parameter a
:type b: int :type b: int
:param b: Parameter b :param b: Parameter b""")
""")

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

@ -8,46 +8,45 @@ import commentVerifier
commentVerifier.check(doxygen_translate_all_tags.func01.__doc__, commentVerifier.check(doxygen_translate_all_tags.func01.__doc__,
r""" r"""
*Hello* *Hello*
* some list item * some list item
This is attention! This is attention!
You were warned! You were warned!
Authors: lots of them Authors: lots of them
Author: Zubr Author: Zubr
**boldword** **boldword**
Some brief description, Some brief description,
extended to many lines. extended to many lines.
Not everything works right now... Not everything works right now...
``codeword`` ``codeword``
'citationword' 'citationword'
.. code-block:: c++ .. code-block:: c++
some test code some test code
""")
""")
commentVerifier.check(doxygen_translate_all_tags.func02.__doc__, commentVerifier.check(doxygen_translate_all_tags.func02.__doc__,
r""" r"""
Conditional comment: SOMECONDITION Conditional comment: SOMECONDITION
Some conditional comment Some conditional comment
End of conditional comment. End of conditional comment.
@ -55,23 +54,22 @@ r"""
Copyright: some copyright Copyright: some copyright
1970 - 2012 1970 - 2012
Deprecated: Now use another function Deprecated: Now use another function
This is very large This is very large
and detailed description of some thing and detailed description of some thing""")
""")
commentVerifier.check(doxygen_translate_all_tags.func03.__doc__, commentVerifier.check(doxygen_translate_all_tags.func03.__doc__,
r""" r"""
Comment for **func03()**. Comment for **func03()**.
@ -81,32 +79,32 @@ r"""
*italicword* *italicword*
emphazedWord emphazedWord
Example: someFile.txt Example: someFile.txt
Some details on using the example Some details on using the example""")
""")
commentVerifier.check(doxygen_translate_all_tags.func04.__doc__, commentVerifier.check(doxygen_translate_all_tags.func04.__doc__,
r""" r"""
:raises: SuperError
: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:: .. math::
\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
.. math:: .. math::
\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \sqrt{(x_2-x_1)^2+(y_2-y_1)^2}
@ -121,13 +119,12 @@ r"""
This will only appear in hmtl This will only appear in hmtl
""")
""")
commentVerifier.check(doxygen_translate_all_tags.func05.__doc__, commentVerifier.check(doxygen_translate_all_tags.func05.__doc__,
r""" r"""
If: ANOTHERCONDITION { If: ANOTHERCONDITION {
First part of comment First part of comment
If: SECONDCONDITION { If: SECONDCONDITION {
Nested condition text Nested condition text
@ -135,17 +132,17 @@ r"""
The third condition text The third condition text
}Else: { The last text block }Else: { The last text block
} }
}Else: { Second part of comment }Else: { Second part of comment
If: CONDITION { If: CONDITION {
Second part extended Second part extended
} }
} }
If not: SOMECONDITION { If not: SOMECONDITION {
This is printed if not This is printed if not
} }
Image: testImage.bmp("Hello, world!") Image: testImage.bmp("Hello, world!")
@ -157,35 +154,34 @@ r"""
Some text Some text
describing invariant. describing invariant.""")
""")
commentVerifier.check(doxygen_translate_all_tags.func06.__doc__, commentVerifier.check(doxygen_translate_all_tags.func06.__doc__,
r""" r"""
Comment for **func06()**. Comment for **func06()**.
This will only appear in LATeX This will only appear in LATeX
* Some unordered list * Some unordered list
* With lots of items * With lots of items
* lots of lots of items * lots of lots of items
someMember Some description follows someMember Some description follows
This will only appear in man This will only appear in man
@ -197,59 +193,62 @@ r"""
""")
""")
commentVerifier.check(doxygen_translate_all_tags.func07.__doc__, commentVerifier.check(doxygen_translate_all_tags.func07.__doc__,
r""" r"""
Comment for **func07()**. Comment for **func07()**.
Notes: Here Notes: Here
is the note! is the note!
This is an overloaded member function, provided for convenience. This is an overloaded member function, provided for convenience.
It differs from the above function only in what argument(s) it accepts. It differs from the above function only in what argument(s) it accepts.
someword someword
Title: The paragraph title Title: The paragraph title
The paragraph text. The paragraph text.
Maybe even multiline Maybe even multiline
:type a: int :type a: int
:param a: the first param :param a: the first param
""")
""")
commentVerifier.check(doxygen_translate_all_tags.func08.__doc__, commentVerifier.check(doxygen_translate_all_tags.func08.__doc__,
r""" r"""
Text after anchor.
Text after anchor.
'Anchor description' 'Anchor description'
'someAnchor' not quoted text is not part of ref tag 'someAnchor' not quoted text is not part of ref tag
'someAnchor' 'someAnchor'
@ -259,38 +258,38 @@ r"""
Remarks: Some remark text Remarks: Some remark text
Another remarks section Another remarks section
:rtype: int :rtype: int
:return: Whatever :return: Whatever
:rtype: int :rtype: int
:return: it :return: it
:rtype: int :rtype: int
:return: may return :return: may return
""")
""")
commentVerifier.check(doxygen_translate_all_tags.func09.__doc__, commentVerifier.check(doxygen_translate_all_tags.func09.__doc__,
r""" r"""
This will only appear in RTF
This will only appear in RTF
See also: someOtherMethod See also: someOtherMethod
See also: function See also: function
Same as Same as
brief description brief description
Since: version 0.0.0.1 Since: version 0.0.0.1
@ -306,17 +305,16 @@ r"""
:raises: superException :raises: superException
:raises: RuntimeError :raises: RuntimeError""")
""")
commentVerifier.check(doxygen_translate_all_tags.func10.__doc__, commentVerifier.check(doxygen_translate_all_tags.func10.__doc__,
r""" r"""
TODO: Some very important task TODO: Some very important task
:type b: float :type b: float
:param b: B is mentioned again... :param b: B is mentioned again...
@ -324,24 +322,23 @@ r"""
very long very long
text with tags <sometag> text with tags <sometag>
Version: 0.0.0.2 Version: 0.0.0.2
Warning: This is senseless! Warning: This is senseless!
This will only appear in XML This will only appear in XML
Here goes test of symbols: Here goes test of symbols:
$ @ \ & ~ < > # % " . :: $ @ \ & ~ < > # % " . ::
And here goes simple text And here goes simple text""")
""")

39
Examples/test-suite/python/doxygen_translate_links_runme.py
View file

@ -8,35 +8,34 @@ import commentVerifier
commentVerifier.check(doxygen_translate_links.function.__doc__, commentVerifier.check(doxygen_translate_links.function.__doc__,
r""" r"""
Testing typenames converting in @ link Testing typenames converting in @ link
superFunc(int,std::string) superFunc(int,std::string)
Test for std_string member Test for std_string member
superFunc(int,long,void*) superFunc(int,long,void*)
Test for simple types Test for simple types
superFunc(Shape::superType*) superFunc(Shape::superType*)
Test for custom types Test for custom types
superFunc(int**[13]) superFunc(int**[13])
Test for complex types Test for complex types
same works for 'See also:' links: same works for 'See also:' links:
See also: superFunc(int,std::string) See also: superFunc(int,std::string)
See also: superFunc(int,long,void*) See also: superFunc(int,long,void*)
See also: superFunc(Shape::superType*) See also: superFunc(Shape::superType*)
See also: superFunc(int**[13]) See also: superFunc(int**[13])
some failing params: some failing params:
See also: superFunc() See also: superFunc()
See also: superFunc() See also: superFunc()
See also: superFunc() See also: superFunc()
""")
""")

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

@ -8,42 +8,42 @@ import commentVerifier
commentVerifier.check(doxygen_translate.function.__doc__, commentVerifier.check(doxygen_translate.function.__doc__,
r""" r"""
*Hello* *Hello*
* some list item * some list item
Authors: lots of them Authors: lots of them
Author: Zubr Author: Zubr
**boldword** **boldword**
``codeword`` ``codeword``
'citationword' 'citationword'
.. code-block:: c++ .. code-block:: c++
some test code some test code
Conditional comment: SOMECONDITION Conditional comment: SOMECONDITION
Some conditional comment Some conditional comment
End of conditional comment. End of conditional comment.
Copyright: some copyright Copyright: some copyright
Deprecated: Now use another function Deprecated: Now use another function
*italicword* *italicword*
Example: someFile.txt Example: someFile.txt
Some details on using the example Some details on using the example
:raises: SuperError :raises: SuperError
If: ANOTHERCONDITION { If: ANOTHERCONDITION {
First part of comment First part of comment
If: SECONDCONDITION { If: SECONDCONDITION {
Nested condition text Nested condition text
@ -51,189 +51,187 @@ r"""
The third condition text The third condition text
}Else: { The last text block }Else: { The last text block
} }
}Else: { Second part of comment }Else: { Second part of comment
If: CONDITION { If: CONDITION {
Second part extended Second part extended
} }
} }
If not: SOMECONDITION { If not: SOMECONDITION {
This is printed if not This is printed if not
} }
Image: testImage.bmp("Hello, world!") Image: testImage.bmp("Hello, world!")
* Some unordered list * Some unordered list
* With lots of items * With lots of items
* lots of lots of items * lots of lots of items
someMember Some description follows someMember Some description follows
Notes: Here Notes: Here
is the note! is the note!
This is an overloaded member function, provided for convenience. This is an overloaded member function, provided for convenience.
It differs from the above function only in what argument(s) it accepts. It differs from the above function only in what argument(s) it accepts.
someword someword
Title: The paragraph title Title: The paragraph title
The paragraph text. The paragraph text.
Maybe even multiline Maybe even multiline
:type a: int :type a: int
:param a: the first param :param a: the first param
Remarks: Some remark text Remarks: Some remark text
Another remarks section Another remarks section
:rtype: int :rtype: int
:return: Whatever :return: Whatever
:rtype: int :rtype: int
:return: it :return: it
:rtype: int :rtype: int
:return: may return :return: may return
See also: someOtherMethod See also: someOtherMethod
See also: function See also: function
Since: version 0.0.0.1 Since: version 0.0.0.1
:raises: superException :raises: superException
:raises: RuntimeError :raises: RuntimeError
TODO: Some very important task TODO: Some very important task
:type b: float :type b: float
:param b: B is mentioned again... :param b: B is mentioned again...
very long very long
text with tags <sometag> text with tags <sometag>
Version: 0.0.0.2 Version: 0.0.0.2
Warning: This is senseless! Warning: This is senseless!
Here goes test of symbols: Here goes test of symbols:
$ @ \ & ~ < > # % " . :: $ @ \ & ~ < > # % " . ::
And here goes simple text And here goes simple text"""
"""
) )
commentVerifier.check(doxygen_translate.htmlFunction.__doc__, commentVerifier.check(doxygen_translate.htmlFunction.__doc__,
r""" r"""
Test for html tags. See Doxygen doc for list of tags recognized by Doxygen. Test for html tags. See Doxygen doc for list of tags recognized by Doxygen.
This is link ("http://acme.com/index.html") This is link ("http://acme.com/index.html")
**bold** **bold**
Quote: Quote:
Quotation block. Quotation block.
("http://www.worldwildlife.org/who/index.html") ("http://www.worldwildlife.org/who/index.html")
center center
``this is code`` ``this is code``
Starts an item title. Starts an item title.
Starts an item description. Starts an item description.
Starts a piece of text displayed in a typewriter font. Starts a piece of text displayed in a typewriter font.
Starts a section with a specific style (HTML only) Starts a section with a specific style (HTML only)
**Starts a piece of text displayed in an italic font.** **Starts a piece of text displayed in an italic font.**
'Form' does not generate any output. 'Form' does not generate any output.
-------------------------------------------------------------------- --------------------------------------------------------------------
# Heading 1 # Heading 1
## Heading 2 ## Heading 2
### Heading 3 ### Heading 3
*Starts a piece of text displayed in an italic font.* *Starts a piece of text displayed in an italic font.*
Input tag. Input tag.
Image: src="slika.png" Image: src="slika.png"
Meta tag. Meta tag.
Multicol is ignored by doxygen. Multicol is ignored by doxygen.
* List item 1. * List item 1.
* List item 2. * List item 2.
Starts a new paragraph. Starts a new paragraph.
Starts a preformatted fragment. Starts a preformatted fragment.
Starts a section of text displayed in a smaller font. Starts a section of text displayed in a smaller font.
'Starts an inline text fragment with a specific style.' 'Starts an inline text fragment with a specific style.'
**Starts a section of bold text.** **Starts a section of bold text.**
Starts a piece of text displayed in subscript. Starts a piece of text displayed in subscript.
Starts a piece of text displayed in superscript. Starts a piece of text displayed in superscript.
Animals Animals
| Column 1 | Column 2 | | Column 1 | Column 2 |
----------------------- -----------------------
| cow | dog | | cow | dog |
| cat | mouse | | cat | mouse |
| horse | parrot | | horse | parrot |
Starts a piece of text displayed in a typewriter font. Starts a piece of text displayed in a typewriter font.
Starts a piece of text displayed in a typewriter font. Starts a piece of text displayed in a typewriter font.
* List item 1. * List item 1.
* List item 2. * List item 2.
* List item 3. * List item 3.
*Starts a piece of text displayed in an italic font.* *Starts a piece of text displayed in an italic font.*
<u>underlined \b bold text - doxy commands are ignored inside 'htmlonly' section </u> <u>underlined \b bold text - doxy commands are ignored inside 'htmlonly' section </u>
""")
""")
commentVerifier.check(doxygen_translate.htmlTableFunction.__doc__, commentVerifier.check(doxygen_translate.htmlTableFunction.__doc__,
r""" r"""
The meaning of flags: The meaning of flags:
:type byFlags: int :type byFlags: int
:param byFlags: bits marking required items: :param byFlags: bits marking required items:
| Size in bits| Items Required | | Size in bits| Items Required |
-------------------------------- --------------------------------
@ -242,33 +240,31 @@ r"""
| 17 - 32 | 4 | | 17 - 32 | 4 |
Almost all combinations of above flags are supported by Almost all combinations of above flags are supported by
``htmlTable...`` functions. ``htmlTable...`` functions.""")
""")
commentVerifier.check(doxygen_translate.htmlEntitiesFunction.__doc__, commentVerifier.check(doxygen_translate.htmlEntitiesFunction.__doc__,
r""" r"""
All entities are treated as commands (C) TM (R) All entities are treated as commands (C) TM (R)
should work also<in text should work also<in text
> >
& &
' '
" "
` `
' '
" "
" "
- -
-- --
x x
- -
. .
~ ~
<= <=
>= >=
<-- <--
--> -->
Not an html entity - ignored by Doxygen. Not an html entity - ignored by Doxygen.
Not an &text html entity - ampersand is replaced with entity. Not an &text html entity - ampersand is replaced with entity.""")
""")

37
Source/Modules/python.cxx
View file

@ -1545,21 +1545,12 @@ public:
* Get the docstring text enclosed in triple double quotes. * Get the docstring text enclosed in triple double quotes.
* ------------------------------------------------------------ */ * ------------------------------------------------------------ */
String *docstring(Node *n, autodoc_t ad_type, const String *indent) { String *docstring(Node *n, autodoc_t ad_type) {
String *docstr = build_combined_docstring(n, ad_type); String *docstr = build_combined_docstring(n, ad_type);
if (!Len(docstr)) if (!Len(docstr))
return docstr; return docstr;
// If there is more than one line then make docstrings like this:
//
// """
// This is line1
// And here is line2 followed by the rest of them
// """
//
// otherwise, put it all on a single line
//
// Notice that all comments are created as raw strings (prefix "r"), // Notice that all comments are created as raw strings (prefix "r"),
// because '\' is used often in comments, but may break Python module from // because '\' is used often in comments, but may break Python module from
// loading. For example, in doxy comment one may write path in quotes: // loading. For example, in doxy comment one may write path in quotes:
@ -1571,15 +1562,7 @@ public:
// of doxygen doc, Latex expressions, ... // of doxygen doc, Latex expressions, ...
String *doc = NewString(""); String *doc = NewString("");
Append(doc, "r\"\"\""); Append(doc, "r\"\"\"");
if (Strchr(docstr, '\n') == 0) {
Append(doc, docstr); Append(doc, docstr);
} else {
Append(doc, "\n");
Append(doc, pythoncode(docstr, indent));
Append(doc, indent);
}
Append(doc, "\"\"\""); Append(doc, "\"\"\"");
Delete(docstr); Delete(docstr);
@ -2137,7 +2120,7 @@ public:
/* Make a wrapper function to insert the code into */ /* Make a wrapper function to insert the code into */
Printv(f_dest, "\ndef ", name, "(", parms, ")", returnTypeAnnotation(n), ":\n", NIL); Printv(f_dest, "\ndef ", name, "(", parms, ")", returnTypeAnnotation(n), ":\n", NIL);
if (have_docstring(n)) if (have_docstring(n))
Printv(f_dest, tab4, docstring(n, AUTODOC_FUNC, tab4), "\n", NIL); Printv(f_dest, tab4, docstring(n, AUTODOC_FUNC), "\n", NIL);
if (have_pythonprepend(n)) if (have_pythonprepend(n))
Printv(f_dest, pythoncode(pythonprepend(n), tab4), "\n", NIL); Printv(f_dest, pythoncode(pythonprepend(n), tab4), "\n", NIL);
if (have_pythonappend(n)) { if (have_pythonappend(n)) {
@ -3274,7 +3257,7 @@ public:
if (f_s) { if (f_s) {
Printv(f_s, iname, " = ", module, ".", iname, "\n", NIL); Printv(f_s, iname, " = ", module, ".", iname, "\n", NIL);
if (have_docstring(n)) if (have_docstring(n))
Printv(f_s, docstring(n, AUTODOC_CONST, ""), "\n", NIL); Printv(f_s, docstring(n, AUTODOC_CONST), "\n", NIL);
} }
} }
return SWIG_OK; return SWIG_OK;
@ -4053,7 +4036,7 @@ public:
// write docstrings if requested // write docstrings if requested
if (have_docstring(n)) { if (have_docstring(n)) {
String *str = docstring(n, AUTODOC_CLASS, tab4); String *str = docstring(n, AUTODOC_CLASS);
if (str && Len(str)) if (str && Len(str))
Printv(f_shadow, tab4, str, "\n", NIL); Printv(f_shadow, tab4, str, "\n", NIL);
} }
@ -4333,7 +4316,7 @@ public:
} else { } else {
Printv(f_shadow, "\n", tab4, "def ", symname, "(", parms, ")", returnTypeAnnotation(n), ":\n", NIL); Printv(f_shadow, "\n", tab4, "def ", symname, "(", parms, ")", returnTypeAnnotation(n), ":\n", NIL);
if (have_docstring(n)) if (have_docstring(n))
Printv(f_shadow, tab8, docstring(n, AUTODOC_METHOD, tab8), "\n", NIL); Printv(f_shadow, tab8, docstring(n, AUTODOC_METHOD), "\n", NIL);
if (have_pythonprepend(n)) { if (have_pythonprepend(n)) {
fproxy = 0; fproxy = 0;
Printv(f_shadow, pythoncode(pythonprepend(n), tab8), "\n", NIL); Printv(f_shadow, pythoncode(pythonprepend(n), tab8), "\n", NIL);
@ -4419,7 +4402,7 @@ public:
String *callParms = make_pyParmList(n, false, true, kw); String *callParms = make_pyParmList(n, false, true, kw);
Printv(f_shadow, "\n", tab4, "def ", symname, "(", parms, ")", returnTypeAnnotation(n), ":\n", NIL); Printv(f_shadow, "\n", tab4, "def ", symname, "(", parms, ")", returnTypeAnnotation(n), ":\n", NIL);
if (have_docstring(n)) if (have_docstring(n))
Printv(f_shadow, tab8, docstring(n, AUTODOC_STATICFUNC, tab8), "\n", NIL); Printv(f_shadow, tab8, docstring(n, AUTODOC_STATICFUNC), "\n", NIL);
if (have_pythonprepend(n)) if (have_pythonprepend(n))
Printv(f_shadow, pythoncode(pythonprepend(n), tab8), "\n", NIL); Printv(f_shadow, pythoncode(pythonprepend(n), tab8), "\n", NIL);
if (have_pythonappend(n)) { if (have_pythonappend(n)) {
@ -4536,7 +4519,7 @@ public:
Printv(f_shadow, "\n", tab4, "def __init__(", parms, ")", returnTypeAnnotation(n), ":\n", NIL); Printv(f_shadow, "\n", tab4, "def __init__(", parms, ")", returnTypeAnnotation(n), ":\n", NIL);
if (have_docstring(n)) if (have_docstring(n))
Printv(f_shadow, tab8, docstring(n, AUTODOC_CTOR, tab8), "\n", NIL); Printv(f_shadow, tab8, docstring(n, AUTODOC_CTOR), "\n", NIL);
if (have_pythonprepend(n)) if (have_pythonprepend(n))
Printv(f_shadow, pythoncode(pythonprepend(n), tab8), "\n", NIL); Printv(f_shadow, pythoncode(pythonprepend(n), tab8), "\n", NIL);
Printv(f_shadow, pass_self, NIL); Printv(f_shadow, pass_self, NIL);
@ -4569,7 +4552,7 @@ public:
Printv(f_shadow_stubs, "\ndef ", symname, "(", parms, ")", returnTypeAnnotation(n), ":\n", NIL); Printv(f_shadow_stubs, "\ndef ", symname, "(", parms, ")", returnTypeAnnotation(n), ":\n", NIL);
if (have_docstring(n)) if (have_docstring(n))
Printv(f_shadow_stubs, tab4, docstring(n, AUTODOC_CTOR, tab4), "\n", NIL); Printv(f_shadow_stubs, tab4, docstring(n, AUTODOC_CTOR), "\n", NIL);
if (have_pythonprepend(n)) if (have_pythonprepend(n))
Printv(f_shadow_stubs, pythoncode(pythonprepend(n), tab4), "\n", NIL); Printv(f_shadow_stubs, pythoncode(pythonprepend(n), tab4), "\n", NIL);
String *subfunc = NULL; String *subfunc = NULL;
@ -4637,7 +4620,7 @@ public:
} }
Printv(f_shadow, tab4, "def __del__(self):\n", NIL); Printv(f_shadow, tab4, "def __del__(self):\n", NIL);
if (have_docstring(n)) if (have_docstring(n))
Printv(f_shadow, tab8, docstring(n, AUTODOC_DTOR, tab8), "\n", NIL); Printv(f_shadow, tab8, docstring(n, AUTODOC_DTOR), "\n", NIL);
if (have_pythonprepend(n)) if (have_pythonprepend(n))
Printv(f_shadow, pythoncode(pythonprepend(n), tab8), "\n", NIL); Printv(f_shadow, pythoncode(pythonprepend(n), tab8), "\n", NIL);
#ifdef USE_THISOWN #ifdef USE_THISOWN
@ -4811,7 +4794,7 @@ public:
} else if (shadow) { } else if (shadow) {
Printv(f_shadow, tab4, symname, " = ", module, ".", Swig_name_member(NSPACE_TODO, class_name, symname), "\n", NIL); Printv(f_shadow, tab4, symname, " = ", module, ".", Swig_name_member(NSPACE_TODO, class_name, symname), "\n", NIL);
if (have_docstring(n)) if (have_docstring(n))
Printv(f_shadow, tab4, docstring(n, AUTODOC_CONST, tab4), "\n", NIL); Printv(f_shadow, tab4, docstring(n, AUTODOC_CONST), "\n", NIL);
} }
return SWIG_OK; return SWIG_OK;
} }