improved section 'troubleshooting', moved before 'Developr info'
This commit is contained in:
Marko Klopcic
parent
c3a2b7524e
commit
4c6f33b1c9
1 changed files with 63 additions and 102 deletions
|
|
@ -23,7 +23,6 @@
|
|||
</ul>
|
||||
<li><a href="#Doxygen_additional_options">Additional command line options</a>
|
||||
</ul>
|
||||
<li><a href="#Doxygen_troubleshooting">Troubleshooting</a>
|
||||
<li><a href="#Doxygen_to_javadoc">Doxygen to Javadoc</a>
|
||||
<ul>
|
||||
<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_further_details">Further details</a>
|
||||
</ul>
|
||||
<li><a href="#Doxygen_troubleshooting">Troubleshooting</a>
|
||||
<li><a href="#Doxygen_developer_details">Developer information</a>
|
||||
<ul>
|
||||
<li><a href="#Doxygen_translator_design">Doxygen translator design</a>
|
||||
|
|
@ -444,107 +444,6 @@ ALSO TO BE ADDED (Javadoc auto brief?)
|
|||
</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>
|
||||
|
||||
|
||||
|
|
@ -1737,6 +1636,68 @@ Here is the list of these tags:
|
|||
TO BE ADDED.
|
||||
</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>
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue