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

improved section 'troubleshooting', moved before 'Developr info'

Browse source
This commit is contained in:
Marko Klopcic 2019-04-23 10:25:35 +02:00
commit 4c6f33b1c9
1 changed files with 63 additions and 102 deletions
Download patch file Download diff file Expand all files Collapse all files

165
Doc/Manual/Doxygen.html
View file

@ -23,7 +23,6 @@
</ul> </ul>
<li><a href="#Doxygen_additional_options">Additional command line options</a> <li><a href="#Doxygen_additional_options">Additional command line options</a>
</ul> </ul>
<li><a href="#Doxygen_troubleshooting">Troubleshooting</a>
<li><a href="#Doxygen_to_javadoc">Doxygen to Javadoc</a> <li><a href="#Doxygen_to_javadoc">Doxygen to Javadoc</a>
<ul> <ul>
<li><a href="#Doxygen_basic_example">Basic example</a> <li><a href="#Doxygen_basic_example">Basic example</a>
@ -38,6 +37,7 @@
<li><a href="#Doxygen_python_unsupported_tags">Unsupported tags</a> <li><a href="#Doxygen_python_unsupported_tags">Unsupported tags</a>
<li><a href="#Doxygen_python_further_details">Further details</a> <li><a href="#Doxygen_python_further_details">Further details</a>
</ul> </ul>
<li><a href="#Doxygen_troubleshooting">Troubleshooting</a>
<li><a href="#Doxygen_developer_details">Developer information</a> <li><a href="#Doxygen_developer_details">Developer information</a>
<ul> <ul>
<li><a href="#Doxygen_translator_design">Doxygen translator design</a> <li><a href="#Doxygen_translator_design">Doxygen translator design</a>
@ -444,107 +444,6 @@ ALSO TO BE ADDED (Javadoc auto brief?)
</p> </p>
<H2><a name="Doxygen_troubleshooting">17.3 Troubleshooting</a></H2>
<p>
When running SWIG with command line switch <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 switch. The problem is,
that Doxygen comments are not tokens (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 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
switch <tt>-doxygen</tt>. When it successfully processes the code,
include the switch and fix problems with Doxygen comments.
</p>
<H3><a name="troubleshooting_enums">17.3.1 Enums</a></H3>
<p>
In C/C++ the comma after the last enum item is optional, but when
<tt>-doxygen</tt> switch is used the comma must <i>not</i> be present
if followed by Doxygen post-comment. For example, this snippet will
cause <tt>Error: Syntax error in input(3).</tt>:
</p>
<div class="code"><pre>
/**
* Comments after enum items.
*/
enum SomeEnum
{
SOME_ITEM_100, ///< Post comment for the first item
SOME_ITEM_200<font color='#ff0000'>,</font> ///< Comma after enum item causes error.
};
</pre></div>
<p>
Solution: remove the comma after the last enum item:
</p>
<div class="code"><pre>
/**
* Comments after enum items.
*/
enum SomeEnum
{
SOME_ITEM_100, ///< Post comment for the first item
SOME_ITEM_200 ///< OK.
};
</pre></div>
<H3><a name="troubleshooting_ifndef">17.3.2 Conditional compilation</a></H3>
<p>
Inserting of conditional compilation preprocessor directive between
Doxygen comment and commented item may also break parsing:
</p>
<div class="code"><pre>
class A {
/**
* Some func.
*/
<font color='#ff0000'>#ifndef SWIG</font>
void myfunc()
{
}
#endif
};
</pre></div>
<p>
Solution is to move the directive above 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_to_javadoc">17.3 Doxygen to Javadoc</a></H2> <H2><a name="Doxygen_to_javadoc">17.3 Doxygen to Javadoc</a></H2>
@ -1737,6 +1636,68 @@ Here is the list of these tags:
TO BE ADDED. TO BE ADDED.
</p> </p>
<H2><a name="Doxygen_troubleshooting">17.4 Troubleshooting</a></H2>
<p>
When running SWIG with command line switch <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 switch. The problem is,
that Doxygen comments are not tokens (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 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
switch <tt>-doxygen</tt>. When it successfully processes the code,
include the switch and fix problems with Doxygen comments.
</p>
<H3><a name="troubleshooting_ifndef">17.3.1 Problem with conditional compilation</a></H3>
<p>
Inserting conditional compilation preprocessor directive between
Doxygen comment and 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>
Solution is to move the directive above 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">17.5 Developer information</a></H2> <H2><a name="Doxygen_developer_details">17.5 Developer information</a></H2>