mirror of https://github.com/swig/swig
2300 lines
53 KiB
HTML
2300 lines
53 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">18 SWIG and Doxygen Translation</a></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_features">Doxygen-specific %feature directives</a>
|
|
<ul>
|
|
<li><a href="#Doxygen_notranslate">doxygen:notranslate</a>
|
|
<li><a href="#Doxygen_alias">doxygen:alias:<command-name></a>
|
|
<li><a href="#Doxygen_ignore">doxygen:ignore:<command-name></a>
|
|
<li><a href="#Doxygen_nolinktranslate">doxygen:nolinktranslate</a>
|
|
<li><a href="#Doxygen_nostripparams">doxygen:nostripparams</a>
|
|
</ul>
|
|
<li><a href="#Doxygen_additional_options">Additional command line options</a>
|
|
</ul>
|
|
<li><a href="#Doxygen_javadoc">Doxygen to Javadoc</a>
|
|
<ul>
|
|
<li><a href="#Doxygen_javadoc_basic_example">Basic Javadoc example</a>
|
|
<li><a href="#Doxygen_javadoc_tags">Javadoc tags</a>
|
|
<li><a href="#Doxygen_javadoc_unsupported_tags">Unsupported tags for Javadoc</a>
|
|
</ul>
|
|
<li><a href="#Doxygen_pydoc">Doxygen to Pydoc</a>
|
|
<ul>
|
|
<li><a href="#Doxygen_pydoc_basic_example">Basic Pydoc example</a>
|
|
<li><a href="#Doxygen_pydoc_tags">Pydoc translator</a>
|
|
<li><a href="#Doxygen_pydoc_unsupported_tags">Unsupported tags for Pydoc</a>
|
|
</ul>
|
|
<li><a href="#Doxygen_csharp">Doxygen to XML C# documentation</a>
|
|
<ul>
|
|
<li><a href="#Doxygen_csharp_basic_example">Basic C# example</a>
|
|
<li><a href="#Doxygen_csharp_tags">C# tags</a>
|
|
<li><a href="#Doxygen_csharp_unsupported_tags">Unsupported tags for C#</a>
|
|
</ul>
|
|
<li><a href="#Doxygen_troubleshooting">Troubleshooting</a>
|
|
<ul>
|
|
<li><a href="#troubleshooting_ifndef">Problem with conditional compilation</a>
|
|
</ul>
|
|
<li><a href="#Doxygen_developer_details">Developer information</a>
|
|
<ul>
|
|
<li><a href="#Doxygen_translator_design">Doxygen translator design</a>
|
|
<li><a href="#Doxygen_debugging_commands">Debugging the Doxygen parser and translator</a>
|
|
<li><a href="#Doxygen_tests">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">18.1 Doxygen translation overview</a></H2>
|
|
|
|
|
|
<p>
|
|
The Doxygen Translation module of SWIG adds an extra layer of
|
|
functionality to SWIG, allowing automated translation of <a href=
|
|
"https://www.doxygen.nl/manual/">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.
|
|
Other extensions could be added at a later date.
|
|
The Doxygen Translation module originally started as
|
|
a <a href="https://developers.google.com/open-source/gsoc/2008/">Google Summer of
|
|
Code</a> proposal from Summer 2008.
|
|
</p>
|
|
|
|
<H2><a name="Doxygen_file_preparation">18.2 Preparations</a></H2>
|
|
|
|
|
|
<p>
|
|
To make use of the comment translation system, your documentation
|
|
comments must be in properly formatted <a href=
|
|
"https://www.doxygen.nl/manual/">Doxygen.</a> Doxygen comments can be
|
|
present in your main SWIG interface file or any header file that it
|
|
imports. You are advised to be validate that your comments compile
|
|
properly with Doxygen before you try to translate them. Doxygen
|
|
itself is a more comprehensive tool and can provide you better feedback for
|
|
correcting any syntax errors that may be present. Please look at
|
|
Doxygen's <a href=
|
|
"https://www.doxygen.nl/manual/docblocks.html"> Documenting the
|
|
code</a> for the full comment format specifications. However, SWIG's
|
|
Doxygen parser will still report many errors and warnings found
|
|
in comments (like unterminated strings or missing ending tags).
|
|
</p>
|
|
|
|
<p>
|
|
Currently, the whole subset of Doxygen comment styles is supported
|
|
(See <a href="https://www.doxygen.nl/manual/docblocks.html">
|
|
Documenting the code</a>). Here they are:
|
|
</p>
|
|
|
|
<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>
|
|
Also any of the above with '<tt><</tt>' added after comment-starting symbol,
|
|
like <tt>/**<, /*!<, ///<, </tt> or <tt> //!<</tt> will be
|
|
treated as a post-comment and will be assigned to the code before the
|
|
comment.
|
|
|
|
Any number of '<tt>*</tt>' or '<tt>/</tt>' within a Doxygen comment is
|
|
considered to be a separator and is not included in the final comment,
|
|
so you may safely use comments like <tt>/*********/</tt>
|
|
or <tt>//////////</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
Please note, as SWIG parses the input file by itself with strict grammar,
|
|
there is only a limited support for various cases of comment placement
|
|
in the file.
|
|
</p>
|
|
<p>
|
|
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 its value
|
|
EN_ONE, ///< The second, EN_ONE=1
|
|
EN_THREE
|
|
};
|
|
</pre></div>
|
|
|
|
<p>
|
|
Currently only comments directly before or after the code items
|
|
are supported. Doxygen also supports comments containing structural commands,
|
|
where the comments for a code item are not put directly before or after the code item.
|
|
These structural commands are stripped out by SWIG and are not assigned to anything.
|
|
</p>
|
|
|
|
<H3><a name="Doxygen_running_swig">18.2.1 Enabling Doxygen translation</a></H3>
|
|
|
|
|
|
<p>
|
|
Doxygen comments translation is disabled by default and needs to be explicitly
|
|
enabled using the command line <tt>-doxygen</tt> option for the languages that
|
|
do support it (currently Java and Python).
|
|
</p>
|
|
|
|
<H3><a name="Doxygen_features">18.2.2 Doxygen-specific %feature directives</a></H3>
|
|
|
|
|
|
<p>
|
|
Translation of Doxygen comments is influenced by the following <a
|
|
href="Customization.html#Customization_features">%feature directives</a>:
|
|
</p>
|
|
|
|
<H4><a name="Doxygen_notranslate">18.2.2.1 doxygen:notranslate</a></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><a name="Doxygen_alias">18.2.2.2 doxygen:alias:<command-name></a></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 specify 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><a name="Doxygen_ignore">18.2.2.3 doxygen:ignore:<command-name></a></H4>
|
|
|
|
|
|
<p>
|
|
This feature makes it possible to just ignore an unknown Doxygen command, instead of
|
|
replacing it with the predefined text that <tt>doxygen:alias</tt> does.
|
|
For example, you could use
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%feature("doxygen:ignore:transferfull") Fantastic();
|
|
/**
|
|
A fantastic function.
|
|
|
|
@transferfull Command ignored, but anything here is still included.
|
|
*/
|
|
int * Fantastic();
|
|
</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="https://www.doxygen.nl/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
|
|
//
|
|
// @compileroptions Some special C++ compiler options.
|
|
//
|
|
// in Doxygen comments as C++ options are not interesting for the target language
|
|
// developers.
|
|
%feature("doxygen:ignore:compileroptions", range="line") Amazing();
|
|
|
|
/**
|
|
An amazing function.
|
|
|
|
@compileroptions This function must be compiled with /EHa when using MSVC.
|
|
*/
|
|
void Amazing();
|
|
|
|
</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"
|
|
/**
|
|
An incredible function.
|
|
|
|
@forcpponly
|
|
This is C++-specific.
|
|
@endforcpponly
|
|
*/
|
|
void Incredible();
|
|
</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");
|
|
/**
|
|
A splendid function.
|
|
|
|
@beginPythonOnly
|
|
This is specific to @b Python.
|
|
@endPythonOnly
|
|
*/
|
|
void Splendid();
|
|
|
|
</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.
|
|
*/
|
|
int * Contrived();
|
|
</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><a name="Doxygen_nolinktranslate">18.2.2.4 doxygen:nolinktranslate</a></H4>
|
|
|
|
|
|
<p>
|
|
Turn off automatic link-objects translation.
|
|
This is only applicable to Java at the moment.
|
|
</p>
|
|
|
|
|
|
<H4><a name="Doxygen_nostripparams">18.2.2.5 doxygen:nostripparams</a></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.
|
|
This is only applicable to Java at the moment.
|
|
</p>
|
|
|
|
|
|
<H3><a name="Doxygen_additional_options">18.2.3 Additional command line options</a></H3>
|
|
|
|
|
|
<p>
|
|
ALSO TO BE ADDED (Javadoc auto brief?)
|
|
</p>
|
|
|
|
<H2><a name="Doxygen_javadoc">18.3 Doxygen to Javadoc</a></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_javadoc_basic_example">18.3.1 Basic Javadoc example</a></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 the doxygen functionality enabled. When the Doxygen Translator
|
|
module encounters a comment that contains nothing useful or a doxygen comment that it cannot
|
|
parse, it will not affect the functionality of the SWIG generated
|
|
code.
|
|
</p>
|
|
|
|
<p>
|
|
The Javadoc translator will handle most of the tags conversions (see the
|
|
table below). It will also automatically translate link-objects
|
|
params, in <tt>\see</tt> and <tt>\link...\endlink</tt> commands. For example,
|
|
<tt>someFunction(std::string)</tt> will be converted to
|
|
<tt>someFunction(String)</tt>. If
|
|
you don't want such behaviour, you could turn this off by using the
|
|
<tt>doxygen:nolinktranslate</tt> feature. Also all <tt>\param</tt> and <tt>\tparam</tt>
|
|
commands are stripped out, if the specified parameter is not present in
|
|
the function. Use <tt>doxygen:nostripparams</tt> to avoid.
|
|
</p>
|
|
|
|
<p>
|
|
Javadoc translator features summary
|
|
(see <a href="Customization.html#Customization_features">%feature
|
|
directives</a>):
|
|
</p>
|
|
|
|
<H3><a name="Doxygen_javadoc_tags">18.3.2 Javadoc tags</a></H3>
|
|
|
|
|
|
<p>
|
|
Here is the list of all Doxygen tags and the description of how they are translated to Javadoc
|
|
</p>
|
|
<div class="diagram">
|
|
<table border="0" summary="Java Doxygen tags">
|
|
<tr>
|
|
<th align="left">Doxygen tags</th>
|
|
</tr>
|
|
<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>
|
|
<td>\cite</td>
|
|
<td>wrapped with <i> html tag</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\code</td>
|
|
<td>translated to {@code ...}</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\code{<ext>}</td>
|
|
<td>translated to {@code ...}; code language extension is ignored</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 newline 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>\param[<dir>]</td>
|
|
<td>translated to @param; parameter direction ('in'; 'out'; or 'in,out') is ignored</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>
|
|
</div>
|
|
|
|
<H3><a name="Doxygen_javadoc_unsupported_tags">18.3.3 Unsupported tags for Javadoc</a></H3>
|
|
|
|
|
|
<p>
|
|
Doxygen has a wealth of tags such as <tt>@latexonly</tt> that have no
|
|
equivalent in Javadoc (all supported tags are listed in
|
|
<a href="https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html">Javadoc documentation</a>).
|
|
As a result several tags have no
|
|
translation or particular use, such as some linking and section tags.
|
|
These are suppressed with their content just printed out (if the tag has any
|
|
sense, typically text content).
|
|
Here is the list of these tags:
|
|
</p>
|
|
|
|
<div class="diagram">
|
|
<b>Unsupported Doxygen tags</b>
|
|
|
|
<ul style="list-style-type:none;column-count:4;">
|
|
<li>\addindex</li>
|
|
<li>\addtogroup</li>
|
|
<li>\anchor</li>
|
|
<li>\attention</li>
|
|
<li>\brief</li>
|
|
<li>\bug</li>
|
|
<li>\callergraph</li>
|
|
<li>\callgraph</li>
|
|
<li>\category</li>
|
|
<li>\class</li>
|
|
<li>\copybrief</li>
|
|
<li>\copydetails</li>
|
|
<li>\copydoc</li>
|
|
<li>\date</li>
|
|
<li>\def</li>
|
|
<li>\defgroup</li>
|
|
<li>\details</li>
|
|
<li>\dir</li>
|
|
<li>\dontinclude</li>
|
|
<li>\dot</li>
|
|
<li>\dotfile</li>
|
|
<li>\enddot</li>
|
|
<li>\endhtmlonly</li>
|
|
<li>\endinternal</li>
|
|
<li>\endlatexonly</li>
|
|
<li>\endmanonly</li>
|
|
<li>\endmsc</li>
|
|
<li>\endrtfonly</li>
|
|
<li>\endxmlonly</li>
|
|
<li>\enum</li>
|
|
<li>\example</li>
|
|
<li>\extends</li>
|
|
<li>\file</li>
|
|
<li>\fn</li>
|
|
<li>\headerfile</li>
|
|
<li>\hideinitializer</li>
|
|
<li>\htmlinclude</li>
|
|
<li>\htmlonly</li>
|
|
<li>\implements</li>
|
|
<li>\include</li>
|
|
<li>\includelineno</li>
|
|
<li>\ingroup</li>
|
|
<li>\interface</li>
|
|
<li>\internal</li>
|
|
<li>\invariant</li>
|
|
<li>\latexonly</li>
|
|
<li>\line</li>
|
|
<li>\mainpage</li>
|
|
<li>\manonly</li>
|
|
<li>\memberof</li>
|
|
<li>\msc</li>
|
|
<li>\mscfile</li>
|
|
<li>\name</li>
|
|
<li>\namespace</li>
|
|
<li>\nosubgrouping</li>
|
|
<li>\package</li>
|
|
<li>\page</li>
|
|
<li>\paragraph</li>
|
|
<li>\post</li>
|
|
<li>\pre</li>
|
|
<li>\private</li>
|
|
<li>\privatesection</li>
|
|
<li>\property</li>
|
|
<li>\protected</li>
|
|
<li>\protectedsection</li>
|
|
<li>\protocol</li>
|
|
<li>\public</li>
|
|
<li>\publicsection</li>
|
|
<li>\ref</li>
|
|
<li>\related</li>
|
|
<li>\relatedalso</li>
|
|
<li>\relates</li>
|
|
<li>\relatesalso</li>
|
|
<li>\retval</li>
|
|
<li>\rtfonly</li>
|
|
<li>\section</li>
|
|
<li>\short</li>
|
|
<li>\showinitializer</li>
|
|
<li>\skip</li>
|
|
<li>\skipline</li>
|
|
<li>\snippet</li>
|
|
<li>\struct</li>
|
|
<li>\subpage</li>
|
|
<li>\subsection</li>
|
|
<li>\subsubsection</li>
|
|
<li>\tableofcontents</li>
|
|
<li>\test</li>
|
|
<li>\typedef</li>
|
|
<li>\union</li>
|
|
<li>\until</li>
|
|
<li>\var</li>
|
|
<li>\verbinclude</li>
|
|
<li>\weakgroup</li>
|
|
<li>\xmlonly</li>
|
|
<li>\xrefitem</li>
|
|
</ul>
|
|
</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">
|
|
<b>Ignored Doxygen tags</b>
|
|
|
|
<ul style="list-style-type:none;column-count:4;">
|
|
<li>\addtogroup</li>
|
|
<li>\callergraph</li>
|
|
<li>\callgraph</li>
|
|
<li>\category</li>
|
|
<li>\class</li>
|
|
<li>\def</li>
|
|
<li>\defgroup</li>
|
|
<li>\dir</li>
|
|
<li>\enum</li>
|
|
<li>\example</li>
|
|
<li>\file</li>
|
|
<li>\fn</li>
|
|
<li>\headerfile</li>
|
|
<li>\hideinitializer</li>
|
|
<li>\interface</li>
|
|
<li>\internal</li>
|
|
<li>\mainpage</li>
|
|
<li>\name</li>
|
|
<li>\namespace</li>
|
|
<li>\nosubgrouping</li>
|
|
<li>\overload</li>
|
|
<li>\package</li>
|
|
<li>\page</li>
|
|
<li>\property</li>
|
|
<li>\protocol</li>
|
|
<li>\relates</li>
|
|
<li>\relatesalso</li>
|
|
<li>\showinitializer</li>
|
|
<li>\struct</li>
|
|
<li>\typedef</li>
|
|
<li>\union</li>
|
|
<li>\var</li>
|
|
<li>\weakgroup</li>
|
|
</ul>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<H2><a name="Doxygen_pydoc">18.4 Doxygen to Pydoc</a></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 by merely
|
|
copying the appropriate command text.
|
|
</p>
|
|
|
|
<H3><a name="Doxygen_pydoc_basic_example">18.4.1 Basic Pydoc example</a></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="https://www.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>
|
|
|
|
<p>
|
|
would be translated to
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
def SetBreakpoint(filename, line_number):
|
|
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 the "doctype" 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 global variables and static member variables
|
|
are not present in generated code, so they have no comment translated for them.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Whitespace and tables</b>
|
|
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="diagram"><pre>
|
|
Animals
|
|
| Column 1 | Column 2 |
|
|
-----------------------
|
|
| cow | dog |
|
|
| cat | mouse |
|
|
| horse | parrot |
|
|
</pre></div>
|
|
|
|
<p>
|
|
<b>Overloaded functions</b>
|
|
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 into the comment for the one wrapper function.
|
|
</p>
|
|
<p>
|
|
If you intend to use resulting generated Python file with the Doxygen docs
|
|
generator, rather than Pydoc, you may want to turn off translation
|
|
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="https://www.doxygen.nl/manual/docblocks.html#pythonblocks">Doxygen
|
|
docs</a>), you may want to use some tool like doxypy
|
|
(<a href="https://pypi.org/project/doxypy/">doxypy</a>)
|
|
to do the work.
|
|
</p>
|
|
|
|
<H3><a name="Doxygen_pydoc_tags">18.4.2 Pydoc translator</a></H3>
|
|
|
|
|
|
<p>
|
|
Here is the list of all Doxygen tags and the description of how they are translated to Pydoc
|
|
</p>
|
|
<div class="diagram">
|
|
<table border="0" summary="Python Doxygen tags">
|
|
<tr>
|
|
<th align="left">Doxygen tags</th>
|
|
</tr>
|
|
<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 'Authors:'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\b</td>
|
|
<td>wrapped with '**'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\c</td>
|
|
<td>wrapped with '``'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\cite</td>
|
|
<td>wrapped with single quotes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\code</td>
|
|
<td>replaced with '.. code-block:: c++'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\code{<ext>}</td>
|
|
<td>replaced with '.. code-block:: <lang>', where the following doxygen code languages are recognized: .c -> C, .py -> python, .java > java</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>\example</td>
|
|
<td>replaced with 'Example:'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\exception</td>
|
|
<td>replaced with ':raises:'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\f$</td>
|
|
<td>rendered using ':math:``'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\f[</td>
|
|
<td>rendered using '.. math::'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\f{</td>
|
|
<td>rendered using '.. math::'</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 newline 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 '``'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\par</td>
|
|
<td>replaced with 'Title: ...'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\param</td>
|
|
<td>add ':type:' and ':param:' directives</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\param[<dir>]</td>
|
|
<td>same as \param, but direction ('in'; 'out'; 'in,out') is included in ':type:' directive</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>add ':rtype:' and ':return:' directives</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\return</td>
|
|
<td>add ':rtype:' and ':return:' directives</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\returns</td>
|
|
<td>add ':rtype:' and ':return:' directives</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 ':raises:'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\throws</td>
|
|
<td>replaced with ':raises:'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\todo</td>
|
|
<td>replaced with 'TODO:'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\tparam</td>
|
|
<td>add ':type:' and ':param:' directives</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\verbatim</td>
|
|
<td>content copied verbatim</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>
|
|
</div>
|
|
|
|
<H3><a name="Doxygen_pydoc_unsupported_tags">18.4.3 Unsupported tags for Pydoc</a></H3>
|
|
|
|
|
|
<p>
|
|
Doxygen has a wealth of tags such as <tt>@latexonly</tt> 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).
|
|
Here is the list of these tags:
|
|
</p>
|
|
|
|
<div class="diagram">
|
|
<b>Unsupported Python Doxygen tags</b>
|
|
|
|
<ul style="list-style-type:none;column-count:4;">
|
|
<li>\addindex</li>
|
|
<li>\addtogroup</li>
|
|
<li>\anchor</li>
|
|
<li>\attention</li>
|
|
<li>\brief</li>
|
|
<li>\bug</li>
|
|
<li>\callergraph</li>
|
|
<li>\callgraph</li>
|
|
<li>\category</li>
|
|
<li>\class</li>
|
|
<li>\copybrief</li>
|
|
<li>\copydetails</li>
|
|
<li>\copydoc</li>
|
|
<li>\date</li>
|
|
<li>\def</li>
|
|
<li>\defgroup</li>
|
|
<li>\details</li>
|
|
<li>\dir</li>
|
|
<li>\dontinclude</li>
|
|
<li>\dot</li>
|
|
<li>\dotfile</li>
|
|
<li>\enddot</li>
|
|
<li>\endhtmlonly</li>
|
|
<li>\endinternal</li>
|
|
<li>\endlatexonly</li>
|
|
<li>\endlink</li>
|
|
<li>\endmanonly</li>
|
|
<li>\endmsc</li>
|
|
<li>\endrtfonly</li>
|
|
<li>\endxmlonly</li>
|
|
<li>\enum</li>
|
|
<li>\extends</li>
|
|
<li>\file</li>
|
|
<li>\fn</li>
|
|
<li>\headerfile</li>
|
|
<li>\hideinitializer</li>
|
|
<li>\htmlinclude</li>
|
|
<li>\htmlonly</li>
|
|
<li>\image</li>
|
|
<li>\implements</li>
|
|
<li>\include</li>
|
|
<li>\includelineno</li>
|
|
<li>\ingroup</li>
|
|
<li>\interface</li>
|
|
<li>\internal</li>
|
|
<li>\invariant</li>
|
|
<li>\latexonly</li>
|
|
<li>\line</li>
|
|
<li>\link</li>
|
|
<li>\mainpage</li>
|
|
<li>\manonly</li>
|
|
<li>\memberof</li>
|
|
<li>\msc</li>
|
|
<li>\mscfile</li>
|
|
<li>\name</li>
|
|
<li>\namespace</li>
|
|
<li>\nosubgrouping</li>
|
|
<li>\package</li>
|
|
<li>\page</li>
|
|
<li>\paragraph</li>
|
|
<li>\post</li>
|
|
<li>\pre</li>
|
|
<li>\private</li>
|
|
<li>\privatesection</li>
|
|
<li>\property</li>
|
|
<li>\protected</li>
|
|
<li>\protectedsection</li>
|
|
<li>\protocol</li>
|
|
<li>\public</li>
|
|
<li>\publicsection</li>
|
|
<li>\ref</li>
|
|
<li>\related</li>
|
|
<li>\relatedalso</li>
|
|
<li>\relates</li>
|
|
<li>\relatesalso</li>
|
|
<li>\retval</li>
|
|
<li>\rtfonly</li>
|
|
<li>\section</li>
|
|
<li>\short</li>
|
|
<li>\showinitializer</li>
|
|
<li>\skip</li>
|
|
<li>\skipline</li>
|
|
<li>\snippet</li>
|
|
<li>\struct</li>
|
|
<li>\subpage</li>
|
|
<li>\subsection</li>
|
|
<li>\subsubsection</li>
|
|
<li>\tableofcontents</li>
|
|
<li>\test</li>
|
|
<li>\typedef</li>
|
|
<li>\union</li>
|
|
<li>\until</li>
|
|
<li>\var</li>
|
|
<li>\verbinclude</li>
|
|
<li>\weakgroup</li>
|
|
<li>\xmlonly</li>
|
|
<li>\xrefitem</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<H2><a name="Doxygen_csharp">18.5 Doxygen to XML C# documentation</a></H2>
|
|
|
|
|
|
<p>
|
|
If translation is enabled, XML formatted comments should be
|
|
automatically placed in the correct locations in the resulting module
|
|
and proxy files.
|
|
</p>
|
|
|
|
<H3><a name="Doxygen_csharp_basic_example">18.5.1 Basic C# example</a></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--;
|
|
};
|
|
/** Important Variables x*/
|
|
double x;
|
|
/** Important Variables y*/
|
|
double y;
|
|
/** Moves the Shape
|
|
* @param dx delta on x
|
|
* @param dy delta on y */
|
|
void move(double dx, double dy);
|
|
/** \return the area */
|
|
virtual double area(void) = 0;
|
|
/** \return the perimeter */
|
|
virtual double perimeter(void) = 0;
|
|
static int nshapes;
|
|
};
|
|
</pre></div>
|
|
|
|
<p>
|
|
Simply running SWIG should result in the following code being present in Shapes.cs
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
|
|
/// <summary>This is describing class Shape
|
|
/// Author: Bob
|
|
/// </summary>
|
|
public class Shape {
|
|
|
|
...
|
|
/// Important Variables x
|
|
public double x {
|
|
set {
|
|
ShapesCsPINVOKE.Shape_x_set(swigCPtr, value);
|
|
}
|
|
get {
|
|
double ret = ShapesCsPINVOKE.Shape_x_get(swigCPtr);
|
|
return ret;
|
|
}
|
|
}
|
|
|
|
/// Important Variables y
|
|
public double y {
|
|
set {
|
|
ShapesCsPINVOKE.Shape_y_set(swigCPtr, value);
|
|
}
|
|
get {
|
|
double ret = ShapesCsPINVOKE.Shape_y_get(swigCPtr);
|
|
return ret;
|
|
}
|
|
}
|
|
|
|
/// Moves the Shape
|
|
/// <param name="dx"> delta on x</param>
|
|
/// <param name="dy"> delta on y</param>
|
|
public void move(double dx, double dy) {
|
|
ShapesCsPINVOKE.Shape_move(swigCPtr, dx, dy);
|
|
}
|
|
|
|
/// <returns>the area</returns>
|
|
public virtual double area() {
|
|
double ret = ShapesCsPINVOKE.Shape_area(swigCPtr);
|
|
return ret;
|
|
}
|
|
|
|
/// <returns>the perimeter</returns>
|
|
public virtual double perimeter() {
|
|
double ret = ShapesCsPINVOKE.Shape_perimeter(swigCPtr);
|
|
return ret;
|
|
}
|
|
|
|
public static int nshapes {
|
|
set {
|
|
ShapesCsPINVOKE.Shape_nshapes_set(value);
|
|
}
|
|
get {
|
|
int ret = ShapesCsPINVOKE.Shape_nshapes_get();
|
|
return ret;
|
|
}
|
|
}
|
|
}
|
|
|
|
</pre></div>
|
|
|
|
<p>
|
|
Otherwise, the code should be identical to what would have been
|
|
generated without the Doxygen functionality enabled. When the Doxygen Translator
|
|
module encounters a comment that contains nothing useful or a Doxygen comment that it cannot
|
|
parse, it will not affect the functionality of the SWIG generated
|
|
code.
|
|
</p>
|
|
|
|
<p>
|
|
The translator will handle most of the tags conversions (see the
|
|
table below). It will also automatically translate link-objects
|
|
params, in <tt><seealso></tt> tags .
|
|
Also all <tt>\param</tt> and <tt>\tparam</tt> commands are stripped out, if the specified parameter is not present in
|
|
the function. Use <tt>doxygen:nostripparams</tt> to avoid.
|
|
</p>
|
|
|
|
<p>
|
|
C# translator features summary
|
|
(see <a href="Customization.html#Customization_features">%feature
|
|
directives</a>):
|
|
</p>
|
|
|
|
<H3><a name="Doxygen_csharp_tags">18.5.2 C# tags</a></H3>
|
|
|
|
|
|
<p>
|
|
Here is the list of all Doxygen tags and the description of how they are translated to C# XML
|
|
</p>
|
|
<div class="diagram">
|
|
<table border="0" summary="CSharp XML Doxygen tags">
|
|
<tr>
|
|
<th align="left">Doxygen tags</th>
|
|
</tr>
|
|
<tr>
|
|
<td>\a</td>
|
|
<td>wrapped with '*' markdown character</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\arg</td>
|
|
<td>prefixed with '*' markdown character</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\author</td>
|
|
<td>Made simple text with prefix 'Author:'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\authors</td>
|
|
<td>Made simple text with prefix 'Author:'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\b</td>
|
|
<td>wrapped with '**' markdown character</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\c</td>
|
|
<td>wrapped with `` markdown character</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\cite</td>
|
|
<td>started with ' markdown character</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\code</td>
|
|
<td>wrapped in <code> tag </td>
|
|
</tr>
|
|
<tr>
|
|
<td>\code{<ext>}</td>
|
|
<td>wrapped in <code> tag. code language extension is ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\cond</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\copyright</td>
|
|
<td>wrapped in <remark> tag</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\deprecated</td>
|
|
<td>Made simple text with prefix 'Deprecated:' </td>
|
|
</tr>
|
|
<tr>
|
|
<td>\e</td>
|
|
<td>prefixed with '*' markdown character</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\else</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\elseif</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\em</td>
|
|
<td>prefixed with '*' markdown character</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\endcode</td>
|
|
<td>wrapped in <code> tag. code language extension is ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\endcond</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\endif</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\endlink</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\endverbatim</td>
|
|
<td>see note for \verbatim</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\exception</td>
|
|
<td>translated to <exception> section</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\f$, \f[, \f], \f{, \f}</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\if</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\ifnot</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\image</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\li</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\link</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\n</td>
|
|
<td>replaced with newline char</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\note</td>
|
|
<td>Content copied</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\overload</td>
|
|
<td>Ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\p</td>
|
|
<td>wrapped with `` markdown characters</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\par</td>
|
|
<td>Made simple text with prefix "Title:"</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\param</td>
|
|
<td>translated to <param> xml section</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\param[<dir>]</td>
|
|
<td>translated to <param> xml section; parameter direction ('in'; 'out'; or 'in,out') is ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\remark</td>
|
|
<td>Made simple text with prefix "remarks:"</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\remarks</td>
|
|
<td>Made simple text with prefix "remarks:"</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\result</td>
|
|
<td>translated to <return> xml section</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\return</td>
|
|
<td>translated to <return> xml section</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\returns</td>
|
|
<td>translated to <return> xml section</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\sa</td>
|
|
<td>translated to <seealso> xml section</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\see</td>
|
|
<td>translated to <seealso> xml section</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\since</td>
|
|
<td>Content copied</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\throw</td>
|
|
<td>translated to <exception></td>
|
|
</tr>
|
|
<tr>
|
|
<td>\throws</td>
|
|
<td>translated to <exception></td>
|
|
</tr>
|
|
<tr>
|
|
<td>\todo</td>
|
|
<td>Prefixed with 'TODO:'</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\tparam</td>
|
|
<td>translated to <exception> xml section</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\verbatim</td>
|
|
<td>copied without any processing</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\version</td>
|
|
<td>Made simple text with prefix 'Version:"</td>
|
|
</tr>
|
|
<tr>
|
|
<td>\warning</td>
|
|
<td>Made simple text with prefix 'remarks:"</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>
|
|
</div>
|
|
|
|
<H3><a name="Doxygen_csharp_unsupported_tags">18.5.3 Unsupported tags for C#</a></H3>
|
|
|
|
|
|
<p>
|
|
Doxygen has a wealth of tags such as <tt>@latexonly</tt> that have no
|
|
equivalent in C# XML (all supported tags are listed in
|
|
<a href="https://www.doxygen.nl/manual/xmlcmds.html">XML documentation</a>).
|
|
As a result several tags have no
|
|
translation or particular use, such as some linking and section tags.
|
|
These are suppressed with their content just printed out (if the tag has any
|
|
sense, typically text content).
|
|
Here is the list of these tags:
|
|
</p>
|
|
|
|
<div class="diagram">
|
|
<b>Unsupported Doxygen tags</b>
|
|
|
|
<ul style="list-style-type:none;column-count:4;">
|
|
<li>\addindex</li>
|
|
<li>\addtogroup</li>
|
|
<li>\anchor</li>
|
|
<li>\attention</li>
|
|
<li>\brief</li>
|
|
<li>\bug</li>
|
|
<li>\callergraph</li>
|
|
<li>\callgraph</li>
|
|
<li>\category</li>
|
|
<li>\class</li>
|
|
<li>\copybrief</li>
|
|
<li>\copydetails</li>
|
|
<li>\copydoc</li>
|
|
<li>\date</li>
|
|
<li>\def</li>
|
|
<li>\defgroup</li>
|
|
<li>\details</li>
|
|
<li>\dir</li>
|
|
<li>\dontinclude</li>
|
|
<li>\dot</li>
|
|
<li>\dotfile</li>
|
|
<li>\enddot</li>
|
|
<li>\endhtmlonly</li>
|
|
<li>\endinternal</li>
|
|
<li>\endlatexonly</li>
|
|
<li>\endmanonly</li>
|
|
<li>\endmsc</li>
|
|
<li>\endrtfonly</li>
|
|
<li>\endxmlonly</li>
|
|
<li>\enum</li>
|
|
<li>\example</li>
|
|
<li>\extends</li>
|
|
<li>\file</li>
|
|
<li>\fn</li>
|
|
<li>\headerfile</li>
|
|
<li>\hideinitializer</li>
|
|
<li>\htmlinclude</li>
|
|
<li>\htmlonly</li>
|
|
<li>\implements</li>
|
|
<li>\include</li>
|
|
<li>\includelineno</li>
|
|
<li>\ingroup</li>
|
|
<li>\interface</li>
|
|
<li>\internal</li>
|
|
<li>\invariant</li>
|
|
<li>\latexonly</li>
|
|
<li>\line</li>
|
|
<li>\mainpage</li>
|
|
<li>\manonly</li>
|
|
<li>\memberof</li>
|
|
<li>\msc</li>
|
|
<li>\mscfile</li>
|
|
<li>\name</li>
|
|
<li>\namespace</li>
|
|
<li>\nosubgrouping</li>
|
|
<li>\package</li>
|
|
<li>\page</li>
|
|
<li>\paragraph</li>
|
|
<li>\post</li>
|
|
<li>\pre</li>
|
|
<li>\private</li>
|
|
<li>\privatesection</li>
|
|
<li>\property</li>
|
|
<li>\protected</li>
|
|
<li>\protectedsection</li>
|
|
<li>\protocol</li>
|
|
<li>\public</li>
|
|
<li>\publicsection</li>
|
|
<li>\ref</li>
|
|
<li>\related</li>
|
|
<li>\relatedalso</li>
|
|
<li>\relates</li>
|
|
<li>\relatesalso</li>
|
|
<li>\retval</li>
|
|
<li>\rtfonly</li>
|
|
<li>\section</li>
|
|
<li>\short</li>
|
|
<li>\showinitializer</li>
|
|
<li>\skip</li>
|
|
<li>\skipline</li>
|
|
<li>\snippet</li>
|
|
<li>\struct</li>
|
|
<li>\subpage</li>
|
|
<li>\subsection</li>
|
|
<li>\subsubsection</li>
|
|
<li>\tableofcontents</li>
|
|
<li>\test</li>
|
|
<li>\typedef</li>
|
|
<li>\union</li>
|
|
<li>\until</li>
|
|
<li>\var</li>
|
|
<li>\verbinclude</li>
|
|
<li>\weakgroup</li>
|
|
<li>\xmlonly</li>
|
|
<li>\xrefitem</li>
|
|
</ul>
|
|
</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">
|
|
<b>Ignored Doxygen tags</b>
|
|
|
|
<ul style="list-style-type:none;column-count:4;">
|
|
<li>\addtogroup</li>
|
|
<li>\callergraph</li>
|
|
<li>\callgraph</li>
|
|
<li>\category</li>
|
|
<li>\class</li>
|
|
<li>\def</li>
|
|
<li>\defgroup</li>
|
|
<li>\dir</li>
|
|
<li>\enum</li>
|
|
<li>\example</li>
|
|
<li>\file</li>
|
|
<li>\fn</li>
|
|
<li>\headerfile</li>
|
|
<li>\hideinitializer</li>
|
|
<li>\interface</li>
|
|
<li>\internal</li>
|
|
<li>\mainpage</li>
|
|
<li>\name</li>
|
|
<li>\namespace</li>
|
|
<li>\nosubgrouping</li>
|
|
<li>\overload</li>
|
|
<li>\package</li>
|
|
<li>\page</li>
|
|
<li>\property</li>
|
|
<li>\protocol</li>
|
|
<li>\relates</li>
|
|
<li>\relatesalso</li>
|
|
<li>\showinitializer</li>
|
|
<li>\struct</li>
|
|
<li>\typedef</li>
|
|
<li>\union</li>
|
|
<li>\var</li>
|
|
<li>\weakgroup</li>
|
|
</ul>
|
|
</div>
|
|
|
|
|
|
<H2><a name="Doxygen_troubleshooting">18.6 Troubleshooting</a></H2>
|
|
|
|
|
|
<p>
|
|
When running SWIG with command line option <tt>-doxygen</tt>, it may happen
|
|
that SWIG will fail to parse the code, which is valid C++ code and
|
|
is parsed without problems without the option. The problem is,
|
|
that Doxygen comments are not tokens (the C/C++ compiler actually never
|
|
sees them) and that they can appear anywhere in the code. That's why it is
|
|
practically impossible to handle all corner cases with the parser.
|
|
However, these problems can usually be avoided by minor changes in the
|
|
code or comment. Known problems and solutions are shown in this section.
|
|
</p>
|
|
|
|
|
|
<p>
|
|
Recommended approach is to first run SWIG without command line
|
|
option <tt>-doxygen</tt>. When it successfully processes the code,
|
|
include the option and fix problems with Doxygen comments.
|
|
</p>
|
|
|
|
|
|
<H3><a name="troubleshooting_ifndef">18.6.1 Problem with conditional compilation</a></H3>
|
|
|
|
|
|
<p>
|
|
Inserting a conditional compilation preprocessor directive between a
|
|
Doxygen comment and a commented item may break parsing:
|
|
</p>
|
|
|
|
|
|
<div class="code"><pre>
|
|
class A {
|
|
/**
|
|
* Some func.
|
|
*/
|
|
<font color='#ff0000'>#ifndef SWIG</font>
|
|
void myfunc()
|
|
{
|
|
}
|
|
#endif
|
|
};
|
|
</pre></div>
|
|
|
|
<p>
|
|
The solution is to move the directive above the comment:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
class A {
|
|
<font color='#00d000'>#ifndef SWIG</font>
|
|
/**
|
|
* Some func.
|
|
*/
|
|
void myfunc()
|
|
{
|
|
}
|
|
#endif
|
|
};
|
|
</pre></div>
|
|
|
|
|
|
<H2><a name="Doxygen_developer_details">18.7 Developer information</a></H2>
|
|
|
|
|
|
<p>
|
|
This section contains information for developers enhancing the Doxygen translator.
|
|
</p>
|
|
|
|
<H3><a name="Doxygen_translator_design">18.7.1 Doxygen translator design</a></H3>
|
|
|
|
|
|
<p>
|
|
If this functionality is turned on, SWIG places all comments found
|
|
into the SWIG parse tree. Nodes contain an additional attribute
|
|
called <tt>doxygen</tt> when a comment is present. Individual nodes
|
|
containing Doxygen with Structural Indicators, such as <tt>@file</tt>, 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 Doxygen Translator 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">18.7.2 Debugging the Doxygen parser and translator</a></H3>
|
|
|
|
|
|
<p>
|
|
There are two handy command line options, 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">18.7.3 Tests</a></H3>
|
|
|
|
|
|
<p>
|
|
Doxygen tests have been added to the regular SWIG test-suite.
|
|
There are a number of tests beginning <tt>doxygen_</tt> in the Examples/test-suite sub-directory.
|
|
</p>
|
|
|
|
<p>
|
|
Like any other SWIG test case, the tests are included in Examples/test-suite/common.mk and can be tested with
|
|
commands like <tt>make check-test-suite</tt> or <tt>make check-python-test-suite</tt>.
|
|
To run them individually, type
|
|
<tt>make -s <testname>.cpptest</tt> in the language-specific sub-directory in
|
|
<tt>Examples/test-suite</tt> directory. For example:
|
|
</p>
|
|
|
|
<div class="shell"><pre>
|
|
Examples/test-suite/java $ make -s doxygen_parsing.cpptest
|
|
</pre></div>
|
|
|
|
<p>
|
|
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:
|
|
</p>
|
|
|
|
<div class="shell"><pre>
|
|
Examples/test-suite/java $ kdiff3 expected.txt got.txt
|
|
</pre></div>
|
|
|
|
|
|
<p>
|
|
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
|
|
environment variable defined and pointing to the JDK location.
|
|
</p>
|
|
<p>
|
|
The Java's comment parsing code (the testing part) is located in commentParser.java.
|
|
It checks the generated code. It is possible
|
|
to run this file as a stand-alone program, with <tt>java commentParser <some java package></tt>,
|
|
and it will print the list of comments found in the specified directory (in the format it has used
|
|
in the runtime tests). So, when you want to create a new Doxygen test case,
|
|
just copy an existing one and replace the actual comment content (section of entries in
|
|
form 'wantedComments.put(...)' with the output of the above command.
|
|
</p>
|
|
<p>
|
|
Runtime tests in Python are just plain string comparisons of the __doc__
|
|
properties.
|
|
</p>
|
|
|
|
<H2><a name="Doxygen_language_extension">18.8 Extending to other languages</a></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 Source/Doxygen/javadoc.cxx for a good example.
|
|
The target language module passes the Doxygen Translator the blob to translate, and receives back the 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 Doxygen Translator module can easily include a <tt>main</tt> function and thus be developed, compiled, and tested independently of SWIG.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|