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

fixed bug with autodoc, manual updated with table description and tests description

Browse source
This commit is contained in:
Marko Klopcic 2013-02-21 22:50:15 +01:00
commit 9cd379b800
3 changed files with 52 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

46
Doc/Manual/Doxygen.html
View file

@ -949,6 +949,40 @@ file, so they have no comment translated for them.
</p>
<p>
<b>Whitespaces and tables</b><br>
Whitespaces are preserved when translating comments, so it makes
sense to have Doxygen comments formatted in a readable way. This
includes tables, where tags &lt;th&gt;, &lt;td&gt; and &lt;/tr&gt;are translated
to '|'. The line after line with &lt;th&gt; tags contains dashes.
If we take care about whitespaces, comments in Python are much more
readable. Example:
<div class="code"><pre>
/**
* &lt;table border = '1'&gt;
* &lt;caption&gt;Animals&lt;/caption&gt;
* &lt;tr&gt;&lt;th&gt; Column 1 &lt;/th&gt;&lt;th&gt; Column 2 &lt;/th&gt;&lt;/tr&gt;
* &lt;tr&gt;&lt;td&gt; cow &lt;/td&gt;&lt;td&gt; dog &lt;/td&gt;&lt;/tr&gt;
* &lt;tr&gt;&lt;td&gt; cat &lt;/td&gt;&lt;td&gt; mouse &lt;/td&gt;&lt;/tr&gt;
* &lt;tr&gt;&lt;td&gt; horse &lt;/td&gt;&lt;td&gt; parrot &lt;/td&gt;&lt;/tr&gt;
* &lt;/table&gt;
*/
</pre></div>
<p/>
translates to Python as:
<p/>
<div class="targetlang"><pre>
Animals
| Column 1 | Column 2 |
-----------------------
| cow | dog |
| cat | mouse |
| horse | parrot |
</pre></div>
</p>
<p>
<b>Overloaded functions</b><br>
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.
@ -957,7 +991,7 @@ If you intend to use resulting proxy files with Doxygen docs
generator, rather than PyDoc, you may want to turn off translator
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. As Doxygen don't support
the comment content will be left as is. As Doxygen doesn'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
@ -1458,6 +1492,16 @@ check-python-test-suite'. To run them individually, type
Examples/test-suite/java $ make doxygen_misc_constructs.cpptest -s
</pre>
If test fails, both expected and translated comments are printed to
std out, but also written to files <i>expected.txt</i>
and <I>got.txt</I>. Since it is often difficult to find a single
character difference in several lines of text, we can use some diff
tool, for example:
<pre>
Examples/test-suite/java $ kdiff3 expected.txt got.txt
</pre>
<br>
Runtime tests in Java are implemented using JavaDoc doclets. To make that work, you

8
Examples/test-suite/doxygen_translate.i
View file

@ -182,10 +182,10 @@ int function(int a, float b)
*
* <table border = '1'>
* <caption>Animals</caption>
<tr><th> Column 1 </th><th> Column 2 </th></tr>
<tr><td> cow </td><td> dog </td></tr>
<tr><td> cat </td><td> mouse </td></tr>
<tr><td> horse </td><td> parrot </td></tr>
* <tr><th> Column 1 </th><th> Column 2 </th></tr>
* <tr><td> cow </td><td> dog </td></tr>
* <tr><td> cat </td><td> mouse </td></tr>
* <tr><td> horse </td><td> parrot </td></tr>
* </table>
*
* <TT>Starts a piece of text displayed in a typewriter font.

6
Source/Modules/python.cxx
View file

@ -1257,13 +1257,13 @@ public:
//
// otherwise, put it all on a single line
//
// All comments translated from doxygen are given as raw stringr (prefix "r"),
// All comments translated from doxygen are given as raw strings (prefix "r"),
// because '\' is used often in comments, but may break Python module from
// loading. For example, in doxy comment one may write path in quotes:
//
// This is path to file "C:\x\file.txt"
//
// Python will no load the module with such comment becaue of illegal
// Python will no load the module with such comment because of illegal
// escape '\x'. '\' may additionally appear in verbatim or htmlonly sections
// of doxygen doc, Latex expressions, ...
if (have_auto && have_ds) { // Both autodoc and docstring are present
@ -1281,7 +1281,7 @@ public:
doc = NewStringf("%s%s%s", triple_double, autodoc, triple_double);
} else {
doc = NewString("");
Printv(doc, "r", triple_double, "\n", pythoncode(autodoc, indent), indent, triple_double, NIL);
Printv(doc, triple_double, "\n", pythoncode(autodoc, indent), indent, triple_double, NIL);
}
} else if (have_doxygen) { // the lowest priority
doc = NewString("");