jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
swig/Doc/Manual/Doxygen.html

1516 lines
31 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and Doxygen Translation</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Doxygen"></a>39 SWIG and Doxygen Translation</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Doxygen_translation_overview">Doxygen Translation Overview</a>
<li><a href="#Doxygen_file_preparation">Preparations</a>
<ul>
<li><a href="#Doxygen_running_swig">Enabling Doxygen Translation</a>
<li><a href="#Doxygen_additional_options">Additional Commandline Options</a>
</ul>
<li><a href="#Doxygen_to_javadoc">Doxygen To JavaDoc</a>
<ul>
<li><a href="#Doxygen_basic_example">Basic Example</a>
<li><a href="#Doxygen_javadoc_tags">JavaDoc Tags</a>
<li><a href="#Doxygen_unsupported_tags">Unsupported tags</a>
<li><a href="#Doxygen_further_details">Further Details</a>
</ul>
<li><a href="#Doxygen_to_pydoc">Doxygen To PythonDoc</a>
<ul>
<li><a href="#Doxygen_python_basic_example">Basic Example</a>
<li><a href="#Doxygen_pydoc_tags">PyDoc translator</a>
<li><a href="#Doxygen_python_unsupported_tags">Unsupported tags</a>
<li><a href="#Doxygen_python_further_details">Further Details</a>
</ul>
<li><a href="#Doxygen_developer_details">Developer Information</a>
<ul>
<li><a href="#Doxygen_module_design">Module Design</a>
<li><a href="#Doxygen_debugging_commands">Debugging Doxygen parser and translator</a>
<li><a href="#Doxygen_debugging_commands">Tests</a>
</ul>
<li><a href="#Doxygen_language_extension">Extending to Other Languages</a>
</ul>
</div>
<!-- INDEX -->
<p>
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.
</p>
<H2><a name="Doxygen_translation_overview"></a>39.1 Doxygen Translation Overview</H2>
<p>
The Doxygen Translation Module of SWIG is an ongoing effort from
a <A HREF ="http://code.google.com/soc/2008/">Google Summer of
Code</A> proposal from Summer 2008. It adds an extra layer of
functionality to SWIG, allowing automated translation of <A HREF=
"http://www.stack.nl/~dimitri/doxygen/">Doxygen</A> 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.
</p>
<p>
Questions about running SWIG are best answered in
the <a href="SWIG.html#SWIG">SWIG Basics</a> chapter as well as the
target language modules. (For now, only <A href = "Java.html">Java</A>
and <A href = "Python.html">Python</A>). The behaviour of this
functionality is wildly unpredictable if the interface file is not
proper to begin with!
</p>
<H2><a name="Doxygen_file_preparation"></a>39.2 Preparations</H2>
<p>
To make use of the comment translation system, your documentation
comments must be in properly formatted <A HREF=
"http://www.stack.nl/~dimitri/doxygen/">Doxygen.</A> 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 <A HREF =
"http://www.stack.nl/~dimitri/doxygen/docblocks.html"> Documenting the
code</A> 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).
</p>
<div class="code"><pre>
/*! This is describing class Shape
\author Bob
*/
class Shape {
</pre></div>
<p>
Currently, the whole subset of Doxygen comment styles is supported
(See <A HREF = "http://www.stack.nl/~dimitri/doxygen/docblocks.html">
Documenting the code</A>). Here they are:
<div class="code"><pre>
/**
* JavaDoc style comment, multiline
*/
/*!
* QT-style comment, multiline
*/
/**
Any of the above, but without intermediate *'s
*/
/// Single-line comment
//! Another single-line comment
</pre></div>
</p>
<p>
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
comments like <i>/*********/</i> or <i>//////////</i>.
</p>
<p>
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.
<br>
Comments can be placed before C\C++ expressions on separate lines:
</p>
<div class="code"><pre>
/**
* Some comment
*/
void someOtherFunction();
/**
* Some comment
*/
void someFunction();
class Shape {
/*
* Calculate the area in cm^2
*/
int getArea();
}
</pre></div>
<p>
After C\C++ expressions at the end of the line:
</p>
<div class="code"><pre>
int someVariable = 9; ///< This is a var holding magic number 9
void doNothing(); ///< This does nothing, nop
</pre></div>
<p>
and in some special cases, like function parameter comments:
</p>
<div class="code"><pre>
void someFunction(
int a ///< Some parameter
);
</pre></div>
<p>
or enum element comments:
</p>
<div class="code"><pre>
enum E_NUMBERS
{
EN_ZERO, ///< The first enum item, gets zero as it's value
EN_ONE, ///< The second, EN_ONE=1
EN_THREE
};
</pre></div>
<p>
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.
<br>
Also, currently only the comments directly before or after the nodes
are supported. Doxygen structural comments are stripped out and not
assigned to anything.
</p>
<H3><a name="Doxygen_running_swig"></a>39.2.1 Enabling Doxygen Translation</H3>
<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 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.
</p>
<H3><a name="Doxygen_additional_options"></a>39.2.2 Additional Commandline Options</H3>
<p>
ALSO TO BE ADDED (JavaDoc Autobrief?)
</p>
<H2><a name="Doxygen_to_javadoc"></a>39.3 Doxygen To JavaDoc</H2>
<p>
If translation is enabled, JavaDoc formatted comments should be
automatically placed in the correct locations in the resulting module
and proxy files.
</p>
<H3><a name="Doxygen_basic_example"></a>39.3.1 Basic Example</H3>
<p>
Here is an example segment from an included header file
</p>
<div class="code"><pre>
/*! This is describing class Shape
\author Bob
*/
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
};
double x, y; /*!&lt; Important Variables */
void move(double dx, double dy); /*!&lt; Moves the Shape */
virtual double area(void) = 0; /*!&lt; \return the area */
virtual double perimeter(void) = 0; /*!&lt; \return the perimeter */
static int nshapes;
};
</pre></div>
<p>
Simply running SWIG should result in the following code being present in Shapes.java
</p>
<div class="targetlang"><pre>
/**
* 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);
}
}
</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
<br>
<b>Doxygen tags:</b>
</p>
<div class="diagram"><pre>
<table border="0">
<tr>
<td>\a</td>
<td>wrapped with &lt;i&gt; html tag</td>
</tr>
<tr>
<td>\arg</td>
<td>wrapped with &lt;li&gt; html tag</td>
</tr>
<tr>
<td>\author</td>
<td>translated to @author</td>
</tr>
<tr>
<td>\authors</td>
<td>translated to @author</td>
</tr>
<tr>
<td>\b</td>
<td>wrapped with &lt;b&gt; html tag</td>
</tr>
<tr>
<td>\c</td>
<td>wrapped with &lt;code&gt; html tag</td>
</tr>
<tr>
<tr>
<td>\cite</td>
<td>wrapped with &lt;i&gt; html tag</td>
</tr>
<tr>
<td>\code</td>
<td>translated to {@code ...}</td>
</tr>
<tr>
<td>\cond</td>
<td>translated to 'Conditional comment: &lt;condition&gt;'</td>
</tr>
<tr>
<td>\copyright</td>
<td>replaced with 'Copyrigth:'</td>
</tr>
<tr>
<td>\deprecated</td>
<td>translated to @deprecated</td>
</tr>
<tr>
<td>\e</td>
<td>wrapped with &lt;i&gt; html tag</td>
</tr>
<tr>
<td>\else</td>
<td>replaced with '}Else:{'</td>
</tr>
<tr>
<td>\elseif</td>
<td>replaced with '}Else if: &lt;condition&gt;{'</td>
</tr>
<tr>
<td>\em</td>
<td>wrapped with &lt;i&gt; html tag</td>
</tr>
<tr>
<td>\endcode</td>
<td>see note for \code</td>
</tr>
<tr>
<td>\endcond</td>
<td>replaced with 'End of conditional comment.'</td>
</tr>
<tr>
<td>\endif</td>
<td>replaced with '}'</td>
</tr>
<tr>
<td>\endlink</td>
<td>see note for \link</td>
</tr>
<tr>
<td>\endverbatim</td>
<td>see note for \verbatim</td>
</tr>
<tr>
<td>\exception</td>
<td>translated to @exception</td>
</tr>
<tr>
<td>\f$, \f[, \f], \f{, \f}</td>
<td>LateX formulas are left unchanged</td>
</tr>
<tr>
<td>\if</td>
<td>replaced with 'If: &lt;condition&gt; {'</td>
</tr>
<tr>
<td>\ifnot</td>
<td>replaced with 'If not: &lt;condition&gt; {'</td>
</tr>
<tr>
<td>\image</td>
<td>translated to &lt;img/&gt; html tag only if target=HTML</td>
</tr>
<tr>
<td>\li</td>
<td>wrapped with &lt;li&gt; html tag</td>
</tr>
<tr>
<td>\link</td>
<td>translated to {@link ...}</td>
</tr>
<tr>
<td>\n</td>
<td>replaced with new line char</td>
</tr>
<tr>
<td>\note</td>
<td>replaced with 'Note:'</td>
</tr>
<tr>
<td>\overload</td>
<td>prints 'This is an overloaded ...' according to Doxygen docs</td>
</tr>
<tr>
<td>\p</td>
<td>wrapped with &lt;code&gt; html tag</td>
</tr>
<tr>
<td>\par</td>
<td>replaced with &lt;p alt='title'&gt;...&lt/p&gt;</td>
</tr>
<tr>
<td>\param</td>
<td>translated to @param</td>
</tr>
<tr>
<td>\remark</td>
<td>replaced with 'Remarks:'</td>
</tr>
<tr>
<td>\remarks</td>
<td>replaced with 'Remarks:'</td>
</tr>
<tr>
<td>\result</td>
<td>translated to @return</td>
</tr>
<tr>
<td>\return</td>
<td>translated to @return</td>
</tr>
<tr>
<td>\returns</td>
<td>translated to @return</td>
</tr>
<tr>
<td>\sa</td>
<td>translated to @see</td>
</tr>
<tr>
<td>\see</td>
<td>translated to @see</td>
</tr>
<tr>
<td>\since</td>
<td>translated to @since</td>
</tr>
<tr>
<td>\throw</td>
<td>translated to @throws</td>
</tr>
<tr>
<td>\throws</td>
<td>translated to @thtows</td>
</tr>
<tr>
<td>\todo</td>
<td>replaced with 'TODO:'</td>
</tr>
<tr>
<td>\tparam</td>
<td>translated to @param</td>
</tr>
<tr>
<td>\verbatim</td>
<td>translated to {@literal ...}</td>
</tr>
<tr>
<td>\version</td>
<td>translated to @version</td>
</tr>
<tr>
<td>\warning</td>
<td>translated to 'Warning:'</td>
</tr>
<tr>
<td>\$</td>
<td>prints $ char</td>
</tr>
<tr>
<td>\@</td>
<td>prints @ char</td>
</tr>
<tr>
<td>\\</td>
<td>prints \ char</td>
</tr>
<tr>
<td>\&amp;</td>
<td>prints &amp; char</td>
</tr>
<tr>
<td>\~</td>
<td>prints ~ char</td>
</tr>
<tr>
<td>\&lt;</td>
<td>prints &lt; char</td>
</tr>
<tr>
<td>\&gt;</td>
<td>prints &gt; char</td>
</tr>
<tr>
<td>\#</td>
<td>prints # char</td>
</tr>
<tr>
<td>\%</td>
<td>prints % char</td>
</tr>
<tr>
<td>\&quot;</td>
<td>prints &quot; char</td>
</tr>
<tr>
<td>\.</td>
<td>prints . char</td>
</tr>
<tr>
<td>\::</td>
<td>prints ::</td>
</tr>
</table>
</pre></div>
<H3><a name="Doxygen_unsupported_tags"></a>39.3.3 Unsupported tags</H3>
<p>
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 <A HREF="http://java.sun.com/j2se/javadoc/writingdoccomments/">How
to Write Doc Comments for the Javadoc Tool.</A>
<br>
Here is the list of these tags:
</p>
<div class="diagram"><pre>
<table border="0">
<tr>
<td>\addindex</td>
<td>\addtogroup</td>
<td>\anchor</td>
<td>\attention</td>
</tr>
<tr>
<td>\brief</td>
<td>\bug</td>
<td>\callgraph</td>
<td>\callergraph</td>
</tr>
<tr>
<td>\class</td>
<td>\copybrief</td>
<td>\copydetails</td>
<td>\copydoc</td>
</tr>
<tr>
<td>\date</td>
<td>\def</td>
<td>\defgroup</td>
<td>\details</td>
</tr>
<tr>
<td>\dir</td>
<td>\dontinclude</td>
<td>\dot</td>
<td>\dotfile</td>
</tr>
<tr>
<td>\enddot</td>
<td>\endhtmlonly</td>
<td>\endinternal</td>
<td>\endlatexonly</td>
</tr>
<tr>
<td>\endmanonly</td>
<td>\endmsc</td>
<td>\endrtfonly</td>
<td>\endxmlonly</td>
</tr>
<tr>
<td>\enum</td>
<td>\example</td>
<td>\extends</td>
</tr>
<tr>
<td>\file</td>
<td>\fn</td>
<td>\headerfile</td>
<td>\hideinitializer</td>
</tr>
<tr>
<td>\htmlinclude</td>
<td>\htmlonly</td>
<td>\implements</td>
<td>\include</td>
</tr>
<tr>
<td>\includelineno</td>
<td>\ingroup</td>
<td>\internal</td>
<td>\invariant</td>
</tr>
<tr>
<td>\interface</td>
<td>\latexonly</td>
<td>\line</td>
<td>\mainpage</td>
</tr>
<tr>
<td>\manonly</td>
<td>\memberof</td>
<td>\msc</td>
<td>\mscfile</td>
</tr>
<tr>
<td>\name</td>
<td>\namespace</td>
<td>\nosubgrouping</td>
<td>\package</td>
</tr>
<tr>
<td>\page</td>
<td>\paragraph</td>
<td>\post</td>
<td>\pre</td>
</tr>
<tr>
<td>\private</td>
<td>\privatesection</td>
<td>\property</td>
<td>\protected</td>
</tr>
<tr>
<td>\protectedsection</td>
<td>\protocol</td>
<td>\public</td>
<td>\publicsection</td>
</tr>
<tr>
<td>\ref</td>
<td>\related</td>
<td>\relates</td>
<td>\relatedalso</td>
</tr>
<tr>
<td>\relatesalso</td>
<td>\retval</td>
<td>\rtfonly</td>
<td>\section</td>
</tr>
<tr>
<td>\short</td>
<td>\showinitializer</td>
<td>\skip</td>
<td>\skipline</td>
</tr>
<tr>
<td>\snippet</td>
<td>\struct</td>
<td>\subpage</td>
<td>\subsection</td>
</tr>
<tr>
<td>\subsubsection</td>
<td>\tableofcontents</td>
<td>\test</td>
<td>\typedef</td>
</tr>
<tr>
<td>\union</td>
<td>\until</td>
<td>\var</td>
<td>\verbinclude</td>
</tr>
<tr>
<td>\weakgroup</td>
<td>\xmlonly</td>
<td>\xrefitem</td>
<td>\category</td>
</tr>
</table>
</pre></div>
<p/>
If one of the following Doxygen tags appears as the first tag in a
comment, the whole comment block is ignored:
<!-- see parser.y, function isStructuralDoxygen() -->
</p>
<div class="diagram"><pre>
<table border="0">
<tr>
<td>\addtogroup</td>
<td>\callgraph</td>
<td>\callergraph</td>
<td>\category</td>
</tr>
<tr>
<td>\class</td>
<td>\def</td>
<td>\defgroup</td>
<td>\dir</td>
</tr>
<tr>
<td>\enum</td>
<td>\example</td>
<td>\file</td>
<td>\fn</td>
</tr>
<tr>
<td>\headerfile</td>
<td>\hideinitializer</td>
<td>\interface</td>
<td>\internal</td>
</tr>
<tr>
<td>\mainpage</td>
<td>\name</td>
<td>\namespace</td>
<td>\nosubgrouping</td>
</tr>
<tr>
<td>\overload</td>
<td>\package</td>
<td>\page</td>
<td>\property</td>
</tr>
<tr>
<td>\protocol</td>
<td>\relates</td>
<td>\relatesalso</td>
<td>\showinitializer</td>
</tr>
<tr>
<td>\struct</td>
<td>\name</td>
<td>\namespace</td>
<td>\nosubgrouping</td>
</tr>
<tr>
<td>\typedef</td>
<td>\union</td>
<td>\var</td>
<td>\weakgroup</td>
</tr>
</table>
</pre></div>
<H3><a name="Doxygen_further_details"></a>39.3.4 Further Details</H3>
<p>
TO BE ADDED.
</p>
<H2><a name="Doxygen_to_pydoc"></a>39.4 Doxygen To PythonDoc</H2>
<p>
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.
</p>
<H3><a name="Doxygen_python_basic_example"></a>39.4.1 Basic Example</H3>
<p>
Here is an example segment from an included header file
</p>
<div class="code"><pre>
/*! This is describing class Shape
\author Bob
*/
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
};
double x, y; /*!&lt; Important Variables */
void move(double dx, double dy); /*!&lt; Moves the Shape */
virtual double area(void) = 0; /*!&lt; \return the area */
virtual double perimeter(void) = 0; /*!&lt; \return the perimeter */
static int nshapes;
};
</pre></div>
<p>
Simply running SWIG should result in the following code being present in Shapes.py
</p>
<div class="targetlang"><pre>
...
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)
</pre></div>
<p>
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
<br>
<b>Doxygen tags:</b>
</p>
<div class="diagram"><pre>
<table border="0">
<tr>
<td>\a</td>
<td>wrapped with '_'</td>
</tr>
<tr>
<td>\arg</td>
<td>prepended with ' --'</td>
</tr>
<tr>
<td>\author</td>
<td>prints 'Author:'</td>
</tr>
<tr>
<td>\authors</td>
<td>prints 'Author:'</td>
</tr>
<tr>
<td>\b</td>
<td>wrapped with '__'</td>
</tr>
<tr>
<td>\cite</td>
<td>wrapped with single quotes</td>
</tr>
<tr>
<td>\cond</td>
<td>translated to 'Conditional comment: &lt;condition&gt;'</td>
</tr>
<tr>
<td>\copyright</td>
<td>prints'Copyrigth:'</td>
</tr>
<tr>
<td>\deprecated</td>
<td>prints 'Deprecated:'</td>
</tr>
<tr>
<td>\e</td>
<td>wrapped with '_'</td>
</tr>
<tr>
<td>\else</td>
<td>replaced with '}Else:{'</td>
</tr>
<tr>
<td>\elseif</td>
<td>replaced with '}Else if: &lt;condition&gt;{'</td>
</tr>
<tr>
<td>\em</td>
<td>wrapped with '_'</td>
</tr>
<tr>
<td>\endcond</td>
<td>replaced with 'End of conditional comment.'</td>
</tr>
<tr>
<td>\endif</td>
<td>replaced with '}'</td>
</tr>
<tr>
<td>\exception</td>
<td>replaced with 'Throws:'</td>
</tr>
<tr>
<td>\if</td>
<td>replaced with 'If: &lt;condition&gt; {'</td>
</tr>
<tr>
<td>\ifnot</td>
<td>replaced with 'If not: &lt;condition&gt; {'</td>
</tr>
<tr>
<td>\li</td>
<td>prepended with ' --'</td>
</tr>
<tr>
<td>\n</td>
<td>replaced with new line char</td>
</tr>
<tr>
<td>\note</td>
<td>replaced with 'Note:'</td>
</tr>
<tr>
<td>\overload</td>
<td>prints 'This is an overloaded ...' according to Doxygen docs</td>
</tr>
<tr>
<td>\par</td>
<td>replaced with 'Title: ...'</td>
</tr>
<tr>
<td>\param</td>
<td>translated to 'Arguments:\n param(type) --description'</td>
</tr>
<tr>
<td>\remark</td>
<td>replaced with 'Remarks:'</td>
</tr>
<tr>
<td>\remarks</td>
<td>replaced with 'Remarks:'</td>
</tr>
<tr>
<td>\result</td>
<td>replaced with 'Result:'</td>
</tr>
<tr>
<td>\return</td>
<td>replaced with 'Result:'</td>
</tr>
<tr>
<td>\returns</td>
<td>replaced with 'Result:'</td>
</tr>
<tr>
<td>\sa</td>
<td>replaced with 'See also:'</td>
</tr>
<tr>
<td>\see</td>
<td>replaced with 'See also:'</td>
</tr>
<tr>
<td>\since</td>
<td>replaced with 'Since:'</td>
</tr>
<tr>
<td>\throw</td>
<td>replaced with 'Throws:'</td>
</tr>
<tr>
<td>\throws</td>
<td>replaced wih 'Throws:'</td>
</tr>
<tr>
<td>\todo</td>
<td>replaced with 'TODO:'</td>
</tr>
<tr>
<td>\tparam</td>
<td>translated to 'Arguments:\n param(type) --description'</td>
</tr>
<tr>
<td>\version</td>
<td>replaced with 'Version:'</td>
</tr>
<tr>
<td>\warning</td>
<td>translated to 'Warning:'</td>
</tr>
<tr>
<td>\$</td>
<td>prints $ char</td>
</tr>
<tr>
<td>\@</td>
<td>prints @ char</td>
</tr>
<tr>
<td>\\</td>
<td>prints \ char</td>
</tr>
<tr>
<td>\&amp;</td>
<td>prints &amp; char</td>
</tr>
<tr>
<td>\~</td>
<td>prints ~ char</td>
</tr>
<tr>
<td>\&lt;</td>
<td>prints &lt; char</td>
</tr>
<tr>
<td>\&gt;</td>
<td>prints &gt; char</td>
</tr>
<tr>
<td>\#</td>
<td>prints # char</td>
</tr>
<tr>
<td>\%</td>
<td>prints % char</td>
</tr>
<tr>
<td>\&quot;</td>
<td>prints &quot; char</td>
</tr>
<tr>
<td>\.</td>
<td>prints . char</td>
</tr>
<tr>
<td>\::</td>
<td>prints ::</td>
</tr>
</table>
</pre></div>
<H3><a name="Doxygen_python_unsupported_tags"></a>39.4.3 Unsupported tags</H3>
<p>
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).
<br>
Here is the list of these tags:
</p>
<div class="diagram"><pre>
<table border="0">
<tr>
<td>\addindex</td>
<td>\addtogroup</td>
<td>\anchor</td>
<td>\attention</td>
</tr>
<tr>
<td>\brief</td>
<td>\bug</td>
<td>\callgraph</td>
<td>\callergraph</td>
</tr>
<tr>
<td>\class</td>
<td>\copybrief</td>
<td>\copydetails</td>
<td>\copydoc</td>
</tr>
<tr>
<td>\date</td>
<td>\def</td>
<td>\defgroup</td>
<td>\details</td>
</tr>
<tr>
<td>\dir</td>
<td>\dontinclude</td>
<td>\dot</td>
<td>\dotfile</td>
</tr>
<tr>
<td>\code</td>
<td>\endcode</td>
<td>\endverbatim</td>
<td>\endlink</td>
</tr>
<tr>
<td>\enddot</td>
<td>\endhtmlonly</td>
<td>\endinternal</td>
<td>\endlatexonly</td>
</tr>
<tr>
<td>\endmanonly</td>
<td>\endmsc</td>
<td>\endrtfonly</td>
<td>\endxmlonly</td>
</tr>
<tr>
<td>\enum</td>
<td>\example</td>
<td>\extends</td>
<td>\f$</td>
</tr>
<tr>
<td>\f[</td>
<td>\f]</td>
<td>\f{</td>
<td>\f}</td>
</tr>
<tr>
<td>\file</td>
<td>\fn</td>
<td>\headerfile</td>
<td>\hideinitializer</td>
</tr>
<tr>
<td>\htmlinclude</td>
<td>\htmlonly</td>
<td>\implements</td>
<td>\include</td>
</tr>
<tr>
<td>\image</td>
<td>\link</td>
<td>\verbatim</td>
<td>\p</td>
</tr>
<tr>
<td>\includelineno</td>
<td>\ingroup</td>
<td>\internal</td>
<td>\invariant</td>
</tr>
<tr>
<td>\interface</td>
<td>\latexonly</td>
<td>\line</td>
<td>\mainpage</td>
</tr>
<tr>
<td>\manonly</td>
<td>\memberof</td>
<td>\msc</td>
<td>\mscfile</td>
</tr>
<tr>
<td>\name</td>
<td>\namespace</td>
<td>\nosubgrouping</td>
<td>\package</td>
</tr>
<tr>
<td>\page</td>
<td>\paragraph</td>
<td>\post</td>
<td>\pre</td>
</tr>
<tr>
<td>\private</td>
<td>\privatesection</td>
<td>\property</td>
<td>\protected</td>
</tr>
<tr>
<td>\protectedsection</td>
<td>\protocol</td>
<td>\public</td>
<td>\publicsection</td>
</tr>
<tr>
<td>\ref</td>
<td>\related</td>
<td>\relates</td>
<td>\relatedalso</td>
</tr>
<tr>
<td>\relatesalso</td>
<td>\retval</td>
<td>\rtfonly</td>
<td>\section</td>
</tr>
<tr>
<td>\short</td>
<td>\showinitializer</td>
<td>\skip</td>
<td>\skipline</td>
</tr>
<tr>
<td>\snippet</td>
<td>\struct</td>
<td>\subpage</td>
<td>\subsection</td>
</tr>
<tr>
<td>\subsubsection</td>
<td>\tableofcontents</td>
<td>\test</td>
<td>\typedef</td>
</tr>
<tr>
<td>\union</td>
<td>\until</td>
<td>\var</td>
<td>\verbinclude</td>
</tr>
<tr>
<td>\weakgroup</td>
<td>\xmlonly</td>
<td>\xrefitem</td>
<td>\category</td>
</tr>
<tr>
<td>\c</td>
</tr>
</table>
</pre></div>
<H3><a name="Doxygen_python_further_details"></a>39.4.4 Further Details</H3>
<p>
TO BE ADDED.
</p>
<H2><a name="Doxygen_developer_details"></a>39.5 Developer Information</H2>
<p>
</p>
<H3><a name="Doxygen_module_design"></a>39.5.1 Module Design</H3>
<p>
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 :
</p>
<div class="code"><pre>
/*! This is describing function Foo
\param x some random variable
\author Bob
\return Foo
*/
</pre></div>
<p>
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, <tt>JavaDocConverter</tt> is the JavaDoc module class.
</p>
<H3><a name="Doxygen_debugging_commands"></a>39.5.2 Debugging Doxygen parser and translator</H3>
<p>
There are two handy command line switches, that enable lots of
detailed debug information printing.
</p>
<div class="shell"><pre>
-debug-doxygen-parser - Display Doxygen parser module debugging information
-debug-doxygen-translator - Display Doxygen translator module debugging information
</pre></div>
<H3><a name="Doxygen_tests"></a>39.5.3 Tests</H3>
<p>
This part of SWIG currently has 6 runtime tests in both Java and Python.
</p>
<div class="shell"><pre>
doxygen_parsing
doxygen_translate
doxygen_translate_all_tags
doxygen_basic_translate
doxygen_basic_notranslate
doxygen_translate_links
doxygen_misc_constructs
</pre></div>
<p>
All this tests are included in common.mk and are build with the
commands like 'make check-test-suite' or 'make
check-python-test-suite'. To run them individually, type
<code>make &lt;testname&gt;.cpptest -s</code> in the language-specific subdir in
<code>Examples/test-suite</code> directory. For example:
<pre>
Examples/test-suite/java $ make doxygen_misc_constructs.cpptest -s
</pre>
<br>
Runtime tests in Java are implemented using JavaDoc doclets. To make that work, you
should have tools.jar from the JDK in your classpath. Or you should have JAVA_HOME
environmental var defined and pointing to the JDK location.
<br>
The Java's comment parsing code (the testing part) is located in commentParser.java.
You may see it to understand how the checking process works. There is also a possibility
to run that file as stand-alone program, with 'java commentParser <some java package>',
and it will print the list of comments found in the specified dir (in the format it's used
in runtime tests). So, when you want to create the new test of Doxygen comment translator,
just copy any existing one, and replace the actual comment content (section of entries in
form 'wantedComments.put(...)' with the output of the above command.
<br>
Runtime tests in Python are just plain strings comparison with the use of __doc__
properties.
</p>
<H2><a name="Doxygen_language_extension"></a>39.6 Extending to Other Languages</H2>
<p>
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.
</p>
<p>
<b> What is given to the Doxygen Translator</b>
</p>
<div class="code"><pre>
/*! This is describing function Foo
\param x some random variable
\author Bob
\return Foo
*/
</pre></div>
<p>
<b> What is received back by java.cxx </b>
</p>
<div class="targetlang"><pre>
/** This is describing function Foo
*
* @param x some random variable
* @author Bob
* @return Foo
*/
</pre></div>
<p> Development of the comment translator itself is simplified by the fact that the DoxygenTranslator module can easily include a <tt>main</tt> function and thus be developed, compiled, and tested independently of SWIG.
</p>
</body>
</html>
Reference in a new issue View git blame Copy permalink