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 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 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 and Python). The behaviour of this functionality is wildly unpredictable if the interface file is not proper to begin with!
To make use of the comment translation system, your documentation comments must be in properly formatted Doxygen. They can be present in your main interface file or any header file that it imports. It is advised that you are certain your comments compile properly with Doxygen before you try to translate them. Doxygen itself is a deeper tool and can provide you better feedback for correcting any syntax errors that may be present. Please look at Doxygen's Documenting the code for proper specificatons for comment format. However, SWIG's Doxygen parser will still point you most of errors and warnings found in comments (like unterminated strings or missing ending tags).
/*! This is describing class Shape
\author Bob
*/
class Shape {
Currently, the whole subset of Doxygen comment styles is supported (See Documenting the code) Here they are:
/** * JavaDoc style comment, multiline */ /*! * QT-style comment, multiline */ /** Any of the above, but without intermediate *'s */ /// Single-line comment //! Another single-line comment
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
comments like /*********/ or //////////.
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 before C\C++ expressions on separate lines:
/**
* Some comment
*/
void someOtherFunction();
/**
* Some comment
*/
void someFunction();
class Shape {
/*
* Calculate the area in cm^2
*/
int getArea();
}
After C\C++ expressions at the end of the line:
int someVariable = 9; ///< This is a var holding magic number 9 void doNothing(); ///< This does nothing, nop
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.
Also, currently only the comments directly before or after the nodes are supported. Doxygen structural comments are stripped out and not assigned to anything.
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 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.
ALSO TO BE ADDED (JavaDoc Autobrief?)
If translation is enabled, JavaDoc formatted comments should be automatically placed in the correct locations in the resulting module and proxy files.
Here is an example segment from an included header file
/*! This is describing class Shape
\author Bob
*/
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
};
double x, y; /*!< Important Variables */
void move(double dx, double dy); /*!< Moves the Shape */
virtual double area(void) = 0; /*!< \return the area */
virtual double perimeter(void) = 0; /*!< \return the perimeter */
static int nshapes;
};
Simply running SWIG should result in the following code being present in Shapes.java
/**
* This is describing class Shape
* @author Bob
*
*/
public class Shape {
...
/**
* Important Variables
*/
public void setX(double value) {
ShapesJNI.Shape_x_set(swigCPtr, this, value);
}
/**
* Important Variables
*/
public double getX() {
return ShapesJNI.Shape_x_get(swigCPtr, this);
}
/**
* Moves the Shape
*/
public void move(double dx, double dy) {
ShapesJNI.Shape_move(swigCPtr, this, dx, dy);
}
/**
* @return the area
*/
public double area() {
return ShapesJNI.Shape_area(swigCPtr, this);
}
/**
* @return the perimeter
*/
public double perimeter() {
return ShapesJNI.Shape_perimeter(swigCPtr, this);
}
}
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.
Here is the list of all doxygen tags and the description of how they are translated to JavaDoc
Doxygen tags:
| \a | wrapped with <i> html tag |
| \arg | wrapped with <li> html tag |
| \author | translated to @author |
| \authors | translated to @author |
| \b | wrapped with <b> html tag |
| \c | wrapped with <code> html tag |
| \cite | wrapped with <i> html tag |
| \code | translated to {@code ...} |
| \cond | translated to 'Conditional comment: <condition>' |
| \copyright | replaced with 'Copyrigth:' |
| \deprecated | translated to @deprecated |
| \e | wrapped with <i> html tag |
| \else | replaced with '}Else:{' |
| \elseif | replaced with '}Else if: <condition>{' |
| \em | wrapped with <i> html tag |
| \endcode | see note for \code |
| \endcond | replaced with 'End of conditional comment.' |
| \endif | replaced with '}' |
| \endlink | see note for \link |
| \endverbatim | see note for \verbatim |
| \exception | translated to @exception |
| \if | replaced with 'If: <condition> {' |
| \ifnot | replaced with 'If not: <condition> {' |
| \image | translated to <img/> html tag only if target=HTML |
| \li | wrapped with <li> html tag |
| \link | translated to {@link ...} |
| \n | replaced with new line char |
| \note | replaced with 'Note:' |
| \overload | prints 'This is an overloaded ...' according to Doxygen docs |
| \p | wrapped with <code> html tag |
| \par | replaced with <p alt='title'>...</p> |
| \param | translated to @param |
| \remark | replaced with 'Remarks:' |
| \remarks | replaced with 'Remarks:' |
| \result | translated to @return |
| \return | translated to @return |
| \returns | translated to @return |
| \sa | translated to @see |
| \see | translated to @see |
| \since | translated to @since |
| \throw | translated to @throws |
| \throws | translated to @thtows |
| \todo | replaced with 'TODO:' |
| \tparam | translated to @param |
| \verbatim | translated to {@literal ...} |
| \version | translated to @version |
| \warning | translated to 'Warning:' |
| \$ | prints $ char |
| \@ | prints @ char |
| \\ | prints \ char |
| \& | prints & char |
| \~ | prints ~ char |
| \< | prints < char |
| \> | prints > char |
| \# | prints # char |
| \% | prints % char |
| \" | prints " char |
| \. | prints . char |
| \:: | prints :: |
Doxygen has a wealth of tags such as @latexonly that have no equivalent in JavaDoc.
As a result several tags that have no translation (or particular use, such as some linking and section tags) are supressed with their content just printed out (if it has any sense, typically text content).
If you are interested in more of the specifics of JavaDoc, please visit How to Write Doc Comments for the Javadoc Tool.
Here is the list of these tags:
| \addindex | \addtogroup | \anchor | \attention |
| \brief | \bug | \callgraph | \callergraph |
| \class | \copybrief | \copydetails | \copydoc |
| \date | \def | \defgroup | \details |
| \dir | \dontinclude | \dot | \dotfile |
| \enddot | \endhtmlonly | \endinternal | \endlatexonly |
| \endmanonly | \endmsc | \endrtfonly | \endxmlonly |
| \enum | \example | \extends | \f$ |
| \f[ | \f] | \f{ | \f} |
| \file | \fn | \headerfile | \hideinitializer |
| \htmlinclude | \htmlonly | \implements | \include |
| \includelineno | \ingroup | \internal | \invariant |
| \interface | \latexonly | \line | \mainpage |
| \manonly | \memberof | \msc | \mscfile |
| \name | \namespace | \nosubgrouping | \package |
| \page | \paragraph | \post | \pre |
| \private | \privatesection | \property | \protected |
| \protectedsection | \protocol | \public | \publicsection |
| \ref | \related | \relates | \relatedalso |
| \relatesalso | \retval | \rtfonly | \section |
| \short | \showinitializer | \skip | \skipline |
| \snippet | \struct | \subpage | \subsection |
| \subsubsection | \tableofcontents | \test | \typedef |
| \union | \until | \var | \verbinclude |
| \weakgroup | \xmlonly | \xrefitem | \category |
TO BE ADDED.
If translation is enabled, PyDoc formatted comments should be automatically placed in the correct locations in the resulting module and proxy files. The problem is that PyDoc has no tag mechanism like Doxygen or JavaDoc, so most of Doxygen commands are translated as English plaintext pieces.
Here is an example segment from an included header file
/*! This is describing class Shape
\author Bob
*/
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
};
double x, y; /*!< Important Variables */
void move(double dx, double dy); /*!< Moves the Shape */
virtual double area(void) = 0; /*!< \return the area */
virtual double perimeter(void) = 0; /*!< \return the perimeter */
static int nshapes;
};
Simply running SWIG should result in the following code being present in Shapes.py
...
class Shape(_object):
"""
This is describing class Shape
Authors:
Bob
"""
...
def move(self, *args):
"""
Moves the Shape
"""
return _Shapes.Shape_move(self, *args)
def area(self):
"""
Return:
the area
"""
return _Shapes.Shape_area(self)
def perimeter(self):
"""
Return:
the perimeter
"""
return _Shapes.Shape_perimeter(self)
Currently Doxygen comments assigned to vars are not present in proxy file, so they have no comment translated for them.
Here is the list of all doxygen tags and the description of how they are translated to PyDoc
Doxygen tags:
| \a | wrapped with '_' |
| \arg | prepended with ' --' |
| \author | prints 'Author:' |
| \authors | prints 'Author:' |
| \b | wrapped with '__' |
| \cite | wrapped with single quotes |
| \cond | translated to 'Conditional comment: <condition>' |
| \copyright | prints'Copyrigth:' |
| \deprecated | prints 'Deprecated:' |
| \e | wrapped with '_' |
| \else | replaced with '}Else:{' |
| \elseif | replaced with '}Else if: <condition>{' |
| \em | wrapped with '_' |
| \endcond | replaced with 'End of conditional comment.' |
| \endif | replaced with '}' |
| \exception | replaced with 'Throws:' |
| \if | replaced with 'If: <condition> {' |
| \ifnot | replaced with 'If not: <condition> {' |
| \li | prepended with ' --' |
| \n | replaced with new line char |
| \note | replaced with 'Note:' |
| \overload | prints 'This is an overloaded ...' according to Doxygen docs |
| \par | replaced with 'Title: ...' |
| \param | translated to 'Arguments:\n param(type) --description' |
| \remark | replaced with 'Remarks:' |
| \remarks | replaced with 'Remarks:' |
| \result | replaced with 'Result:' |
| \return | replaced with 'Result:' |
| \returns | replaced with 'Result:' |
| \sa | replaced with 'See also:' |
| \see | replaced with 'See also:' |
| \since | replaced with 'Since:' |
| \throw | replaced with 'Throws:' |
| \throws | replaced wih 'Throws:' |
| \todo | replaced with 'TODO:' |
| \tparam | translated to 'Arguments:\n param(type) --description' |
| \version | replaced with 'Version:' |
| \warning | translated to 'Warning:' |
| \$ | prints $ char |
| \@ | prints @ char |
| \\ | prints \ char |
| \& | prints & char |
| \~ | prints ~ char |
| \< | prints < char |
| \> | prints > char |
| \# | prints # char |
| \% | prints % char |
| \" | prints " char |
| \. | prints . char |
| \:: | prints :: |
Doxygen has a wealth of tags such as @latexonly that have no equivalent in PyDoc.
As a result several tags that have no translation (or particular use, such as some linking and section tags) are supressed with their content just printed out (if it has any sense, typically text content).
Here is the list of these tags:
| \addindex | \addtogroup | \anchor | \attention |
| \brief | \bug | \callgraph | \callergraph |
| \class | \copybrief | \copydetails | \copydoc |
| \date | \def | \defgroup | \details |
| \dir | \dontinclude | \dot | \dotfile |
| \code | \endcode | \endverbatim | \endlink |
| \enddot | \endhtmlonly | \endinternal | \endlatexonly |
| \endmanonly | \endmsc | \endrtfonly | \endxmlonly |
| \enum | \example | \extends | \f$ |
| \f[ | \f] | \f{ | \f} |
| \file | \fn | \headerfile | \hideinitializer |
| \htmlinclude | \htmlonly | \implements | \include |
| \image | \link | \verbatim | \p |
| \includelineno | \ingroup | \internal | \invariant |
| \interface | \latexonly | \line | \mainpage |
| \manonly | \memberof | \msc | \mscfile |
| \name | \namespace | \nosubgrouping | \package |
| \page | \paragraph | \post | \pre |
| \private | \privatesection | \property | \protected |
| \protectedsection | \protocol | \public | \publicsection |
| \ref | \related | \relates | \relatedalso |
| \relatesalso | \retval | \rtfonly | \section |
| \short | \showinitializer | \skip | \skipline |
| \snippet | \struct | \subpage | \subsection |
| \subsubsection | \tableofcontents | \test | \typedef |
| \union | \until | \var | \verbinclude |
| \weakgroup | \xmlonly | \xrefitem | \category |
| \c |
TO BE ADDED.
If this functionality is turned on, SWIG places all comments found into the SWIG parse tree. Nodes contain an additional attribute called DoxygenComment when a comment is present. Individual nodes containing Doxygen with Structural Indicators, such as @file, as their first command, are also present in the parse tree. These individual "blobs" of Doxygen such as :
/*! This is describing function Foo \param x some random variable \author Bob \return Foo */
are passed on individually to the DoxygenTranslator Module. This module builds its own private parse tree and hands it to a separate class for translation into the target documentation language. For example, JavaDocConverter is the JavaDoc module class.
There are two handy command line switches, that enable lots of detailed debug information printing.
-debug-doxygen-parser - Display doxygen parser module debugging information -debug-doxygen-translator - Display doxygen translator module debugging information
In general, an extension to another language requires a fairly deep understanding of the target language module, such as Modules/python.cxx for Python. Searching for "doxygen" in the java.cxx module can give you a good idea of the process for placing documentation comments into the correct areas. The basic gist is that anywhere a comment may reside on a node, there needs to be a catch for it in front of where that function, class, or other object is written out to a target language file. The other half of extension is building a target documentation language comment generator that handles one blob at a time. However, this is relatively simple and nowhere near as complex as the wrapper generating modules in SWIG. See DoxygenTranslator/JavaDocConverter.cpp for a good example. The target language module hands the DoxygenTranslator the blob to translate, and receives back a translated text.
What is given to the Doxygen Translator
/*! This is describing function Foo \param x some random variable \author Bob \return Foo */
What is received back by java.cxx
/** This is describing function Foo * * @param x some random variable * @author Bob * @return Foo */
Development of the comment translator itself is simplified by the fact that the DoxygenTranslator module can easily include a main function and thus be developed, compiled, and tested independently of SWIG.