Describe Doxygen-specific %features in a single place.
Put them all in a single table instead of describing doxygen:notranslate separately for Java and Python when it does the same thing for both. And while doxygen:nolinkranslate and doxygen:nostripparams are currently Java-specific, it probably won't remain this way and these features would either be made to work for Python as well or, perhaps, removed entirely.
This commit is contained in:
parent
a1d7930835
commit
a1ae3a4344
1 changed files with 38 additions and 64 deletions
|
|
@ -14,6 +14,7 @@
|
|||
<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>
|
||||
|
|
@ -201,21 +202,46 @@ assigned to anything.
|
|||
</p>
|
||||
<H3><a name="Doxygen_running_swig"></a>39.2.1 Enabling Doxygen Translation</H3>
|
||||
|
||||
|
||||
<p>
|
||||
There is a switch '-doxygen' in every module that supports converting
|
||||
documentation comments. Some comments in some target languages can be
|
||||
manually overridden by specific swig's features,
|
||||
like <i>feature:docstring</i> or <i>feature:autodoc</i>, in this cases
|
||||
Doxygen comments have lowest priority.
|
||||
</p>
|
||||
<p>
|
||||
If Doxygen parsing is switched off, then all the comments are stripped
|
||||
out in parser and all the resources used by comment parser and
|
||||
translator are freed.
|
||||
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_additional_options"></a>39.2.2 Additional Command Line Options</H3>
|
||||
<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: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>
|
||||
|
|
@ -330,12 +356,6 @@ you don't want such behaviour, you could turn this off by using
|
|||
'doxygen:nolinktranslate' feature. Also all '\param' and '\tparam'
|
||||
commands are stripped out, if specified parameter is not present in
|
||||
function. Use 'doxygen:nostripparams' to avoid.
|
||||
<br>
|
||||
If you intend to use resulting proxy files with Doxygen docs
|
||||
generator, rather than Javadoc, you may want to turn off translator
|
||||
completely (doxygen:notranslate feature). Then SWIG will just copy
|
||||
the comments to the proxy file and reformat them if needed, but all
|
||||
the comment content will be left as is.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
@ -346,33 +366,6 @@ directives</a>):
|
|||
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
<table>
|
||||
<tr>
|
||||
<td>doxygen:notranslate</td>
|
||||
<td>
|
||||
Turn off the whole Doxygen translator.
|
||||
The Doxygen comment will be attached to the right node,
|
||||
but all the commands and text will be left as-is
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>doxygen:nolinkranslate</td>
|
||||
<td>Turn off automatic link-objects translation</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>doxygen:nostripparams</td>
|
||||
<td>
|
||||
Turn off stripping of @param and @tparam
|
||||
Doxygen commands if such parameter is not found
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</pre></div>
|
||||
|
||||
|
||||
<H3><a name="Doxygen_javadoc_tags"></a>39.3.2 Javadoc Tags</H3>
|
||||
|
||||
|
||||
|
|
@ -1036,25 +1029,6 @@ docs</a>), you may want to use some tool like doxypy
|
|||
to do the work.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Pydoc translator features summary (see <a href="Customization.html#Customization_features">%feature directives</a>):
|
||||
<br>
|
||||
|
||||
</p>
|
||||
|
||||
<div class="shell"><pre>
|
||||
<table>
|
||||
<tr>
|
||||
<td>doxygen:notranslate</td>
|
||||
<td>
|
||||
Turn off the whole Doxygen translator.
|
||||
The Doxygen comment will be attached to the right node,
|
||||
but all the commands and text will be left as-is
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</pre></div>
|
||||
|
||||
<H3><a name="Doxygen_pydoc_tags"></a>39.4.2 Pydoc translator</H3>
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue