From 51e184f134cf1a7897aac7e5c4f1a3229c74c3db Mon Sep 17 00:00:00 2001 From: Dmitry Kabak Date: Sun, 5 Aug 2012 16:22:48 +0000 Subject: [PATCH] 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 | 90 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 81 insertions(+), 9 deletions(-) diff --git a/Doc/Manual/Doxygen.html b/Doc/Manual/Doxygen.html index 77c00b40e..3178f70c2 100644 --- a/Doc/Manual/Doxygen.html +++ b/Doc/Manual/Doxygen.html @@ -101,7 +101,7 @@ Here they are: Also any of the above with '<' added after comment-starting symbol, like /**<, /*!<, ///<, or //!< will be treated as post-comment and will be assigned to the node before the comment.
-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 /*********/ or //////////.

@@ -172,11 +172,11 @@ Also, currently only the comments directly before or after the nodes are support

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 feature:docstring or feature:autodoc, in this cases doxygen comments +swig's features, like feature:docstring or feature:autodoc, in this cases Doxygen comments have lowest priority.

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

39.2.2 Additional Commandline Options

@@ -274,19 +274,61 @@ public class Shape { - -

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.

+

+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. +
+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. +

+ +

+JavaDoc translator features summary (see %feature directives): +
+ +

+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
doxygen:noranslate
+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
+
doxygen:notlinkranslateTurn off automatic link-objects translation
doxygen:nostripparams
+Turn off stripping of @param and @tparam
+Doxygen commands if such parameter is not found
+

+
+

39.3.2 JavaDoc Tags

-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
Doxygen tags:

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

+

+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. +
+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 Doxygen docs), +you may want to use some tool like doxypy (http://code.foosel.org/doxypy) to do the work. +

+ +

+PyDoc translator features summary (see %feature directives): +
+ +

+ +
+
+
+
+
+
+
doxygen:noranslate
+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
+

+
+

39.4.2 PyDoc translator

-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
Doxygen tags:

@@ -1218,8 +1290,8 @@ There are two handy command line switches, that enable lots of detailed debug in 

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

39.6 Extending to Other Languages