jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Doxygen comments take precedence over the autodoc feature.

Browse source 
If a "docstring" feature is present it will still override a Doxygen comment.
If the "autodoc" feature is also present, the combined "autodoc" and "docstring"
will override the Doxygen comment. If no "docstring" is present then the
"autodoc" feature will not be generated when there is a Doxygen comment.

This way the "autodoc" feature can be specified and used to provide documentation
for 'missing' Doxygen comments.

Closes #1635
This commit is contained in:
William S Fulton 2022-04-06 08:08:14 +01:00
commit b35ebc81a9
7 changed files with 175 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

1
Doc/Manual/Contents.html
View file

@ -1464,6 +1464,7 @@
<li><a href="Python.html#Python_nn70">%feature("autodoc", "docstring")</a>
</ul>
<li><a href="Python.html#Python_nn71">%feature("docstring")</a>
<li><a href="Python.html#Python_doxygen_docstrings">Doxygen comments</a>
</ul>
<li><a href="Python.html#Python_nn72">Python Packages</a>
<ul>

24
Doc/Manual/Python.html
View file

@ -114,6 +114,7 @@
<li><a href="#Python_nn70">%feature("autodoc", "docstring")</a>
</ul>
<li><a href="#Python_nn71">%feature("docstring")</a>
<li><a href="#Python_doxygen_docstrings">Doxygen comments</a>
</ul>
<li><a href="#Python_nn72">Python Packages</a>
<ul>
@ -152,6 +153,7 @@
<!-- INDEX -->
<p>
This chapter describes SWIG's support of Python. SWIG is compatible
with all recent Python versions (Python 2.7 and Python &gt;= 3.2). If you
@ -5898,6 +5900,28 @@ with more than one line.
</pre>
</div>
<H3><a name="Python_doxygen_docstrings">33.10.4 Doxygen comments</a></H3>
<p>
Please see the separate <a href="Doxygen.html#Doxygen">Doxygen</a> chapter for information
on making use of C++ Doxygen comments and translating them into Python docstring comments.
</p>
<p>
Note that when generating docstrings and Doxygen comments have also been turned on,
the <a href="#Python_nn71">docstring feature</a> will take precedence over a Doxygen comment.
If the <a href="#Python_nn67">autodoc feature</a> is also turned on, then it will be
used in conjunction with the docstring feature.
However, if there is no docstring feature present and there is a Doxygen comment, then the autodoc docstring will not be generated. The Doxygen comment alone will be used.
</p>
<p>
This way, if the autodoc feature is specified globally it will fill in any missing
Doxygen documentation comments.
Doxygen comments can be overridden by using the docstring feature.
</p>
<H2><a name="Python_nn72">33.11 Python Packages</a></H2>