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

added section 'troubleshooting'

Browse source
This commit is contained in:
Marko Klopcic 2019-04-23 10:07:42 +02:00
commit c3a2b7524e
1 changed files with 122 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

103
Doc/Manual/Doxygen.html
View file

@ -23,6 +23,7 @@
</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>
@ -442,6 +443,108 @@ This is only applicable to Java at the moment.
ALSO TO BE ADDED (Javadoc auto brief?) 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>