mirror of https://github.com/swig/swig
1736 lines
38 KiB
HTML
1736 lines
38 KiB
HTML
<!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 Command Line Options</a>
|
|
<li><a href="#Doxygen_features">Doxygen-specific %feature Directives</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 Pydoc</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 Pydoc 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 Pydoc 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 specifications 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>/**<, /*!<, ///<, </i> or <i> //!<</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 described
|
|
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>
|
|
Doxygen comments translation is disabled by default and needs to be explicitly
|
|
enabled using the command line <tt>-doxygen</tt> switch for the languages that
|
|
do support it (currently Java and Python).
|
|
</p>
|
|
|
|
<H3><a name="Doxygen_features"></a>39.2.2 Doxygen-specific %feature Directives</H3>
|
|
|
|
<p>
|
|
Translation of Doxygen comments is influenced by the following <a
|
|
href="Customization.html#Customization_features">%feature directives</a>:
|
|
</p>
|
|
|
|
<h4>doxygen:notranslate</h4>
|
|
|
|
<p>
|
|
Turns off translation of Doxygen comments to the target language syntax: the
|
|
original comment will be copied to the output unchanged. This is useful if you
|
|
want to use Doxygen itself to generate documentation for the target language
|
|
instead of the corresponding language tool (<tt>javadoc</tt>, <tt>sphinx</tt>,
|
|
...).
|
|
</p>
|
|
|
|
|
|
<h4>doxygen:alias:<command-name></h4>
|
|
|
|
<p>
|
|
Specify an alias for a Doxygen command with the given name. This can be useful
|
|
for custom Doxygen commands which can be defined using <tt>ALIASES</tt> option
|
|
for Doxygen itself but which are unknown to SWIG. <tt>"command-name"</tt> is the
|
|
name of the command in the Doxyfile, e.g. if it contains
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
ALIASES = "sideeffect=\par Side Effects:\n"
|
|
</pre></div>
|
|
|
|
<p>
|
|
Then you could also the same expansion for SWIG with:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%feature("doxygen:alias:sideeffect") "\par Side Effects:\n"
|
|
</pre></div>
|
|
|
|
<p>
|
|
Please note that command arguments are not currently supported with this
|
|
feature.
|
|
</p>
|
|
|
|
<p>
|
|
Notice that it is perfectly possible and potentially useful to define the alias
|
|
expansion differently depending on the target language, e.g. with
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
#ifdef SWIGJAVA
|
|
%feature("doxygen:alias:not_for_java") "This functionality is not available for Java"
|
|
#else
|
|
%feature("doxygen:alias:not_for_java") ""
|
|
#endif
|
|
</pre></div>
|
|
|
|
<p>
|
|
you could use <tt>@not_for_java</tt> in the documentation comments of all
|
|
functions which can't, for whatever reason, be currently exposed in Java
|
|
wrappers of the C++ API.
|
|
</p>
|
|
|
|
|
|
<h4>doxygen:ignore:<command-name></h4>
|
|
|
|
<p>
|
|
This feature allows to just ignore an unknown Doxygen command, instead of
|
|
replacing it with a predefined text as <tt>doxygen:alias</tt> features allows to
|
|
do. For example, you could use
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%feature("doxygen:ignore:transferfull");
|
|
</pre></div>
|
|
|
|
<p>
|
|
if you use a custom Doxygen <tt>transferfull</tt> command to indicate that the
|
|
return value ownership is transferred to the caller, as this information doesn't
|
|
make much sense for the other languages without explicit ownership management.
|
|
</p>
|
|
|
|
<p>
|
|
Doxygen syntax is rather rich and, in addition to simple commands such as
|
|
<tt>@transferfull</tt>, it is also possible to define commands with arguments.
|
|
As explained in <a href="http://www.stack.nl/~dimitri/doxygen/manual/commands.html">Doxygen documentation</a>,
|
|
the arguments can have a range of a single word, everything until the end of
|
|
line or everything until the end of the next paragraph. Currently, only the "end
|
|
of line" case is supported using the <tt>range="line"</tt> argument of the
|
|
feature directive:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
// Ignore occurrences of
|
|
//
|
|
// @compiler-options Some special C++ compiler options.
|
|
//
|
|
// in Doxygen comments as C++ options are not interested for the target language
|
|
// developers.
|
|
%feature("doxygen:ignore:compileroptions", range="line");
|
|
</pre></div>
|
|
|
|
<p>
|
|
In addition, it is also possible to have custom pairs of begin/end tags,
|
|
similarly to the standard Doxygen <tt>@code/@endcode</tt>, for example. Such
|
|
tags can also be ignored using the special value of <tt>range</tt> starting with
|
|
<tt>end</tt> to indicate that the range is an interval, for example:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%feature("doxygen:ignore:forcpponly", range="end"); // same as "end:endforcpponly"
|
|
</pre></div>
|
|
|
|
<p>
|
|
would ignore everything between <tt>@forcpponly</tt> and <tt>@endforcpponly</tt>
|
|
commands in Doxygen comments. By default, the name of the end command is the
|
|
same as of the start one with "end" prefix, following Doxygen conventions, but
|
|
this can be overridden by providing the end command name after the colon.
|
|
</p>
|
|
<p>
|
|
This example shows how custom tags can be used to bracket anything specific to
|
|
C++ and prevent it from appearing in the target language documentation.
|
|
Conversely, another pair of custom tags could be used to put target language
|
|
specific information in the C++ comments. In this case, only the custom tags
|
|
themselves should be ignored, but their contents should be parsed as usual and
|
|
<tt>contents="parse"</tt> can be used for this:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse");
|
|
</pre></div>
|
|
|
|
<p>
|
|
Putting everything together, if these directives are in effect:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%feature("doxygen:ignore:transferfull");
|
|
%feature("doxygen:ignore:compileroptions", range="line");
|
|
%feature("doxygen:ignore:forcpponly", range="end");
|
|
%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse");
|
|
</pre></div>
|
|
|
|
<p>
|
|
then the following C++ Doxygen comment:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
/**
|
|
A contrived example of ignoring too many commands in one comment.
|
|
|
|
@forcpponly
|
|
This is C++-specific.
|
|
@endforcpponly
|
|
|
|
@beginPythonOnly
|
|
This is specific to @b Python.
|
|
@endPythonOnly
|
|
|
|
@transferfull Command ignored, but anything here is still included.
|
|
|
|
@compileroptions This function must be compiled with /EHa when using MSVC.
|
|
*/
|
|
void func();
|
|
</pre></div>
|
|
|
|
<p>
|
|
would be translated to this comment in Python:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
def func():
|
|
r"""
|
|
A contrived example of ignoring too many commands in one comment.
|
|
|
|
This is specific to **Python**.
|
|
|
|
Command ignored, but anything here is still included.
|
|
"""
|
|
...
|
|
</pre></div>
|
|
|
|
|
|
<h4>doxygen:nolinkranslate (Java-only currently)</h4>
|
|
|
|
<p>
|
|
Turn off automatic link-objects translation.
|
|
</p>
|
|
|
|
|
|
<h4>doxygen:nostripparams (Java-only currently)</h4>
|
|
|
|
<p>
|
|
Turn off stripping of <tt>@param</tt> and <tt>@tparam</tt>
|
|
Doxygen commands if the parameter is not found in the function signature.
|
|
</p>
|
|
|
|
|
|
<H3><a name="Doxygen_additional_options"></a>39.2.3 Additional Command Line Options</H3>
|
|
|
|
|
|
<p>
|
|
ALSO TO BE ADDED (Javadoc auto brief?)
|
|
</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; /*!< 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;
|
|
};
|
|
</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.
|
|
</p>
|
|
|
|
<p>
|
|
Javadoc translator features summary
|
|
(see <a href="Customization.html#Customization_features">%feature
|
|
directives</a>):
|
|
<br>
|
|
|
|
</p>
|
|
|
|
<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 <i> html tag</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\arg</td>
|
|
<td>wrapped with <li> 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 <b> html tag</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\c</td>
|
|
<td>wrapped with <code> html tag</td>
|
|
</tr>
|
|
<tr>
|
|
<tr>
|
|
<td>\cite</td>
|
|
<td>wrapped with <i> html tag</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\code</td>
|
|
<td>translated to {@code ...}</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\cond</td>
|
|
<td>translated to 'Conditional comment: <condition>'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\copyright</td>
|
|
<td>replaced with 'Copyright:'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\deprecated</td>
|
|
<td>translated to @deprecated</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\e</td>
|
|
<td>wrapped with <i> html tag</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\else</td>
|
|
<td>replaced with '}Else:{'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\elseif</td>
|
|
<td>replaced with '}Else if: <condition>{'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\em</td>
|
|
<td>wrapped with <i> 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: <condition> {'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\ifnot</td>
|
|
<td>replaced with 'If not: <condition> {'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\image</td>
|
|
<td>translated to <img/> html tag only if target=HTML</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\li</td>
|
|
<td>wrapped with <li> 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 <code> html tag</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\par</td>
|
|
<td>replaced with <p alt='title'>...</p></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 @throws</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>\&</td>
|
|
<td>prints & char</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>\#</td>
|
|
<td>prints # char</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>\::</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 (all supported tags are listed in
|
|
<a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html">Javadoc documentation</a>).
|
|
As a result several tags that have no
|
|
translation (or particular use, such as some linking and section tags)
|
|
are suppressed 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>\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 Pydoc</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 plain text 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; /*!< 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;
|
|
};
|
|
</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>
|
|
If any parameters of a function or a method are documented in the Doxygen comment,
|
|
their description is copied into the generated output using
|
|
<a href="http://sphinx-doc.org/">Sphinx </a> documentation conventions. For example
|
|
</p>
|
|
<div class="code"><pre>
|
|
/**
|
|
Set a breakpoint at the given location.
|
|
|
|
@param filename The full path to the file.
|
|
@param line_number The line number in the file.
|
|
*/
|
|
bool SetBreakpoint(const char* filename, int line_number);
|
|
</pre></div>
|
|
would be translated to
|
|
<div class="targetlang"><pre>
|
|
def SetBreakpoint(*args):
|
|
r"""
|
|
Set a breakpoint at the given location.
|
|
|
|
:type filename: string
|
|
:param filename: The full path to the file.
|
|
:type line_number: int
|
|
:param line_number: The line number in the file.
|
|
"""
|
|
</pre></div>
|
|
<p>
|
|
The types used for the parameter documentation come from <tt>doctype</tt> typemap which
|
|
is defined for all the primitive types and a few others (e.g. <tt>std::string</tt> and
|
|
<tt>shared_ptr<T></tt>) but for non-primitive types is taken to be just the C++
|
|
name of the type with namespace scope delimiters (<tt>::</tt>) replaced with a dot. To
|
|
change this, you can define your own typemaps for the custom types, e.g:
|
|
</p>
|
|
<div class="code"><pre>
|
|
%typemap(doctype) MyDate "datetime.date";
|
|
</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>
|
|
<b>Whitespace and tables</b><br>
|
|
Whitespace is preserved when translating comments, so it makes
|
|
sense to have Doxygen comments formatted in a readable way. This
|
|
includes tables, where tags <th>, <td> and </tr>are translated
|
|
to '|'. The line after line with <th> tags contains dashes.
|
|
If we take care about whitespace, comments in Python are much more
|
|
readable. Example:
|
|
|
|
<div class="code"><pre>
|
|
/**
|
|
* <table border = '1'>
|
|
* <caption>Animals</caption>
|
|
* <tr><th> Column 1 </th><th> Column 2 </th></tr>
|
|
* <tr><td> cow </td><td> dog </td></tr>
|
|
* <tr><td> cat </td><td> mouse </td></tr>
|
|
* <tr><td> horse </td><td> parrot </td></tr>
|
|
* </table>
|
|
*/
|
|
</pre></div>
|
|
<p/>
|
|
translates to Python as:
|
|
<p/>
|
|
<div class="targetlang"><pre>
|
|
Animals
|
|
| Column 1 | Column 2 |
|
|
-----------------------
|
|
| cow | dog |
|
|
| cat | mouse |
|
|
| horse | parrot |
|
|
</pre></div>
|
|
</p>
|
|
|
|
<p>
|
|
<b>Overloaded functions</b><br>
|
|
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 doesn'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>
|
|
|
|
<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: <condition>'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\copyright</td>
|
|
<td>prints 'Copyright:'</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: <condition>{'</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: <condition> {'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\ifnot</td>
|
|
<td>replaced with 'If not: <condition> {'</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>\&</td>
|
|
<td>prints & char</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>\#</td>
|
|
<td>prints # char</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\%</td>
|
|
<td>prints % char</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\"</td>
|
|
<td>prints " char</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\.</td>
|
|
<td>prints . character</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 suppressed 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 built with the
|
|
commands like 'make check-test-suite' or 'make
|
|
check-python-test-suite'. To run them individually, type
|
|
<code>make <testname>.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>
|
|
|
|
If the test fails, both expected and translated comments are printed to
|
|
std out, but also written to files <i>expected.txt</i>
|
|
and <I>got.txt</I>. Since it is often difficult to find a single
|
|
character difference in several lines of text, we can use some diff
|
|
tool, for example:
|
|
<pre>
|
|
Examples/test-suite/java $ kdiff3 expected.txt got.txt
|
|
</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 directory (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>
|