Added special doxygen features description to docs

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2012-doxygen@13523 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Doc/Manual/Doxygen.html

@@ -101,7 +101,7 @@ Here they are:
 Also any of the above with '<' added after comment-starting symbol, like <i>/**&lt;, /*!&lt;, ///&lt;, </i> or <i> //!&lt;</i>
 will be treated as post-comment and will be assigned to the node before the comment.
 <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>.
 </p>
 
@@ -172,11 +172,11 @@ Also, currently only the comments directly before or after the nodes are support
 <p>
 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
-swig's features, like <i>feature:docstring</i> or <i>feature:autodoc</i>, in this cases doxygen comments
+swig's features, like <i>feature:docstring</i> or <i>feature:autodoc</i>, in this cases Doxygen comments
 have lowest priority.
 </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>
 
 <H3><a name="Doxygen_additional_options"></a>39.2.2 Additional Commandline Options</H3>
@@ -274,19 +274,61 @@ public class Shape {
 
 </pre></div>
 
-
-
 <p>
 The code Java-wise should be identical to what would have been 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>
+JavaDoc translator will handle most of the tags conversions (see the table below). It will also automatically translate link-objects
+params, in \see and \link...\endlink commands. For example, 'someFunction(std::string)' will be converted to '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>
+If you intend to use resulting proxy files with Doxygen docs generator, rather than JavaDoc, 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.
+</p>
+
+<p>
+JavaDoc translator features summary (see <a href="Customization.html#Customization_features">%feature directives</a>):
+<br>
+
+</p>
+
+<div class="shell"><pre>
+<table>
+<tr>
+<td>doxygen:noranslate</td>
+<td>
+Turn off the whole Doxygen translator.
+The Doxygen comment will be attached to the right node,
+but all the commands and text will be left as-is
+</td>
+</tr>
+
+<tr>
+<td>doxygen:notlinkranslate</td>
+<td>Turn off automatic link-objects translation</td>
+</tr>
+
+<tr>
+<td>doxygen:nostripparams</td>
+<td>
+Turn off stripping of @param and @tparam
+Doxygen commands if such parameter is not found
+</td>
+</tr>
+</table>
+</pre></div>
+
 
 <H3><a name="Doxygen_javadoc_tags"></a>39.3.2 JavaDoc Tags</H3>
 
 
 <p>
-Here is the list of all doxygen tags and the description of how they are translated to JavaDoc
+Here is the list of all Doxygen tags and the description of how they are translated to JavaDoc
 <br>
 <b>Doxygen tags:</b>
 </p>
@@ -782,11 +824,41 @@ class Shape(_object):
 Currently Doxygen comments assigned to vars are not present in proxy file, so they have no comment translated for them.
 </p>
 
+<p>
+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.
+<br>
+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 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>
+PyDoc translator features summary (see <a href="Customization.html#Customization_features">%feature directives</a>):
+<br>
+
+</p>
+
+<div class="shell"><pre>
+<table>
+<tr>
+<td>doxygen:noranslate</td>
+<td>
+Turn off the whole Doxygen translator.
+The Doxygen comment will be attached to the right node,
+but all the commands and text will be left as-is
+</td>
+</tr>
+</table>
+</pre></div>
+
 <H3><a name="Doxygen_pydoc_tags"></a>39.4.2 PyDoc translator</H3>
 
 
 <p>
-Here is the list of all doxygen tags and the description of how they are translated to PyDoc
+Here is the list of all Doxygen tags and the description of how they are translated to PyDoc
 <br>
 <b>Doxygen tags:</b>
 </p>
@@ -1218,8 +1290,8 @@ There are two handy command line switches, that enable lots of detailed debug in
 </p>
 
 <div class="shell"><pre>
-  -debug-doxygen-parser     - Display doxygen parser module debugging information
-  -debug-doxygen-translator - Display doxygen translator module debugging information
+  -debug-doxygen-parser     - Display Doxygen parser module debugging information
+  -debug-doxygen-translator - Display Doxygen translator module debugging information
 </pre></div>
 
 <H2><a name="Doxygen_language_extension"></a>39.6 Extending to Other Languages</H2>