This chapter describes SWIG's support for translating Doxygen comments found in interface and header files into a target language's normal documentation language. -Currently only JavaDoc is supported. +Currently only JavaDoc and PythonDoc is supported.
The Doxygen Translation Module of SWIG is an ongoing effort from a Google Summer of Code proposal from Summer 2008. It adds an extra layer of functionality to SWIG, allowing automated translation of Doxygen formatted comments from input files into a documentation language more suited for the target language. -Currently this module only translates into JavaDoc for the SWIG Java Module, but other extensions are to be added in time. +Currently this module only translates into JavaDoc and PythonDoc for the SWIG Java and Python Modules, but other extensions are to be added in time.
-Questions about running SWIG are best answered in the SWIG Basics chapter as well as the target language modules. (For now, only Java). +Questions about running SWIG are best answered in the SWIG Basics chapter as well as the target language modules. (For now, only Java and Python). The behaviour of this functionality is wildly unpredictable if the interface file is not proper to begin with!
@@ -72,7 +72,43 @@ class Shape {-Because this functionality is currently only extended to Java, you must be able to run SWIG's Java Module in order to make use of this tool. +Please note, as SWIG parses input file by itself with strict grammar, there is only a limited support for various cases of comment placement in the file. +Comments can be placed between two C expressions on separate lines: +
+ ++void someOtherFunction(); +/** + * Some comment + */ +void someFunction(); +
+and in some special cases, like function parameter comments: +
+ ++void someFunction( + int a ///< Some parameter + ); +
+or enum element comments: +
+ +
+enum E_NUMBERS
+{
+ EN_ZERO, ///< The first enum item, gets zero as it's value
+ EN_ONE, ///< The second, EN_ONE=1
+ EN_THREE
+};
++Just remember, if SWIG shows syntax error parsing the file because of your comment, try to move it in some other, 'safer' place as desribed above.