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

Doc/Manual/Doxygen.html

@@ -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

Examples/test-suite/doxygen_translate.i

@@ -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><th> Column 1 </th><th> Column 2 </th></tr>
-  <tr><td> cow      </td><td> dog      </td></tr>
+ * <tr><td> cow      </td><td> dog      </td></tr>
-  <tr><td> cat      </td><td> mouse    </td></tr>
+ * <tr><td> cat      </td><td> mouse    </td></tr>
-  <tr><td> horse    </td><td> parrot   </td></tr>
+ * <tr><td> horse    </td><td> parrot   </td></tr>
  * </table>
  *
  * <TT>Starts a piece of text displayed in a typewriter font.

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("");