From 9cd379b800adbd2ea5f3619ad2c7a475e943ca2a Mon Sep 17 00:00:00 2001 From: Marko Klopcic Date: Thu, 21 Feb 2013 22:50:15 +0100 Subject: [PATCH] fixed bug with autodoc, manual updated with table description and tests description --- Doc/Manual/Doxygen.html | 46 ++++++++++++++++++++++++- Examples/test-suite/doxygen_translate.i | 8 ++--- Source/Modules/python.cxx | 6 ++-- 3 files changed, 52 insertions(+), 8 deletions(-) diff --git a/Doc/Manual/Doxygen.html b/Doc/Manual/Doxygen.html index d374a9c2f..d530218a3 100644 --- a/Doc/Manual/Doxygen.html +++ b/Doc/Manual/Doxygen.html @@ -949,6 +949,40 @@ file, so they have no comment translated for them.

+ Whitespaces and tables
+ Whitespaces are preserved when translating comments, so it makes + sense to have Doxygen comments formatted in a readable way. This + includes tables, where tags <th>, <td> and </tr>are translated + to '|'. The line after line with <th> tags contains dashes. + If we take care about whitespaces, comments in Python are much more + readable. Example: + +

+/**
+ * <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>
+ * </table>
+ */
+
+

+translates to Python as: +

+

+  Animals
+  | Column 1 | Column 2 |
+  -----------------------
+  | cow      | dog      |
+  | cat      | mouse    |
+  | horse    | parrot   |
+
+

+ +

+ Overloaded functions
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 Doxygen docs), 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 +If test fails, both expected and translated comments are printed to +std out, but also written to files expected.txt +and got.txt. Since it is often difficult to find a single +character difference in several lines of text, we can use some diff +tool, for example: +

+  Examples/test-suite/java $ kdiff3 expected.txt got.txt
+
+ +
Runtime tests in Java are implemented using JavaDoc doclets. To make that work, you diff --git a/Examples/test-suite/doxygen_translate.i b/Examples/test-suite/doxygen_translate.i index 03e9471f8..a41391dc9 100644 --- a/Examples/test-suite/doxygen_translate.i +++ b/Examples/test-suite/doxygen_translate.i @@ -182,10 +182,10 @@ int function(int a, float b) * * * - - - - + * + * + * + * *
Animals
Column 1 Column 2
cow dog
cat mouse
horse parrot
Column 1 Column 2
cow dog
cat mouse
horse parrot
* * Starts a piece of text displayed in a typewriter font. diff --git a/Source/Modules/python.cxx b/Source/Modules/python.cxx index f3f1df832..5292e8462 100644 --- a/Source/Modules/python.cxx +++ b/Source/Modules/python.cxx @@ -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("");