mirror of https://github.com/swig/swig
Add chapter about C# doxygen documentation
This commit is contained in:
frederic.bon
parent
b006dd940a
commit
f638291e60
|
|
@ -37,6 +37,13 @@
|
|||
<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_to_csharpXml">Doxygen to CSharp XML</a>
|
||||
<ul>
|
||||
<li><a href="#Doxygen_csharp_basic_example">Basic example</a>
|
||||
<li><a href="#Doxygen_csharp_tags">CSharp XML tags</a>
|
||||
<li><a href="#Doxygen_csharp_unsupported_tags">Unsupported tags</a>
|
||||
<li><a href="#Doxygen_csharp_further_details">Further details</a>
|
||||
</ul>
|
||||
<li><a href="#Doxygen_troubleshooting">Troubleshooting</a>
|
||||
<ul>
|
||||
<li><a href="#troubleshooting_ifndef">Problem with conditional compilation</a>
|
||||
|
|
@ -1550,7 +1557,570 @@ Here is the list of these tags:
|
|||
TO BE ADDED.
|
||||
</p>
|
||||
|
||||
<H2><a name="Doxygen_troubleshooting">18.5 Troubleshooting</a></H2>
|
||||
|
||||
<H2><a name="Doxygen_to_csharpXml">18.5 Doxygen to XML Csharp documentation</a></H2>
|
||||
|
||||
|
||||
<p>
|
||||
If translation is enabled, XML formatted comments should be
|
||||
automatically placed in the correct locations in the resulting module
|
||||
and proxy files.
|
||||
</p>
|
||||
|
||||
<H3><a name="Doxygen_csharp_basic_example">18.5.1 Basic example</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
Here is an example segment from an included header file
|
||||
</p>
|
||||
<div class="code"><pre>
|
||||
/*! This is describing class Shape
|
||||
\author Bob
|
||||
*/
|
||||
|
||||
class Shape {
|
||||
public:
|
||||
Shape() {
|
||||
nshapes++;
|
||||
}
|
||||
virtual ~Shape() {
|
||||
nshapes--;
|
||||
};
|
||||
/** Important Variables x*/
|
||||
double x;
|
||||
/** Important Variables y*/
|
||||
double y;
|
||||
/** Moves the Shape
|
||||
* @param dx delta on x
|
||||
* @param dy delta on y */
|
||||
void move(double dx, double dy);
|
||||
/** \return the area */
|
||||
virtual double area(void) = 0;
|
||||
/** \return the perimeter */
|
||||
virtual double perimeter(void) = 0;
|
||||
static int nshapes;
|
||||
};
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Simply running SWIG should result in the following code being present in Shapes.cs
|
||||
</p>
|
||||
|
||||
<div class="targetlang"><pre>
|
||||
|
||||
/// <summary>This is describing class Shape
|
||||
/// Author: Bob
|
||||
/// </summary>
|
||||
public class Shape {
|
||||
|
||||
...
|
||||
/// Important Variables x
|
||||
public double x {
|
||||
set {
|
||||
ShapesCsPINVOKE.Shape_x_set(swigCPtr, value);
|
||||
}
|
||||
get {
|
||||
double ret = ShapesCsPINVOKE.Shape_x_get(swigCPtr);
|
||||
return ret;
|
||||
}
|
||||
}
|
||||
|
||||
/// Important Variables y
|
||||
public double y {
|
||||
set {
|
||||
ShapesCsPINVOKE.Shape_y_set(swigCPtr, value);
|
||||
}
|
||||
get {
|
||||
double ret = ShapesCsPINVOKE.Shape_y_get(swigCPtr);
|
||||
return ret;
|
||||
}
|
||||
}
|
||||
|
||||
/// Moves the Shape
|
||||
/// <param name="dx"> delta on x</param>
|
||||
/// <param name="dy"> delta on y</param>
|
||||
public void move(double dx, double dy) {
|
||||
ShapesCsPINVOKE.Shape_move(swigCPtr, dx, dy);
|
||||
}
|
||||
|
||||
/// <returns>the area</returns>
|
||||
public virtual double area() {
|
||||
double ret = ShapesCsPINVOKE.Shape_area(swigCPtr);
|
||||
return ret;
|
||||
}
|
||||
|
||||
/// <returns>the perimeter</returns>
|
||||
public virtual double perimeter() {
|
||||
double ret = ShapesCsPINVOKE.Shape_perimeter(swigCPtr);
|
||||
return ret;
|
||||
}
|
||||
|
||||
public static int nshapes {
|
||||
set {
|
||||
ShapesCsPINVOKE.Shape_nshapes_set(value);
|
||||
}
|
||||
get {
|
||||
int ret = ShapesCsPINVOKE.Shape_nshapes_get();
|
||||
return ret;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The code CSharp-wise should be identical to what would have been
|
||||
generated without the doxygen functionality enabled. When the Doxygen Translator
|
||||
module encounters a comment that contains nothing useful or a doxygen comment that it cannot
|
||||
parse, it will not affect the functionality of the SWIG generated
|
||||
code.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The translator will handle most of the tags conversions (see the
|
||||
table below). It will also automatically translate link-objects
|
||||
params, in <seealso> tags .
|
||||
Also all '\param' and '\tparam' commands are stripped out, if the specified parameter is not present in
|
||||
the function. Use 'doxygen:nostripparams' to avoid.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
CSharp translator features summary
|
||||
(see <a href="Customization.html#Customization_features">%feature
|
||||
directives</a>):
|
||||
</p>
|
||||
|
||||
<H3><a name="Doxygen_csharp_tags">18.5.2 CSharp tags</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
Here is the list of all Doxygen tags and the description of how they are translated to CSharp XML
|
||||
</p>
|
||||
<div class="diagram">
|
||||
<table border="0" summary="CSharp XML Doxygen tags">
|
||||
<tr>
|
||||
<th align="left">Doxygen tags</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\a</td>
|
||||
<td>wrapped with '*' markdown character</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\arg</td>
|
||||
<td>prefixed with '*' markdown character</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\author</td>
|
||||
<td>Made simple text with prefix 'Author:'</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\authors</td>
|
||||
<td>Made simple text with prefix 'Author:'</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\b</td>
|
||||
<td>wrapped with '**' markdown character</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\c</td>
|
||||
<td>wrapped with `` markdown character</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\cite</td>
|
||||
<td>started with ' markdown character</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\code</td>
|
||||
<td>wrapped in <code> tag </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\code{<ext>}</td>
|
||||
<td>wrapped in <code> tag. code language extension is ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\cond</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\copyright</td>
|
||||
<td>wrapped in <remark> tag</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\deprecated</td>
|
||||
<td>Made simple text with prefix 'Deprecated:' </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\e</td>
|
||||
<td>prefixed with '*' markdown character</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\else</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\elseif</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\em</td>
|
||||
<td>prefixed with '*' markdown character</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\endcode</td>
|
||||
<td>wrapped in <code> tag. code language extension is ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\endcond</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\endif</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\endlink</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\endverbatim</td>
|
||||
<td>see note for \verbatim</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\exception</td>
|
||||
<td>translated to <exception> section</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\f$, \f[, \f], \f{, \f}</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\if</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\ifnot</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\image</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\li</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\link</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\n</td>
|
||||
<td>replaced with newline char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\note</td>
|
||||
<td>Content copied</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\overload</td>
|
||||
<td>Ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\p</td>
|
||||
<td>wrapped with `` markdown characters</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\par</td>
|
||||
<td>Made simple text with prefix "Title:"</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\param</td>
|
||||
<td>translated to <param> xml section</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\param[<dir>]</td>
|
||||
<td>translated to <param> xml section; parameter direction ('in'; 'out'; or 'in,out') is ignored</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\remark</td>
|
||||
<td>Made simple text with prefix "remarks:"</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\remarks</td>
|
||||
<td>Made simple text with prefix "remarks:"</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\result</td>
|
||||
<td>translated to <return> xml section</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\return</td>
|
||||
<td>translated to <return> xml section</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\returns</td>
|
||||
<td>translated to <return> xml section</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\sa</td>
|
||||
<td>translated to <seealso> xml section</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\see</td>
|
||||
<td>translated to <seealso> xml section</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\since</td>
|
||||
<td>Content copied</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\throw</td>
|
||||
<td>translated to <exception></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\throws</td>
|
||||
<td>translated to <exception>>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\todo</td>
|
||||
<td>Prefixed with 'TODO:'</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\tparam</td>
|
||||
<td>translated to <exception> xml section</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\verbatim</td>
|
||||
<td>copied without any processing</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\version</td>
|
||||
<td>Made simple text with prefix 'Version:"</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\warning</td>
|
||||
<td>Made simple text with prefix 'remarks:"</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\$</td>
|
||||
<td>prints $ char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\@</td>
|
||||
<td>prints @ char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\\</td>
|
||||
<td>prints \ char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\&</td>
|
||||
<td>prints & char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\~</td>
|
||||
<td>prints ~ char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\<</td>
|
||||
<td>prints < char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\></td>
|
||||
<td>prints > char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\#</td>
|
||||
<td>prints # char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\%</td>
|
||||
<td>prints % char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\"</td>
|
||||
<td>prints " char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\.</td>
|
||||
<td>prints . char</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>\::</td>
|
||||
<td>prints ::</td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<H3><a name="Doxygen_csharp_unsupported_tags">18.5.3 Unsupported tags</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
Doxygen has a wealth of tags such as @latexonly that have no
|
||||
equivalent in CSharp XML (all supported tags are listed in
|
||||
<a href="https://www.doxygen.nl/manual/xmlcmds.html">XML documentation</a>).
|
||||
As a result several tags have no
|
||||
translation or particular use, such as some linking and section tags.
|
||||
These are suppressed with their content just printed out (if the tag has any
|
||||
sense, typically text content).
|
||||
Here is the list of these tags:
|
||||
</p>
|
||||
|
||||
<div class="diagram">
|
||||
<b>Unsupported Doxygen tags</b>
|
||||
|
||||
<ul style="list-style-type:none;column-count:4;">
|
||||
<li>\addindex</li>
|
||||
<li>\addtogroup</li>
|
||||
<li>\anchor</li>
|
||||
<li>\attention</li>
|
||||
<li>\brief</li>
|
||||
<li>\bug</li>
|
||||
<li>\callergraph</li>
|
||||
<li>\callgraph</li>
|
||||
<li>\category</li>
|
||||
<li>\class</li>
|
||||
<li>\copybrief</li>
|
||||
<li>\copydetails</li>
|
||||
<li>\copydoc</li>
|
||||
<li>\date</li>
|
||||
<li>\def</li>
|
||||
<li>\defgroup</li>
|
||||
<li>\details</li>
|
||||
<li>\dir</li>
|
||||
<li>\dontinclude</li>
|
||||
<li>\dot</li>
|
||||
<li>\dotfile</li>
|
||||
<li>\enddot</li>
|
||||
<li>\endhtmlonly</li>
|
||||
<li>\endinternal</li>
|
||||
<li>\endlatexonly</li>
|
||||
<li>\endmanonly</li>
|
||||
<li>\endmsc</li>
|
||||
<li>\endrtfonly</li>
|
||||
<li>\endxmlonly</li>
|
||||
<li>\enum</li>
|
||||
<li>\example</li>
|
||||
<li>\extends</li>
|
||||
<li>\file</li>
|
||||
<li>\fn</li>
|
||||
<li>\headerfile</li>
|
||||
<li>\hideinitializer</li>
|
||||
<li>\htmlinclude</li>
|
||||
<li>\htmlonly</li>
|
||||
<li>\implements</li>
|
||||
<li>\include</li>
|
||||
<li>\includelineno</li>
|
||||
<li>\ingroup</li>
|
||||
<li>\interface</li>
|
||||
<li>\internal</li>
|
||||
<li>\invariant</li>
|
||||
<li>\latexonly</li>
|
||||
<li>\line</li>
|
||||
<li>\mainpage</li>
|
||||
<li>\manonly</li>
|
||||
<li>\memberof</li>
|
||||
<li>\msc</li>
|
||||
<li>\mscfile</li>
|
||||
<li>\name</li>
|
||||
<li>\namespace</li>
|
||||
<li>\nosubgrouping</li>
|
||||
<li>\package</li>
|
||||
<li>\page</li>
|
||||
<li>\paragraph</li>
|
||||
<li>\post</li>
|
||||
<li>\pre</li>
|
||||
<li>\private</li>
|
||||
<li>\privatesection</li>
|
||||
<li>\property</li>
|
||||
<li>\protected</li>
|
||||
<li>\protectedsection</li>
|
||||
<li>\protocol</li>
|
||||
<li>\public</li>
|
||||
<li>\publicsection</li>
|
||||
<li>\ref</li>
|
||||
<li>\related</li>
|
||||
<li>\relatedalso</li>
|
||||
<li>\relates</li>
|
||||
<li>\relatesalso</li>
|
||||
<li>\retval</li>
|
||||
<li>\rtfonly</li>
|
||||
<li>\section</li>
|
||||
<li>\short</li>
|
||||
<li>\showinitializer</li>
|
||||
<li>\skip</li>
|
||||
<li>\skipline</li>
|
||||
<li>\snippet</li>
|
||||
<li>\struct</li>
|
||||
<li>\subpage</li>
|
||||
<li>\subsection</li>
|
||||
<li>\subsubsection</li>
|
||||
<li>\tableofcontents</li>
|
||||
<li>\test</li>
|
||||
<li>\typedef</li>
|
||||
<li>\union</li>
|
||||
<li>\until</li>
|
||||
<li>\var</li>
|
||||
<li>\verbinclude</li>
|
||||
<li>\weakgroup</li>
|
||||
<li>\xmlonly</li>
|
||||
<li>\xrefitem</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
|
||||
If one of the following Doxygen tags appears as the first tag in a
|
||||
comment, the whole comment block is ignored:
|
||||
<!-- see parser.y, function isStructuralDoxygen() -->
|
||||
|
||||
</p>
|
||||
|
||||
<div class="diagram">
|
||||
<b>Ignored Doxygen tags</b>
|
||||
|
||||
<ul style="list-style-type:none;column-count:4;">
|
||||
<li>\addtogroup</li>
|
||||
<li>\callergraph</li>
|
||||
<li>\callgraph</li>
|
||||
<li>\category</li>
|
||||
<li>\class</li>
|
||||
<li>\def</li>
|
||||
<li>\defgroup</li>
|
||||
<li>\dir</li>
|
||||
<li>\enum</li>
|
||||
<li>\example</li>
|
||||
<li>\file</li>
|
||||
<li>\fn</li>
|
||||
<li>\headerfile</li>
|
||||
<li>\hideinitializer</li>
|
||||
<li>\interface</li>
|
||||
<li>\internal</li>
|
||||
<li>\mainpage</li>
|
||||
<li>\name</li>
|
||||
<li>\namespace</li>
|
||||
<li>\nosubgrouping</li>
|
||||
<li>\overload</li>
|
||||
<li>\package</li>
|
||||
<li>\page</li>
|
||||
<li>\property</li>
|
||||
<li>\protocol</li>
|
||||
<li>\relates</li>
|
||||
<li>\relatesalso</li>
|
||||
<li>\showinitializer</li>
|
||||
<li>\struct</li>
|
||||
<li>\typedef</li>
|
||||
<li>\union</li>
|
||||
<li>\var</li>
|
||||
<li>\weakgroup</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<H3><a name="Doxygen_csharp_further_details">18.5.4 Further details</a></H3>
|
||||
|
||||
|
||||
|
||||
<H2><a name="Doxygen_troubleshooting">18.6 Troubleshooting</a></H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -1572,7 +2142,7 @@ include the option and fix problems with Doxygen comments.
|
|||
</p>
|
||||
|
||||
|
||||
<H3><a name="troubleshooting_ifndef">18.5.1 Problem with conditional compilation</a></H3>
|
||||
<H3><a name="troubleshooting_ifndef">18.6.1 Problem with conditional compilation</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -1612,14 +2182,14 @@ class A {
|
|||
</pre></div>
|
||||
|
||||
|
||||
<H2><a name="Doxygen_developer_details">18.6 Developer information</a></H2>
|
||||
<H2><a name="Doxygen_developer_details">18.7 Developer information</a></H2>
|
||||
|
||||
|
||||
<p>
|
||||
This section contains information for developers enhancing the Doxygen translator.
|
||||
</p>
|
||||
|
||||
<H3><a name="Doxygen_translator_design">18.6.1 Doxygen translator design</a></H3>
|
||||
<H3><a name="Doxygen_translator_design">18.7.1 Doxygen translator design</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -1645,7 +2215,7 @@ class for translation into the target documentation language. For
|
|||
example, <tt>JavaDocConverter</tt> is the Javadoc module class.
|
||||
</p>
|
||||
|
||||
<H3><a name="Doxygen_debugging_commands">18.6.2 Debugging the Doxygen parser and translator</a></H3>
|
||||
<H3><a name="Doxygen_debugging_commands">18.7.2 Debugging the Doxygen parser and translator</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -1658,7 +2228,7 @@ detailed debug information printing.
|
|||
-debug-doxygen-translator - Display Doxygen translator module debugging information
|
||||
</pre></div>
|
||||
|
||||
<H3><a name="Doxygen_tests">18.6.3 Tests</a></H3>
|
||||
<H3><a name="Doxygen_tests">18.7.3 Tests</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -1690,7 +2260,7 @@ tool, for example:
|
|||
Examples/test-suite/java $ kdiff3 expected.txt got.txt
|
||||
</pre></div>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
Runtime tests in Java are implemented using Javadoc doclets. To make that work, you
|
||||
should have tools.jar from the JDK in your classpath. Or you should have JAVA_HOME
|
||||
|
|
@ -1710,7 +2280,7 @@ Runtime tests in Python are just plain string comparisons of the __doc__
|
|||
properties.
|
||||
</p>
|
||||
|
||||
<H2><a name="Doxygen_language_extension">18.7 Extending to other languages</a></H2>
|
||||
<H2><a name="Doxygen_language_extension">18.8 Extending to other languages</a></H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
|
|||
Loading…
Reference in New Issue