fixed doxy documentation (also shortened lines), added test for discovered bug reltaed to nested enums
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2012-doxygen@13728 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Marko Klopcic
parent
faec66879a
commit
e62580acb8
3 changed files with 181 additions and 90 deletions
|
|
@ -43,33 +43,53 @@
|
||||||
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
This chapter describes SWIG's support for translating Doxygen comments found in interface and header files into a target language's normal documentation language.
|
This chapter describes SWIG's support for translating Doxygen comments
|
||||||
Currently only JavaDoc and PythonDoc is supported.
|
found in interface and header files into a target language's normal
|
||||||
|
documentation language. Currently only JavaDoc and PythonDoc is
|
||||||
|
supported.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<H2><a name="Doxygen_translation_overview"></a>39.1 Doxygen Translation Overview</H2>
|
<H2><a name="Doxygen_translation_overview"></a>39.1 Doxygen Translation Overview</H2>
|
||||||
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
The Doxygen Translation Module of SWIG is an ongoing effort from a <A HREF ="http://code.google.com/soc/2008/">Google Summer of Code</A> proposal from Summer 2008.
|
The Doxygen Translation Module of SWIG is an ongoing effort from
|
||||||
It adds an extra layer of functionality to SWIG, allowing automated translation of <A HREF= "http://www.stack.nl/~dimitri/doxygen/">Doxygen</A> formatted comments from input files into a documentation language more suited for the target language.
|
a <A HREF ="http://code.google.com/soc/2008/">Google Summer of
|
||||||
Currently this module only translates into JavaDoc and PythonDoc for the SWIG Java and Python Modules, but other extensions are to be added in time.
|
Code</A> proposal from Summer 2008. It adds an extra layer of
|
||||||
|
functionality to SWIG, allowing automated translation of <A HREF=
|
||||||
|
"http://www.stack.nl/~dimitri/doxygen/">Doxygen</A> formatted comments
|
||||||
|
from input files into a documentation language more suited for the
|
||||||
|
target language. Currently this module only translates into JavaDoc
|
||||||
|
and PythonDoc for the SWIG Java and Python Modules, but other
|
||||||
|
extensions are to be added in time.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Questions about running SWIG are best answered in the <a href="SWIG.html#SWIG">SWIG Basics</a> chapter as well as the target language modules. (For now, only <A href = "Java.html">Java</A> and <A href = "Python.html">Python</A>).
|
Questions about running SWIG are best answered in
|
||||||
The behaviour of this functionality is wildly unpredictable if the interface file is not proper to begin with!
|
the <a href="SWIG.html#SWIG">SWIG Basics</a> chapter as well as the
|
||||||
|
target language modules. (For now, only <A href = "Java.html">Java</A>
|
||||||
|
and <A href = "Python.html">Python</A>). The behaviour of this
|
||||||
|
functionality is wildly unpredictable if the interface file is not
|
||||||
|
proper to begin with!
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<H2><a name="Doxygen_file_preparation"></a>39.2 Preparations</H2>
|
<H2><a name="Doxygen_file_preparation"></a>39.2 Preparations</H2>
|
||||||
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
To make use of the comment translation system, your documentation comments must be in properly formatted <A HREF= "http://www.stack.nl/~dimitri/doxygen/">Doxygen.</A> They can be present in your main interface file or any header file that it imports.
|
To make use of the comment translation system, your documentation
|
||||||
It is advised that you are certain your comments compile properly with Doxygen before you try to translate them.
|
comments must be in properly formatted <A HREF=
|
||||||
Doxygen itself is a deeper tool and can provide you better feedback for correcting any syntax errors that may be present.
|
"http://www.stack.nl/~dimitri/doxygen/">Doxygen.</A> They can be
|
||||||
Please look at Doxygen's <A HREF = "http://www.stack.nl/~dimitri/doxygen/docblocks.html"> Documenting the code</A> for proper specificatons for comment format.
|
present in your main interface file or any header file that it
|
||||||
However, SWIG's Doxygen parser will still point you most of errors and warnings found in comments (like unterminated strings or missing ending tags).
|
imports. It is advised that you are certain your comments compile
|
||||||
|
properly with Doxygen before you try to translate them. Doxygen
|
||||||
|
itself is a deeper tool and can provide you better feedback for
|
||||||
|
correcting any syntax errors that may be present. Please look at
|
||||||
|
Doxygen's <A HREF =
|
||||||
|
"http://www.stack.nl/~dimitri/doxygen/docblocks.html"> Documenting the
|
||||||
|
code</A> for proper specificatons for comment format. However, SWIG's
|
||||||
|
Doxygen parser will still point you most of errors and warnings found
|
||||||
|
in comments (like unterminated strings or missing ending tags).
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<div class="code"><pre>
|
<div class="code"><pre>
|
||||||
|
|
@ -81,8 +101,10 @@ class Shape {
|
||||||
</pre></div>
|
</pre></div>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Currently, the whole subset of Doxygen comment styles is supported (See <A HREF = "http://www.stack.nl/~dimitri/doxygen/docblocks.html"> Documenting the code</A>)
|
Currently, the whole subset of Doxygen comment styles is supported
|
||||||
Here they are:
|
(See <A HREF = "http://www.stack.nl/~dimitri/doxygen/docblocks.html">
|
||||||
|
Documenting the code</A>). Here they are:
|
||||||
|
|
||||||
<div class="code"><pre>
|
<div class="code"><pre>
|
||||||
/**
|
/**
|
||||||
* JavaDoc style comment, multiline
|
* JavaDoc style comment, multiline
|
||||||
|
|
@ -99,15 +121,21 @@ Here they are:
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Also any of the above with '<' added after comment-starting symbol, like <i>/**<, /*!<, ///<, </i> or <i> //!<</i>
|
Also any of the above with '<' added after comment-starting symbol,
|
||||||
will be treated as post-comment and will be assigned to the node before the comment.
|
like <i>/**<, /*!<, ///<, </i> or <i> //!<</i> will be
|
||||||
|
treated as post-comment and will be assigned to the node before the
|
||||||
|
comment.
|
||||||
<br>
|
<br>
|
||||||
Any number of '*' or '/' in Doxygen comment is considered to be a separator and is not included in final comment, so you may safely use
|
|
||||||
|
Any number of '*' or '/' in Doxygen comment is considered to be a
|
||||||
|
separator and is not included in final comment, so you may safely use
|
||||||
comments like <i>/*********/</i> or <i>//////////</i>.
|
comments like <i>/*********/</i> or <i>//////////</i>.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Please note, as SWIG parses input file by itself with strict grammar, there is only a limited support for various cases of comment placement in the file.
|
Please note, as SWIG parses input file by itself with strict grammar,
|
||||||
|
there is only a limited support for various cases of comment placement
|
||||||
|
in the file.
|
||||||
<br>
|
<br>
|
||||||
Comments can be placed before C\C++ expressions on separate lines:
|
Comments can be placed before C\C++ expressions on separate lines:
|
||||||
</p>
|
</p>
|
||||||
|
|
@ -163,21 +191,28 @@ enum E_NUMBERS
|
||||||
</pre></div>
|
</pre></div>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Just remember, if SWIG shows syntax error parsing the file because of your comment, try to move it in some other, 'safer' place as desribed above.
|
Just remember, if SWIG shows syntax error parsing the file because of
|
||||||
|
your comment, try to move it in some other, 'safer' place as desribed
|
||||||
|
above.
|
||||||
<br>
|
<br>
|
||||||
Also, currently only the comments directly before or after the nodes are supported. Doxygen structural comments are stripped out and not assigned to anything.
|
Also, currently only the comments directly before or after the nodes
|
||||||
|
are supported. Doxygen structural comments are stripped out and not
|
||||||
|
assigned to anything.
|
||||||
</p>
|
</p>
|
||||||
<H3><a name="Doxygen_running_swig"></a>39.2.1 Enabling Doxygen Translation</H3>
|
<H3><a name="Doxygen_running_swig"></a>39.2.1 Enabling Doxygen Translation</H3>
|
||||||
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
There is a switch '-doxygen' in every module that supports converting
|
There is a switch '-doxygen' in every module that supports converting
|
||||||
documentation comments. Some comments in some target languages can be manually overriden by specific
|
documentation comments. Some comments in some target languages can be
|
||||||
swig's features, like <i>feature:docstring</i> or <i>feature:autodoc</i>, in this cases Doxygen comments
|
manually overriden by specific swig's features,
|
||||||
have lowest priority.
|
like <i>feature:docstring</i> or <i>feature:autodoc</i>, in this cases
|
||||||
|
Doxygen comments have lowest priority.
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
If Doxygen parsing is switched off, then all the comments are stripped out in parser and all the resources used by comment parser and translator are freed.
|
If Doxygen parsing is switched off, then all the comments are stripped
|
||||||
|
out in parser and all the resources used by comment parser and
|
||||||
|
translator are freed.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<H3><a name="Doxygen_additional_options"></a>39.2.2 Additional Commandline Options</H3>
|
<H3><a name="Doxygen_additional_options"></a>39.2.2 Additional Commandline Options</H3>
|
||||||
|
|
@ -191,7 +226,9 @@ ALSO TO BE ADDED (JavaDoc Autobrief?)
|
||||||
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
If translation is enabled, JavaDoc formatted comments should be automatically placed in the correct locations in the resulting module and proxy files.
|
If translation is enabled, JavaDoc formatted comments should be
|
||||||
|
automatically placed in the correct locations in the resulting module
|
||||||
|
and proxy files.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<H3><a name="Doxygen_basic_example"></a>39.3.1 Basic Example</H3>
|
<H3><a name="Doxygen_basic_example"></a>39.3.1 Basic Example</H3>
|
||||||
|
|
@ -276,24 +313,35 @@ public class Shape {
|
||||||
</pre></div>
|
</pre></div>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
The code Java-wise should be identical to what would have been generated without this feature enabled.
|
The code Java-wise should be identical to what would have been
|
||||||
When the Doxygen Translator Module encounters a comment it finds nothing useful in or cannot parse, it should not effect the functionality of the SWIG generated code.
|
generated without this feature enabled. When the Doxygen Translator
|
||||||
|
Module encounters a comment it finds nothing useful in or cannot
|
||||||
|
parse, it should not effect the functionality of the SWIG generated
|
||||||
|
code.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
JavaDoc translator will handle most of the tags conversions (see the table below). It will also automatically translate link-objects
|
JavaDoc translator will handle most of the tags conversions (see the
|
||||||
params, in \see and \link...\endlink commands. For example, 'someFunction(std::string)' will be converted to 'someFunction(String)'.
|
table below). It will also automatically translate link-objects
|
||||||
If this works not really good for you, or if you don't want such behaviour, you could turn this off by using 'doxygen:nolinktranslate'
|
params, in \see and \link...\endlink commands. For example,
|
||||||
feature. Also all '\param' and '\tparam' commands are stripped out, if specified parameter is not present in function. Use 'doxygen:nostripparams'
|
'someFunction(std::string)' will be converted to
|
||||||
to avoid.
|
'someFunction(String)'. If this works not really good for you, or if
|
||||||
|
you don't want such behaviour, you could turn this off by using
|
||||||
|
'doxygen:nolinktranslate' feature. Also all '\param' and '\tparam'
|
||||||
|
commands are stripped out, if specified parameter is not present in
|
||||||
|
function. Use 'doxygen:nostripparams' to avoid.
|
||||||
<br>
|
<br>
|
||||||
If you intend to use resulting proxy files with Doxygen docs generator, rather than JavaDoc, you may want to turn off translator completely
|
If you intend to use resulting proxy files with Doxygen docs
|
||||||
(doxygen:notranslate feature).
|
generator, rather than JavaDoc, you may want to turn off translator
|
||||||
Then SWIG will just copy the comments to the proxy file and reformat them if needed, but all the comment content will be left as is.
|
completely (doxygen:notranslate feature). Then SWIG will just copy
|
||||||
|
the comments to the proxy file and reformat them if needed, but all
|
||||||
|
the comment content will be left as is.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
JavaDoc translator features summary (see <a href="Customization.html#Customization_features">%feature directives</a>):
|
JavaDoc translator features summary
|
||||||
|
(see <a href="Customization.html#Customization_features">%feature
|
||||||
|
directives</a>):
|
||||||
<br>
|
<br>
|
||||||
|
|
||||||
</p>
|
</p>
|
||||||
|
|
@ -579,9 +627,14 @@ Here is the list of all Doxygen tags and the description of how they are transla
|
||||||
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Doxygen has a wealth of tags such as @latexonly that have no equivalent in JavaDoc.
|
Doxygen has a wealth of tags such as @latexonly that have no
|
||||||
As a result several tags that have no translation (or particular use, such as some linking and section tags) are supressed with their content just printed out (if it has any sense, typically text content).
|
equivalent in JavaDoc. As a result several tags that have no
|
||||||
If you are interested in more of the specifics of JavaDoc, please visit <A HREF="http://java.sun.com/j2se/javadoc/writingdoccomments/">How to Write Doc Comments for the Javadoc Tool.</A>
|
translation (or particular use, such as some linking and section tags)
|
||||||
|
are supressed with their content just printed out (if it has any
|
||||||
|
sense, typically text content). If you are interested in more of the
|
||||||
|
specifics of JavaDoc, please
|
||||||
|
visit <A HREF="http://java.sun.com/j2se/javadoc/writingdoccomments/">How
|
||||||
|
to Write Doc Comments for the Javadoc Tool.</A>
|
||||||
<br>
|
<br>
|
||||||
Here is the list of these tags:
|
Here is the list of these tags:
|
||||||
</p>
|
</p>
|
||||||
|
|
@ -751,8 +804,11 @@ TO BE ADDED.
|
||||||
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
If translation is enabled, PyDoc formatted comments should be automatically placed in the correct locations in the resulting module and proxy files.
|
If translation is enabled, PyDoc formatted comments should be
|
||||||
The problem is that PyDoc has no tag mechanism like Doxygen or JavaDoc, so most of Doxygen commands are translated as English plaintext pieces.
|
automatically placed in the correct locations in the resulting module
|
||||||
|
and proxy files. The problem is that PyDoc has no tag mechanism like
|
||||||
|
Doxygen or JavaDoc, so most of Doxygen commands are translated as
|
||||||
|
English plaintext pieces.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<H3><a name="Doxygen_python_basic_example"></a>39.4.1 Basic Example</H3>
|
<H3><a name="Doxygen_python_basic_example"></a>39.4.1 Basic Example</H3>
|
||||||
|
|
@ -822,18 +878,25 @@ class Shape(_object):
|
||||||
</pre></div>
|
</pre></div>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Currently Doxygen comments assigned to vars are not present in proxy file, so they have no comment translated for them.
|
Currently Doxygen comments assigned to vars are not present in proxy
|
||||||
|
file, so they have no comment translated for them.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Since all the overloaded functions in c++ are wrapped into one Python function, PyDoc translator will combine every comment of every
|
Since all the overloaded functions in c++ are wrapped into one Python
|
||||||
|
function, PyDoc translator will combine every comment of every
|
||||||
overloaded function and put it in the comment for wrapping function.
|
overloaded function and put it in the comment for wrapping function.
|
||||||
<br>
|
<br>
|
||||||
If you intend to use resulting proxy files with Doxygen docs generator, rather than PyDoc, you may want to turn off translator completely
|
If you intend to use resulting proxy files with Doxygen docs
|
||||||
(doxygen:notranslate feature).
|
generator, rather than PyDoc, you may want to turn off translator
|
||||||
Then SWIG will just copy the comments to the proxy file and reformat them if needed, but all the comment content will be left as is. As Doxygen
|
completely (doxygen:notranslate feature). Then SWIG will just copy
|
||||||
don't support special commands in Python comments (see <a href="http://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks">Doxygen docs</a>),
|
the comments to the proxy file and reformat them if needed, but all
|
||||||
you may want to use some tool like doxypy (<a href="http://code.foosel.org/doxypy">http://code.foosel.org/doxypy</a>) to do the work.
|
the comment content will be left as is. As Doxygen don't support
|
||||||
|
special commands in Python comments
|
||||||
|
(see <a href="http://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks">Doxygen
|
||||||
|
docs</a>), you may want to use some tool like doxypy
|
||||||
|
(<a href="http://code.foosel.org/doxypy">http://code.foosel.org/doxypy</a>)
|
||||||
|
to do the work.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
|
|
@ -1072,8 +1135,11 @@ Here is the list of all Doxygen tags and the description of how they are transla
|
||||||
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Doxygen has a wealth of tags such as @latexonly that have no equivalent in PyDoc.
|
Doxygen has a wealth of tags such as @latexonly that have no
|
||||||
As a result several tags that have no translation (or particular use, such as some linking and section tags) are supressed with their content just printed out (if it has any sense, typically text content).
|
equivalent in PyDoc. As a result several tags that have no
|
||||||
|
translation (or particular use, such as some linking and section tags)
|
||||||
|
are supressed with their content just printed out (if it has any
|
||||||
|
sense, typically text content).
|
||||||
<br>
|
<br>
|
||||||
Here is the list of these tags:
|
Here is the list of these tags:
|
||||||
</p>
|
</p>
|
||||||
|
|
@ -1264,10 +1330,12 @@ TO BE ADDED.
|
||||||
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
If this functionality is turned on, SWIG places all comments found into the SWIG parse tree.
|
If this functionality is turned on, SWIG places all comments found
|
||||||
Nodes contain an additional attribute called DoxygenComment when a comment is present.
|
into the SWIG parse tree. Nodes contain an additional attribute
|
||||||
Individual nodes containing Doxygen with Structural Indicators, such as @file, as their first command, are also present in the parse tree.
|
called DoxygenComment when a comment is present. Individual nodes
|
||||||
These individual "blobs" of Doxygen such as :
|
containing Doxygen with Structural Indicators, such as @file, as their
|
||||||
|
first command, are also present in the parse tree. These individual
|
||||||
|
"blobs" of Doxygen such as :
|
||||||
</p>
|
</p>
|
||||||
<div class="code"><pre>
|
<div class="code"><pre>
|
||||||
/*! This is describing function Foo
|
/*! This is describing function Foo
|
||||||
|
|
@ -1278,16 +1346,18 @@ These individual "blobs" of Doxygen such as :
|
||||||
</pre></div>
|
</pre></div>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
are passed on individually to the DoxygenTranslator Module.
|
are passed on individually to the DoxygenTranslator Module. This
|
||||||
This module builds its own private parse tree and hands it to a separate class for translation into the target documentation language.
|
module builds its own private parse tree and hands it to a separate
|
||||||
For example, <tt>JavaDocConverter</tt> is the JavaDoc module class.
|
class for translation into the target documentation language. For
|
||||||
|
example, <tt>JavaDocConverter</tt> is the JavaDoc module class.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<H3><a name="Doxygen_debugging_commands"></a>39.5.2 Debugging Doxygen parser and translator</H3>
|
<H3><a name="Doxygen_debugging_commands"></a>39.5.2 Debugging Doxygen parser and translator</H3>
|
||||||
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
There are two handy command line switches, that enable lots of detailed debug information printing.
|
There are two handy command line switches, that enable lots of
|
||||||
|
detailed debug information printing.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<div class="shell"><pre>
|
<div class="shell"><pre>
|
||||||
|
|
@ -1309,13 +1379,20 @@ This part of SWIG currently has 6 runtime tests in both Java and Python.
|
||||||
doxygen_basic_translate
|
doxygen_basic_translate
|
||||||
doxygen_basic_notranslate
|
doxygen_basic_notranslate
|
||||||
doxygen_translate_links
|
doxygen_translate_links
|
||||||
doxygen_tricky_constructs
|
doxygen_misc_constructs
|
||||||
</pre></div>
|
</pre></div>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
All this tests are included in common.mk and are build with the commands like 'make check-test-suite'
|
All this tests are included in common.mk and are build with the
|
||||||
or 'make check-python-test-suite'. To run them individually, type 'make <testname>.cpptest -s' in the
|
commands like 'make check-test-suite' or 'make
|
||||||
language-specific subdir in Examples\test-suite.
|
check-python-test-suite'. To run them individually, type
|
||||||
|
<code>make <testname>.cpptest -s</code> in the language-specific subdir in
|
||||||
|
<code>Examples/test-suite</code> directory. For example:
|
||||||
|
<pre>
|
||||||
|
Examples/test-suite/java $ make doxygen_misc_constructs.cpptest -s
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
|
||||||
<br>
|
<br>
|
||||||
Runtime tests in Java are implemented using JavaDoc doclets. To make that work, you
|
Runtime tests in Java are implemented using JavaDoc doclets. To make that work, you
|
||||||
should have tools.jar from the JDK in your classpath. Or you should have JAVA_HOME
|
should have tools.jar from the JDK in your classpath. Or you should have JAVA_HOME
|
||||||
|
|
|
||||||
|
|
@ -5,7 +5,7 @@
|
||||||
|
|
||||||
%inline %{
|
%inline %{
|
||||||
|
|
||||||
// Bug 1: Tag '@endink' is not recognized becuse it is not
|
// Tag '@endink' must be recognized even if it is not
|
||||||
// followed by whitespace.
|
// followed by whitespace.
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|
@ -26,13 +26,8 @@
|
||||||
int g_zipCode;
|
int g_zipCode;
|
||||||
|
|
||||||
|
|
||||||
// Bug 2: Paramter 'isReportSize' is missing in comment of the overload, which
|
// Paramter 'isReportSize' must appear in comment of the overload, which
|
||||||
// has it. This bug disappears if @endlink is follwed by a space.
|
// has it. Empty line before link must be preserved.
|
||||||
//
|
|
||||||
// Bug 3: Empty line before the link is missing,
|
|
||||||
// making the link text part of parameter description. This bug appears also
|
|
||||||
// when there is ordinary text in place of the link in case of overload
|
|
||||||
// with only 2 parameters.
|
|
||||||
/**
|
/**
|
||||||
* Returns address of file line.
|
* Returns address of file line.
|
||||||
*
|
*
|
||||||
|
|
@ -48,8 +43,7 @@
|
||||||
{
|
{
|
||||||
}
|
}
|
||||||
|
|
||||||
// Bug 4: The first comment is attached to the second in Python (wrong),
|
// The first comment must be ignored.
|
||||||
// but not in Java (correct).
|
|
||||||
/**
|
/**
|
||||||
* \defgroup icFacade isystem.connect Facade
|
* \defgroup icFacade isystem.connect Facade
|
||||||
*
|
*
|
||||||
|
|
@ -75,19 +69,7 @@
|
||||||
{
|
{
|
||||||
};
|
};
|
||||||
|
|
||||||
// Bug 5: Text after '\c' has no space following in Python.
|
// Text after '\c' must be kept unchanged in Python.
|
||||||
// There are also to many empty lines in multiline comments in Python.
|
|
||||||
// Whitespaces are really a problem in Python (space and newlines),
|
|
||||||
// I like a parameter type added to each parameter description!
|
|
||||||
// """
|
|
||||||
// Determines how long the isystem.connectshould wait for running
|
|
||||||
//
|
|
||||||
// instances to respond. Only one of lfWaitXXXflags from IConnect::ELaunchFlags
|
|
||||||
//
|
|
||||||
// may be specified.
|
|
||||||
//
|
|
||||||
// """
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Determines how long the \c isystem.connect should wait for running
|
* Determines how long the \c isystem.connect should wait for running
|
||||||
* instances to respond. Only one of \c lfWaitXXX flags from IConnect::ELaunchFlags
|
* instances to respond. Only one of \c lfWaitXXX flags from IConnect::ELaunchFlags
|
||||||
|
|
@ -98,8 +80,7 @@
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
// Bug 6: Text after tag \ingroup appears in Python comment (empty line in
|
// Line with tag \ingroup must not appear in translated comment:
|
||||||
// Java, which is acceptable):
|
|
||||||
/** \ingroup icFacade
|
/** \ingroup icFacade
|
||||||
*
|
*
|
||||||
* This class manages connection.
|
* This class manages connection.
|
||||||
|
|
@ -107,6 +88,19 @@
|
||||||
int getConnection()
|
int getConnection()
|
||||||
{
|
{
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Class description.
|
||||||
|
*/
|
||||||
|
class ClassWithNestedEnum {
|
||||||
|
public:
|
||||||
|
/**
|
||||||
|
* Enum description.
|
||||||
|
*/
|
||||||
|
typedef enum {ONE, ///< desc of one
|
||||||
|
TWO, ///< desc of two
|
||||||
|
THREE ///< desc of three
|
||||||
|
} ENested;
|
||||||
|
|
||||||
|
};
|
||||||
%}
|
%}
|
||||||
|
|
|
||||||
|
|
@ -98,7 +98,27 @@ public class doxygen_misc_constructs_runme {
|
||||||
" {@link Connection::getId() }<br> \n" +
|
" {@link Connection::getId() }<br> \n" +
|
||||||
" \n" +
|
" \n" +
|
||||||
"");
|
"");
|
||||||
|
|
||||||
|
wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum",
|
||||||
|
" Class description.\n" +
|
||||||
|
" \n");
|
||||||
|
|
||||||
|
wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested",
|
||||||
|
" Enum description.\n" +
|
||||||
|
" \n");
|
||||||
|
|
||||||
|
wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested.ONE",
|
||||||
|
" desc of one\n" +
|
||||||
|
" \n");
|
||||||
|
|
||||||
|
wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested.TWO",
|
||||||
|
" desc of two\n" +
|
||||||
|
" \n");
|
||||||
|
|
||||||
|
wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested.THREE",
|
||||||
|
" desc of three\n" +
|
||||||
|
" \n");
|
||||||
|
|
||||||
// and ask the parser to check comments for us
|
// and ask the parser to check comments for us
|
||||||
System.exit(parser.check(wantedComments));
|
System.exit(parser.check(wantedComments));
|
||||||
}
|
}
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue