"Fossies" - the Fresh Open Source Software Archive 
Member "swig-4.1.1/Doc/Manual/Doxygen.html" (30 Nov 2022, 42912 Bytes) of package /linux/misc/swig-4.1.1.tar.gz:
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <title>SWIG and Doxygen Translation</title>
5 <link rel="stylesheet" type="text/css" href="style.css">
6 </head>
7 <body bgcolor="#FFFFFF">
8 <H1><a name="Doxygen">18 SWIG and Doxygen Translation</a></H1>
9 <!-- INDEX -->
10 <div class="sectiontoc">
11 <ul>
12 <li><a href="#Doxygen_translation_overview">Doxygen translation overview</a>
13 <li><a href="#Doxygen_file_preparation">Preparations</a>
14 <ul>
15 <li><a href="#Doxygen_running_swig">Enabling Doxygen translation</a>
16 <li><a href="#Doxygen_features">Doxygen-specific %feature directives</a>
17 <ul>
18 <li><a href="#Doxygen_notranslate">doxygen:notranslate</a>
19 <li><a href="#Doxygen_alias">doxygen:alias:<command-name></a>
20 <li><a href="#Doxygen_ignore">doxygen:ignore:<command-name></a>
21 <li><a href="#Doxygen_nolinktranslate">doxygen:nolinktranslate</a>
22 <li><a href="#Doxygen_nostripparams">doxygen:nostripparams</a>
23 </ul>
24 <li><a href="#Doxygen_additional_options">Additional command line options</a>
25 </ul>
26 <li><a href="#Doxygen_to_javadoc">Doxygen to Javadoc</a>
27 <ul>
28 <li><a href="#Doxygen_basic_example">Basic example</a>
29 <li><a href="#Doxygen_javadoc_tags">Javadoc tags</a>
30 <li><a href="#Doxygen_unsupported_tags">Unsupported tags</a>
31 <li><a href="#Doxygen_further_details">Further details</a>
32 </ul>
33 <li><a href="#Doxygen_to_pydoc">Doxygen to Pydoc</a>
34 <ul>
35 <li><a href="#Doxygen_python_basic_example">Basic example</a>
36 <li><a href="#Doxygen_pydoc_tags">Pydoc translator</a>
37 <li><a href="#Doxygen_python_unsupported_tags">Unsupported tags</a>
38 <li><a href="#Doxygen_python_further_details">Further details</a>
39 </ul>
40 <li><a href="#Doxygen_troubleshooting">Troubleshooting</a>
41 <ul>
42 <li><a href="#troubleshooting_ifndef">Problem with conditional compilation</a>
43 </ul>
44 <li><a href="#Doxygen_developer_details">Developer information</a>
45 <ul>
46 <li><a href="#Doxygen_translator_design">Doxygen translator design</a>
47 <li><a href="#Doxygen_debugging_commands">Debugging the Doxygen parser and translator</a>
48 <li><a href="#Doxygen_tests">Tests</a>
49 </ul>
50 <li><a href="#Doxygen_language_extension">Extending to other languages</a>
51 </ul>
52 </div>
53 <!-- INDEX -->
54
55
56
57 <p>
58 This chapter describes SWIG's support for translating Doxygen comments
59 found in interface and header files into a target language's normal
60 documentation language. Currently only Javadoc and Pydoc is
61 supported.
62 </p>
63
64 <H2><a name="Doxygen_translation_overview">18.1 Doxygen translation overview</a></H2>
65
66
67 <p>
68 The Doxygen Translation module of SWIG adds an extra layer of
69 functionality to SWIG, allowing automated translation of <a href=
70 "https://www.doxygen.nl/manual/">Doxygen</a> formatted comments
71 from input files into a documentation language more suited for the
72 target language. Currently this module only translates into Javadoc
73 and Pydoc for the SWIG Java and Python modules.
74 Other extensions could be added at a later date.
75 The Doxygen Translation module originally started as
76 a <a href="https://developers.google.com/open-source/gsoc/2008/">Google Summer of
77 Code</a> proposal from Summer 2008.
78 </p>
79
80 <H2><a name="Doxygen_file_preparation">18.2 Preparations</a></H2>
81
82
83 <p>
84 To make use of the comment translation system, your documentation
85 comments must be in properly formatted <a href=
86 "https://www.doxygen.nl/manual/">Doxygen.</a> Doxygen comments can be
87 present in your main SWIG interface file or any header file that it
88 imports. You are advised to be validate that your comments compile
89 properly with Doxygen before you try to translate them. Doxygen
90 itself is a more comprehensive tool and can provide you better feedback for
91 correcting any syntax errors that may be present. Please look at
92 Doxygen's <a href=
93 "https://www.doxygen.nl/manual/docblocks.html"> Documenting the
94 code</a> for the full comment format specifications. However, SWIG's
95 Doxygen parser will still report many errors and warnings found
96 in comments (like unterminated strings or missing ending tags).
97 </p>
98
99 <p>
100 Currently, the whole subset of Doxygen comment styles is supported
101 (See <a href="https://www.doxygen.nl/manual/docblocks.html">
102 Documenting the code</a>). Here they are:
103 </p>
104
105 <div class="code"><pre>
106 /**
107 * Javadoc style comment, multiline
108 */
109 /*!
110 * QT-style comment, multiline
111 */
112 /**
113 Any of the above, but without intermediate *'s
114 */
115 /// Single-line comment
116 //! Another single-line comment
117 </pre></div>
118
119 <p>
120 Also any of the above with '<tt><</tt>' added after comment-starting symbol,
121 like <tt>/**<, /*!<, ///<, </tt> or <tt> //!<</tt> will be
122 treated as a post-comment and will be assigned to the code before the
123 comment.
124
125 Any number of '<tt>*</tt>' or '<tt>/</tt>' within a Doxygen comment is
126 considered to be a separator and is not included in the final comment,
127 so you may safely use comments like <tt>/*********/</tt>
128 or <tt>//////////</tt>.
129 </p>
130
131 <p>
132 Please note, as SWIG parses the input file by itself with strict grammar,
133 there is only a limited support for various cases of comment placement
134 in the file.
135 </p>
136 <p>
137 Comments can be placed before C/C++ expressions on separate lines:
138 </p>
139
140 <div class="code"><pre>
141 /**
142 * Some comment
143 */
144 void someOtherFunction();
145 /**
146 * Some comment
147 */
148 void someFunction();
149
150 class Shape {
151 /*
152 * Calculate the area in cm^2
153 */
154 int getArea();
155 }
156 </pre></div>
157
158 <p>
159 After C/C++ expressions at the end of the line:
160 </p>
161
162 <div class="code"><pre>
163 int someVariable = 9; ///< This is a var holding magic number 9
164 void doNothing(); ///< This does nothing, nop
165 </pre></div>
166
167 <p>
168 and in some special cases, like function parameter comments:
169 </p>
170
171 <div class="code"><pre>
172 void someFunction(
173 int a ///< Some parameter
174 );
175 </pre></div>
176
177 <p>
178 or enum element comments:
179 </p>
180
181 <div class="code"><pre>
182 enum E_NUMBERS
183 {
184 EN_ZERO, ///< The first enum item, gets zero as its value
185 EN_ONE, ///< The second, EN_ONE=1
186 EN_THREE
187 };
188 </pre></div>
189
190 <p>
191 Currently only comments directly before or after the code items
192 are supported. Doxygen also supports comments containing structural commands,
193 where the comments for a code item are not put directly before or after the code item.
194 These structural commands are stripped out by SWIG and are not assigned to anything.
195 </p>
196
197 <H3><a name="Doxygen_running_swig">18.2.1 Enabling Doxygen translation</a></H3>
198
199
200 <p>
201 Doxygen comments translation is disabled by default and needs to be explicitly
202 enabled using the command line <tt>-doxygen</tt> option for the languages that
203 do support it (currently Java and Python).
204 </p>
205
206 <H3><a name="Doxygen_features">18.2.2 Doxygen-specific %feature directives</a></H3>
207
208
209 <p>
210 Translation of Doxygen comments is influenced by the following <a
211 href="Customization.html#Customization_features">%feature directives</a>:
212 </p>
213
214 <H4><a name="Doxygen_notranslate">18.2.2.1 doxygen:notranslate</a></H4>
215
216
217 <p>
218 Turns off translation of Doxygen comments to the target language syntax: the
219 original comment will be copied to the output unchanged. This is useful if you
220 want to use Doxygen itself to generate documentation for the target language
221 instead of the corresponding language tool (<tt>javadoc</tt>, <tt>sphinx</tt>,
222 ...).
223 </p>
224
225
226 <H4><a name="Doxygen_alias">18.2.2.2 doxygen:alias:<command-name></a></H4>
227
228
229 <p>
230 Specify an alias for a Doxygen command with the given name. This can be useful
231 for custom Doxygen commands which can be defined using <tt>ALIASES</tt> option
232 for Doxygen itself but which are unknown to SWIG. <tt>"command-name"</tt> is the
233 name of the command in the Doxyfile, e.g. if it contains
234 </p>
235
236 <div class="code"><pre>
237 ALIASES = "sideeffect=\par Side Effects:\n"
238 </pre></div>
239
240 <p>
241 Then you could also specify the same expansion for SWIG with:
242 </p>
243
244 <div class="code"><pre>
245 %feature("doxygen:alias:sideeffect") "\par Side Effects:\n"
246 </pre></div>
247
248 <p>
249 Please note that command arguments are not currently supported with this
250 feature.
251 </p>
252
253 <p>
254 Notice that it is perfectly possible and potentially useful to define the alias
255 expansion differently depending on the target language, e.g. with
256 </p>
257
258 <div class="code"><pre>
259 #ifdef SWIGJAVA
260 %feature("doxygen:alias:not_for_java") "This functionality is not available for Java"
261 #else
262 %feature("doxygen:alias:not_for_java") ""
263 #endif
264 </pre></div>
265
266 <p>
267 you could use <tt>@not_for_java</tt> in the documentation comments of all
268 functions which can't, for whatever reason, be currently exposed in Java
269 wrappers of the C++ API.
270 </p>
271
272
273 <H4><a name="Doxygen_ignore">18.2.2.3 doxygen:ignore:<command-name></a></H4>
274
275
276 <p>
277 This feature makes it possible to just ignore an unknown Doxygen command, instead of
278 replacing it with the predefined text that <tt>doxygen:alias</tt> does.
279 For example, you could use
280 </p>
281
282 <div class="code"><pre>
283 %feature("doxygen:ignore:transferfull") Fantastic();
284 /**
285 A fantastic function.
286
287 @transferfull Command ignored, but anything here is still included.
288 */
289 int * Fantastic();
290 </pre></div>
291
292 <p>
293 if you use a custom Doxygen <tt>transferfull</tt> command to indicate that the
294 return value ownership is transferred to the caller, as this information doesn't
295 make much sense for the other languages without explicit ownership management.
296 </p>
297
298 <p>
299 Doxygen syntax is rather rich and, in addition to simple commands such as
300 <tt>@transferfull</tt>, it is also possible to define commands with arguments.
301 As explained in <a href="https://www.doxygen.nl/manual/commands.html">Doxygen documentation</a>,
302 the arguments can have a range of a single word, everything until the end of
303 line or everything until the end of the next paragraph. Currently, only the "end
304 of line" case is supported using the <tt>range="line"</tt> argument of the
305 feature directive:
306 </p>
307
308 <div class="code"><pre>
309 // Ignore occurrences of
310 //
311 // @compileroptions Some special C++ compiler options.
312 //
313 // in Doxygen comments as C++ options are not interesting for the target language
314 // developers.
315 %feature("doxygen:ignore:compileroptions", range="line") Amazing();
316
317 /**
318 An amazing function.
319
320 @compileroptions This function must be compiled with /EHa when using MSVC.
321 */
322 void Amazing();
323
324 </pre></div>
325
326 <p>
327 In addition, it is also possible to have custom pairs of begin/end tags,
328 similarly to the standard Doxygen <tt>@code/@endcode</tt>, for example. Such
329 tags can also be ignored using the special value of <tt>range</tt> starting with
330 <tt>end</tt> to indicate that the range is an interval, for example:
331 </p>
332
333 <div class="code"><pre>
334 %feature("doxygen:ignore:forcpponly", range="end"); // same as "end:endforcpponly"
335 /**
336 An incredible function.
337
338 @forcpponly
339 This is C++-specific.
340 @endforcpponly
341 */
342 void Incredible();
343 </pre></div>
344
345 <p>
346 would ignore everything between <tt>@forcpponly</tt> and <tt>@endforcpponly</tt>
347 commands in Doxygen comments. By default, the name of the end command is the
348 same as of the start one with "end" prefix, following Doxygen conventions, but
349 this can be overridden by providing the end command name after the colon.
350 </p>
351 <p>
352 This example shows how custom tags can be used to bracket anything specific to
353 C++ and prevent it from appearing in the target language documentation.
354 Conversely, another pair of custom tags could be used to put target language
355 specific information in the C++ comments. In this case, only the custom tags
356 themselves should be ignored, but their contents should be parsed as usual and
357 <tt>contents="parse"</tt> can be used for this:
358 </p>
359
360 <div class="code"><pre>
361 %feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse");
362 /**
363 A splendid function.
364
365 @beginPythonOnly
366 This is specific to @b Python.
367 @endPythonOnly
368 */
369 void Splendid();
370
371 </pre></div>
372
373 <p>
374 Putting everything together, if these directives are in effect:
375 </p>
376
377 <div class="code"><pre>
378 %feature("doxygen:ignore:transferfull");
379 %feature("doxygen:ignore:compileroptions", range="line");
380 %feature("doxygen:ignore:forcpponly", range="end");
381 %feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse");
382 </pre></div>
383
384 <p>
385 then the following C++ Doxygen comment:
386 </p>
387
388 <div class="code"><pre>
389 /**
390 A contrived example of ignoring too many commands in one comment.
391
392 @forcpponly
393 This is C++-specific.
394 @endforcpponly
395
396 @beginPythonOnly
397 This is specific to @b Python.
398 @endPythonOnly
399
400 @transferfull Command ignored, but anything here is still included.
401
402 @compileroptions This function must be compiled with /EHa when using MSVC.
403 */
404 int * Contrived();
405 </pre></div>
406
407 <p>
408 would be translated to this comment in Python:
409 </p>
410
411 <div class="code"><pre>
412 def func():
413 r"""
414 A contrived example of ignoring too many commands in one comment.
415
416 This is specific to **Python**.
417
418 Command ignored, but anything here is still included.
419 """
420 ...
421 </pre></div>
422
423
424 <H4><a name="Doxygen_nolinktranslate">18.2.2.4 doxygen:nolinktranslate</a></H4>
425
426
427 <p>
428 Turn off automatic link-objects translation.
429 This is only applicable to Java at the moment.
430 </p>
431
432
433 <H4><a name="Doxygen_nostripparams">18.2.2.5 doxygen:nostripparams</a></H4>
434
435
436 <p>
437 Turn off stripping of <tt>@param</tt> and <tt>@tparam</tt>
438 Doxygen commands if the parameter is not found in the function signature.
439 This is only applicable to Java at the moment.
440 </p>
441
442
443 <H3><a name="Doxygen_additional_options">18.2.3 Additional command line options</a></H3>
444
445
446 <p>
447 ALSO TO BE ADDED (Javadoc auto brief?)
448 </p>
449
450 <H2><a name="Doxygen_to_javadoc">18.3 Doxygen to Javadoc</a></H2>
451
452
453 <p>
454 If translation is enabled, Javadoc formatted comments should be
455 automatically placed in the correct locations in the resulting module
456 and proxy files.
457 </p>
458
459 <H3><a name="Doxygen_basic_example">18.3.1 Basic example</a></H3>
460
461
462 <p>
463 Here is an example segment from an included header file
464 </p>
465 <div class="code"><pre>
466 /*! This is describing class Shape
467 \author Bob
468 */
469
470 class Shape {
471 public:
472 Shape() {
473 nshapes++;
474 }
475 virtual ~Shape() {
476 nshapes--;
477 };
478 double x, y; /*!< Important Variables */
479 void move(double dx, double dy); /*!< Moves the Shape */
480 virtual double area(void) = 0; /*!< \return the area */
481 virtual double perimeter(void) = 0; /*!< \return the perimeter */
482 static int nshapes;
483 };
484 </pre></div>
485
486 <p>
487 Simply running SWIG should result in the following code being present in Shapes.java
488 </p>
489
490 <div class="targetlang"><pre>
491
492 /**
493 * This is describing class Shape
494 * @author Bob
495 *
496 */
497
498 public class Shape {
499
500 ...
501
502 /**
503 * Important Variables
504 */
505 public void setX(double value) {
506 ShapesJNI.Shape_x_set(swigCPtr, this, value);
507 }
508
509 /**
510 * Important Variables
511 */
512 public double getX() {
513 return ShapesJNI.Shape_x_get(swigCPtr, this);
514 }
515
516 /**
517 * Moves the Shape
518 */
519 public void move(double dx, double dy) {
520 ShapesJNI.Shape_move(swigCPtr, this, dx, dy);
521 }
522
523 /**
524 * @return the area
525 */
526 public double area() {
527 return ShapesJNI.Shape_area(swigCPtr, this);
528 }
529
530 /**
531 * @return the perimeter
532 */
533 public double perimeter() {
534 return ShapesJNI.Shape_perimeter(swigCPtr, this);
535 }
536 }
537
538 </pre></div>
539
540 <p>
541 The code Java-wise should be identical to what would have been
542 generated without the doxygen functionality enabled. When the Doxygen Translator
543 module encounters a comment that contains nothing useful or a doxygen comment that it cannot
544 parse, it will not affect the functionality of the SWIG generated
545 code.
546 </p>
547
548 <p>
549 The Javadoc translator will handle most of the tags conversions (see the
550 table below). It will also automatically translate link-objects
551 params, in \see and \link...\endlink commands. For example,
552 'someFunction(std::string)' will be converted to
553 'someFunction(String)'. If
554 you don't want such behaviour, you could turn this off by using the
555 'doxygen:nolinktranslate' feature. Also all '\param' and '\tparam'
556 commands are stripped out, if the specified parameter is not present in
557 the function. Use 'doxygen:nostripparams' to avoid.
558 </p>
559
560 <p>
561 Javadoc translator features summary
562 (see <a href="Customization.html#Customization_features">%feature
563 directives</a>):
564 </p>
565
566 <H3><a name="Doxygen_javadoc_tags">18.3.2 Javadoc tags</a></H3>
567
568
569 <p>
570 Here is the list of all Doxygen tags and the description of how they are translated to Javadoc
571 </p>
572 <div class="diagram">
573 <table border="0" summary="Java Doxygen tags">
574 <tr>
575 <th align="left">Doxygen tags</th>
576 </tr>
577 <tr>
578 <td>\a</td>
579 <td>wrapped with <i> html tag</td>
580 </tr>
581 <tr>
582 <td>\arg</td>
583 <td>wrapped with <li> html tag</td>
584 </tr>
585 <tr>
586 <td>\author</td>
587 <td>translated to @author</td>
588 </tr>
589 <tr>
590 <td>\authors</td>
591 <td>translated to @author</td>
592 </tr>
593 <tr>
594 <td>\b</td>
595 <td>wrapped with <b> html tag</td>
596 </tr>
597 <tr>
598 <td>\c</td>
599 <td>wrapped with <code> html tag</td>
600 </tr>
601 <tr>
602 <td>\cite</td>
603 <td>wrapped with <i> html tag</td>
604 </tr>
605 <tr>
606 <td>\code</td>
607 <td>translated to {@code ...}</td>
608 </tr>
609 <tr>
610 <td>\code{<ext>}</td>
611 <td>translated to {@code ...}; code language extension is ignored</td>
612 </tr>
613 <tr>
614 <td>\cond</td>
615 <td>translated to 'Conditional comment: <condition>'</td>
616 </tr>
617 <tr>
618 <td>\copyright</td>
619 <td>replaced with 'Copyright:'</td>
620 </tr>
621 <tr>
622 <td>\deprecated</td>
623 <td>translated to @deprecated</td>
624 </tr>
625 <tr>
626 <td>\e</td>
627 <td>wrapped with <i> html tag</td>
628 </tr>
629 <tr>
630 <td>\else</td>
631 <td>replaced with '}Else:{'</td>
632 </tr>
633 <tr>
634 <td>\elseif</td>
635 <td>replaced with '}Else if: <condition>{'</td>
636 </tr>
637 <tr>
638 <td>\em</td>
639 <td>wrapped with <i> html tag</td>
640 </tr>
641 <tr>
642 <td>\endcode</td>
643 <td>see note for \code</td>
644 </tr>
645 <tr>
646 <td>\endcond</td>
647 <td>replaced with 'End of conditional comment.'</td>
648 </tr>
649 <tr>
650 <td>\endif</td>
651 <td>replaced with '}'</td>
652 </tr>
653 <tr>
654 <td>\endlink</td>
655 <td>see note for \link</td>
656 </tr>
657 <tr>
658 <td>\endverbatim</td>
659 <td>see note for \verbatim</td>
660 </tr>
661 <tr>
662 <td>\exception</td>
663 <td>translated to @exception</td>
664 </tr>
665 <tr>
666 <td>\f$, \f[, \f], \f{, \f}</td>
667 <td>LateX formulas are left unchanged</td>
668 </tr>
669 <tr>
670 <td>\if</td>
671 <td>replaced with 'If: <condition> {'</td>
672 </tr>
673 <tr>
674 <td>\ifnot</td>
675 <td>replaced with 'If not: <condition> {'</td>
676 </tr>
677 <tr>
678 <td>\image</td>
679 <td>translated to <img/> html tag only if target=HTML</td>
680 </tr>
681 <tr>
682 <td>\li</td>
683 <td>wrapped with <li> html tag</td>
684 </tr>
685 <tr>
686 <td>\link</td>
687 <td>translated to {@link ...}</td>
688 </tr>
689 <tr>
690 <td>\n</td>
691 <td>replaced with newline char</td>
692 </tr>
693 <tr>
694 <td>\note</td>
695 <td>replaced with 'Note:'</td>
696 </tr>
697 <tr>
698 <td>\overload</td>
699 <td>prints 'This is an overloaded ...' according to Doxygen docs</td>
700 </tr>
701 <tr>
702 <td>\p</td>
703 <td>wrapped with <code> html tag</td>
704 </tr>
705 <tr>
706 <td>\par</td>
707 <td>replaced with <p alt='title'>...</p></td>
708 </tr>
709 <tr>
710 <td>\param</td>
711 <td>translated to @param</td>
712 </tr>
713 <tr>
714 <td>\param[<dir>]</td>
715 <td>translated to @param; parameter direction ('in'; 'out'; or 'in,out') is ignored</td>
716 </tr>
717 <tr>
718 <td>\remark</td>
719 <td>replaced with 'Remarks:'</td>
720 </tr>
721 <tr>
722 <td>\remarks</td>
723 <td>replaced with 'Remarks:'</td>
724 </tr>
725 <tr>
726 <td>\result</td>
727 <td>translated to @return</td>
728 </tr>
729 <tr>
730 <td>\return</td>
731 <td>translated to @return</td>
732 </tr>
733 <tr>
734 <td>\returns</td>
735 <td>translated to @return</td>
736 </tr>
737 <tr>
738 <td>\sa</td>
739 <td>translated to @see</td>
740 </tr>
741 <tr>
742 <td>\see</td>
743 <td>translated to @see</td>
744 </tr>
745 <tr>
746 <td>\since</td>
747 <td>translated to @since</td>
748 </tr>
749 <tr>
750 <td>\throw</td>
751 <td>translated to @throws</td>
752 </tr>
753 <tr>
754 <td>\throws</td>
755 <td>translated to @throws</td>
756 </tr>
757 <tr>
758 <td>\todo</td>
759 <td>replaced with 'TODO:'</td>
760 </tr>
761 <tr>
762 <td>\tparam</td>
763 <td>translated to @param</td>
764 </tr>
765 <tr>
766 <td>\verbatim</td>
767 <td>translated to {@literal ...}</td>
768 </tr>
769 <tr>
770 <td>\version</td>
771 <td>translated to @version</td>
772 </tr>
773 <tr>
774 <td>\warning</td>
775 <td>translated to 'Warning:'</td>
776 </tr>
777 <tr>
778 <td>\$</td>
779 <td>prints $ char</td>
780 </tr>
781 <tr>
782 <td>\@</td>
783 <td>prints @ char</td>
784 </tr>
785 <tr>
786 <td>\\</td>
787 <td>prints \ char</td>
788 </tr>
789 <tr>
790 <td>\&</td>
791 <td>prints & char</td>
792 </tr>
793 <tr>
794 <td>\~</td>
795 <td>prints ~ char</td>
796 </tr>
797 <tr>
798 <td>\<</td>
799 <td>prints < char</td>
800 </tr>
801 <tr>
802 <td>\></td>
803 <td>prints > char</td>
804 </tr>
805 <tr>
806 <td>\#</td>
807 <td>prints # char</td>
808 </tr>
809 <tr>
810 <td>\%</td>
811 <td>prints % char</td>
812 </tr>
813 <tr>
814 <td>\"</td>
815 <td>prints " char</td>
816 </tr>
817 <tr>
818 <td>\.</td>
819 <td>prints . char</td>
820 </tr>
821 <tr>
822 <td>\::</td>
823 <td>prints ::</td>
824 </tr>
825 </table>
826 </div>
827
828 <H3><a name="Doxygen_unsupported_tags">18.3.3 Unsupported tags</a></H3>
829
830
831 <p>
832 Doxygen has a wealth of tags such as @latexonly that have no
833 equivalent in Javadoc (all supported tags are listed in
834 <a href="https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html">Javadoc documentation</a>).
835 As a result several tags have no
836 translation or particular use, such as some linking and section tags.
837 These are suppressed with their content just printed out (if the tag has any
838 sense, typically text content).
839 Here is the list of these tags:
840 </p>
841
842 <div class="diagram">
843 <b>Unsupported Doxygen tags</b>
844
845 <ul style="list-style-type:none;column-count:4;">
846 <li>\addindex</li>
847 <li>\addtogroup</li>
848 <li>\anchor</li>
849 <li>\attention</li>
850 <li>\brief</li>
851 <li>\bug</li>
852 <li>\callergraph</li>
853 <li>\callgraph</li>
854 <li>\category</li>
855 <li>\class</li>
856 <li>\copybrief</li>
857 <li>\copydetails</li>
858 <li>\copydoc</li>
859 <li>\date</li>
860 <li>\def</li>
861 <li>\defgroup</li>
862 <li>\details</li>
863 <li>\dir</li>
864 <li>\dontinclude</li>
865 <li>\dot</li>
866 <li>\dotfile</li>
867 <li>\enddot</li>
868 <li>\endhtmlonly</li>
869 <li>\endinternal</li>
870 <li>\endlatexonly</li>
871 <li>\endmanonly</li>
872 <li>\endmsc</li>
873 <li>\endrtfonly</li>
874 <li>\endxmlonly</li>
875 <li>\enum</li>
876 <li>\example</li>
877 <li>\extends</li>
878 <li>\file</li>
879 <li>\fn</li>
880 <li>\headerfile</li>
881 <li>\hideinitializer</li>
882 <li>\htmlinclude</li>
883 <li>\htmlonly</li>
884 <li>\implements</li>
885 <li>\include</li>
886 <li>\includelineno</li>
887 <li>\ingroup</li>
888 <li>\interface</li>
889 <li>\internal</li>
890 <li>\invariant</li>
891 <li>\latexonly</li>
892 <li>\line</li>
893 <li>\mainpage</li>
894 <li>\manonly</li>
895 <li>\memberof</li>
896 <li>\msc</li>
897 <li>\mscfile</li>
898 <li>\name</li>
899 <li>\namespace</li>
900 <li>\nosubgrouping</li>
901 <li>\package</li>
902 <li>\page</li>
903 <li>\paragraph</li>
904 <li>\post</li>
905 <li>\pre</li>
906 <li>\private</li>
907 <li>\privatesection</li>
908 <li>\property</li>
909 <li>\protected</li>
910 <li>\protectedsection</li>
911 <li>\protocol</li>
912 <li>\public</li>
913 <li>\publicsection</li>
914 <li>\ref</li>
915 <li>\related</li>
916 <li>\relatedalso</li>
917 <li>\relates</li>
918 <li>\relatesalso</li>
919 <li>\retval</li>
920 <li>\rtfonly</li>
921 <li>\section</li>
922 <li>\short</li>
923 <li>\showinitializer</li>
924 <li>\skip</li>
925 <li>\skipline</li>
926 <li>\snippet</li>
927 <li>\struct</li>
928 <li>\subpage</li>
929 <li>\subsection</li>
930 <li>\subsubsection</li>
931 <li>\tableofcontents</li>
932 <li>\test</li>
933 <li>\typedef</li>
934 <li>\union</li>
935 <li>\until</li>
936 <li>\var</li>
937 <li>\verbinclude</li>
938 <li>\weakgroup</li>
939 <li>\xmlonly</li>
940 <li>\xrefitem</li>
941 </ul>
942 </div>
943
944 <p>
945
946 If one of the following Doxygen tags appears as the first tag in a
947 comment, the whole comment block is ignored:
948 <!-- see parser.y, function isStructuralDoxygen() -->
949
950 </p>
951
952 <div class="diagram">
953 <b>Ignored Doxygen tags</b>
954
955 <ul style="list-style-type:none;column-count:4;">
956 <li>\addtogroup</li>
957 <li>\callergraph</li>
958 <li>\callgraph</li>
959 <li>\category</li>
960 <li>\class</li>
961 <li>\def</li>
962 <li>\defgroup</li>
963 <li>\dir</li>
964 <li>\enum</li>
965 <li>\example</li>
966 <li>\file</li>
967 <li>\fn</li>
968 <li>\headerfile</li>
969 <li>\hideinitializer</li>
970 <li>\interface</li>
971 <li>\internal</li>
972 <li>\mainpage</li>
973 <li>\name</li>
974 <li>\namespace</li>
975 <li>\nosubgrouping</li>
976 <li>\overload</li>
977 <li>\package</li>
978 <li>\page</li>
979 <li>\property</li>
980 <li>\protocol</li>
981 <li>\relates</li>
982 <li>\relatesalso</li>
983 <li>\showinitializer</li>
984 <li>\struct</li>
985 <li>\typedef</li>
986 <li>\union</li>
987 <li>\var</li>
988 <li>\weakgroup</li>
989 </ul>
990 </div>
991
992
993
994
995 <H3><a name="Doxygen_further_details">18.3.4 Further details</a></H3>
996
997
998 <p>
999 TO BE ADDED.
1000 </p>
1001
1002 <H2><a name="Doxygen_to_pydoc">18.4 Doxygen to Pydoc</a></H2>
1003
1004
1005 <p>
1006 If translation is enabled, Pydoc formatted comments should be
1007 automatically placed in the correct locations in the resulting module
1008 and proxy files. The problem is that Pydoc has no tag mechanism like
1009 Doxygen or Javadoc, so most of Doxygen commands are translated by merely
1010 copying the appropriate command text.
1011 </p>
1012
1013 <H3><a name="Doxygen_python_basic_example">18.4.1 Basic example</a></H3>
1014
1015
1016 <p>
1017 Here is an example segment from an included header file
1018 </p>
1019 <div class="code"><pre>
1020 /*! This is describing class Shape
1021 \author Bob
1022 */
1023
1024 class Shape {
1025 public:
1026 Shape() {
1027 nshapes++;
1028 }
1029 virtual ~Shape() {
1030 nshapes--;
1031 };
1032 double x, y; /*!< Important Variables */
1033 void move(double dx, double dy); /*!< Moves the Shape */
1034 virtual double area(void) = 0; /*!< \return the area */
1035 virtual double perimeter(void) = 0; /*!< \return the perimeter */
1036 static int nshapes;
1037 };
1038 </pre></div>
1039
1040 <p>
1041 Simply running SWIG should result in the following code being present in Shapes.py
1042 </p>
1043
1044 <div class="targetlang"><pre>
1045
1046 ...
1047
1048 class Shape(_object):
1049 """
1050 This is describing class Shape
1051 Authors:
1052 Bob
1053
1054 """
1055
1056 ...
1057
1058 def move(self, *args):
1059 """
1060 Moves the Shape
1061 """
1062 return _Shapes.Shape_move(self, *args)
1063
1064 def area(self):
1065 """
1066 Return:
1067 the area
1068 """
1069 return _Shapes.Shape_area(self)
1070
1071 def perimeter(self):
1072 """
1073 Return:
1074 the perimeter
1075 """
1076 return _Shapes.Shape_perimeter(self)
1077 </pre></div>
1078
1079 <p>
1080 If any parameters of a function or a method are documented in the Doxygen comment,
1081 their description is copied into the generated output using
1082 <a href="https://www.sphinx-doc.org/">Sphinx </a> documentation conventions. For example
1083 </p>
1084 <div class="code"><pre>
1085 /**
1086 Set a breakpoint at the given location.
1087
1088 @param filename The full path to the file.
1089 @param line_number The line number in the file.
1090 */
1091 bool SetBreakpoint(const char* filename, int line_number);
1092 </pre></div>
1093
1094 <p>
1095 would be translated to
1096 </p>
1097
1098 <div class="targetlang"><pre>
1099 def SetBreakpoint(filename, line_number):
1100 r"""
1101 Set a breakpoint at the given location.
1102
1103 :type filename: string
1104 :param filename: The full path to the file.
1105 :type line_number: int
1106 :param line_number: The line number in the file.
1107 """
1108 </pre></div>
1109 <p>
1110 The types used for the parameter documentation come from the "doctype" typemap which
1111 is defined for all the primitive types and a few others (e.g. <tt>std::string</tt> and
1112 <tt>shared_ptr<T></tt>) but for non-primitive types is taken to be just the C++
1113 name of the type with namespace scope delimiters (<tt>::</tt>) replaced with a dot. To
1114 change this, you can define your own typemaps for the custom types, e.g:
1115 </p>
1116 <div class="code"><pre>
1117 %typemap(doctype) MyDate "datetime.date"
1118 </pre></div>
1119
1120 <p>
1121 Currently Doxygen comments assigned to global variables and static member variables
1122 are not present in generated code, so they have no comment translated for them.
1123 </p>
1124
1125 <p>
1126 <b>Whitespace and tables</b>
1127 Whitespace is preserved when translating comments, so it makes
1128 sense to have Doxygen comments formatted in a readable way. This
1129 includes tables, where tags <th>, <td> and </tr>are translated
1130 to '|'. The line after line with <th> tags contains dashes.
1131 If we take care about whitespace, comments in Python are much more
1132 readable. Example:
1133
1134 <div class="code"><pre>
1135 /**
1136 * <table border = '1'>
1137 * <caption>Animals</caption>
1138 * <tr><th> Column 1 </th><th> Column 2 </th></tr>
1139 * <tr><td> cow </td><td> dog </td></tr>
1140 * <tr><td> cat </td><td> mouse </td></tr>
1141 * <tr><td> horse </td><td> parrot </td></tr>
1142 * </table>
1143 */
1144 </pre></div>
1145 <p>
1146 translates to Python as:
1147 </p>
1148 <div class="diagram"><pre>
1149 Animals
1150 | Column 1 | Column 2 |
1151 -----------------------
1152 | cow | dog |
1153 | cat | mouse |
1154 | horse | parrot |
1155 </pre></div>
1156
1157 <p>
1158 <b>Overloaded functions</b>
1159 Since all the overloaded functions in c++ are wrapped into one Python
1160 function, Pydoc translator will combine every comment of every
1161 overloaded function and put it into the comment for the one wrapper function.
1162 </p>
1163 <p>
1164 If you intend to use resulting generated Python file with the Doxygen docs
1165 generator, rather than Pydoc, you may want to turn off translation
1166 completely (doxygen:notranslate feature). Then SWIG will just copy
1167 the comments to the proxy file and reformat them if needed, but all
1168 the comment content will be left as is. As Doxygen doesn't support
1169 special commands in Python comments
1170 (see <a href="https://www.doxygen.nl/manual/docblocks.html#pythonblocks">Doxygen
1171 docs</a>), you may want to use some tool like doxypy
1172 (<a href="https://pypi.org/project/doxypy/">doxypy</a>)
1173 to do the work.
1174 </p>
1175
1176 <H3><a name="Doxygen_pydoc_tags">18.4.2 Pydoc translator</a></H3>
1177
1178
1179 <p>
1180 Here is the list of all Doxygen tags and the description of how they are translated to Pydoc
1181 </p>
1182 <div class="diagram">
1183 <table border="0" summary="Python Doxygen tags">
1184 <tr>
1185 <th align="left">Doxygen tags</th>
1186 </tr>
1187 <tr>
1188 <td>\a</td>
1189 <td>wrapped with '*'</td>
1190 </tr>
1191 <tr>
1192 <td>\arg</td>
1193 <td>prepended with '* '</td>
1194 </tr>
1195 <tr>
1196 <td>\author</td>
1197 <td>prints 'Author:'</td>
1198 </tr>
1199 <tr>
1200 <td>\authors</td>
1201 <td>prints 'Authors:'</td>
1202 </tr>
1203 <tr>
1204 <td>\b</td>
1205 <td>wrapped with '**'</td>
1206 </tr>
1207 <tr>
1208 <td>\c</td>
1209 <td>wrapped with '``'</td>
1210 </tr>
1211 <tr>
1212 <td>\cite</td>
1213 <td>wrapped with single quotes</td>
1214 </tr>
1215 <tr>
1216 <td>\code</td>
1217 <td>replaced with '.. code-block:: c++'</td>
1218 </tr>
1219 <tr>
1220 <td>\code{<ext>}</td>
1221 <td>replaced with '.. code-block:: <lang>', where the following doxygen code languages are recognized: .c -> C, .py -> python, .java > java</td>
1222 </tr>
1223 <tr>
1224 <td>\cond</td>
1225 <td>translated to 'Conditional comment: <condition>'</td>
1226 </tr>
1227 <tr>
1228 <td>\copyright</td>
1229 <td>prints 'Copyright:'</td>
1230 </tr>
1231 <tr>
1232 <td>\deprecated</td>
1233 <td>prints 'Deprecated:'</td>
1234 </tr>
1235 <tr>
1236 <td>\e</td>
1237 <td>wrapped with '*'</td>
1238 </tr>
1239 <tr>
1240 <td>\else</td>
1241 <td>replaced with '}Else:{'</td>
1242 </tr>
1243 <tr>
1244 <td>\elseif</td>
1245 <td>replaced with '}Else if: <condition>{'</td>
1246 </tr>
1247 <tr>
1248 <td>\em</td>
1249 <td>wrapped with '*'</td>
1250 </tr>
1251 <tr>
1252 <td>\endcond</td>
1253 <td>replaced with 'End of conditional comment.'</td>
1254 </tr>
1255 <tr>
1256 <td>\endif</td>
1257 <td>replaced with '}'</td>
1258 </tr>
1259 <tr>
1260 <td>\example</td>
1261 <td>replaced with 'Example:'</td>
1262 </tr>
1263 <tr>
1264 <td>\exception</td>
1265 <td>replaced with ':raises:'</td>
1266 </tr>
1267 <tr>
1268 <td>\f$</td>
1269 <td>rendered using ':math:``'</td>
1270 </tr>
1271 <tr>
1272 <td>\f[</td>
1273 <td>rendered using '.. math::'</td>
1274 </tr>
1275 <tr>
1276 <td>\f{</td>
1277 <td>rendered using '.. math::'</td>
1278 </tr>
1279 <tr>
1280 <td>\if</td>
1281 <td>replaced with 'If: <condition> {'</td>
1282 </tr>
1283 <tr>
1284 <td>\ifnot</td>
1285 <td>replaced with 'If not: <condition> {'</td>
1286 </tr>
1287 <tr>
1288 <td>\li</td>
1289 <td>prepended with '* '</td>
1290 </tr>
1291 <tr>
1292 <td>\n</td>
1293 <td>replaced with newline char</td>
1294 </tr>
1295 <tr>
1296 <td>\note</td>
1297 <td>replaced with 'Note:'</td>
1298 </tr>
1299 <tr>
1300 <td>\overload</td>
1301 <td>prints 'This is an overloaded ...' according to Doxygen docs</td>
1302 </tr>
1303 <tr>
1304 <td>\p</td>
1305 <td>wrapped with '``'</td>
1306 </tr>
1307 <tr>
1308 <td>\par</td>
1309 <td>replaced with 'Title: ...'</td>
1310 </tr>
1311 <tr>
1312 <td>\param</td>
1313 <td>add ':type:' and ':param:' directives</td>
1314 </tr>
1315 <tr>
1316 <td>\param[<dir>]</td>
1317 <td>same as \param, but direction ('in'; 'out'; 'in,out') is included in ':type:' directive</td>
1318 </tr>
1319 <tr>
1320 <td>\remark</td>
1321 <td>replaced with 'Remarks:'</td>
1322 </tr>
1323 <tr>
1324 <td>\remarks</td>
1325 <td>replaced with 'Remarks:'</td>
1326 </tr>
1327 <tr>
1328 <td>\result</td>
1329 <td>add ':rtype:' and ':return:' directives</td>
1330 </tr>
1331 <tr>
1332 <td>\return</td>
1333 <td>add ':rtype:' and ':return:' directives</td>
1334 </tr>
1335 <tr>
1336 <td>\returns</td>
1337 <td>add ':rtype:' and ':return:' directives</td>
1338 </tr>
1339 <tr>
1340 <td>\sa</td>
1341 <td>replaced with 'See also:'</td>
1342 </tr>
1343 <tr>
1344 <td>\see</td>
1345 <td>replaced with 'See also:'</td>
1346 </tr>
1347 <tr>
1348 <td>\since</td>
1349 <td>replaced with 'Since:'</td>
1350 </tr>
1351 <tr>
1352 <td>\throw</td>
1353 <td>replaced with ':raises:'</td>
1354 </tr>
1355 <tr>
1356 <td>\throws</td>
1357 <td>replaced with ':raises:'</td>
1358 </tr>
1359 <tr>
1360 <td>\todo</td>
1361 <td>replaced with 'TODO:'</td>
1362 </tr>
1363 <tr>
1364 <td>\tparam</td>
1365 <td>add ':type:' and ':param:' directives</td>
1366 </tr>
1367 <tr>
1368 <td>\verbatim</td>
1369 <td>content copied verbatim</td>
1370 </tr>
1371 <tr>
1372 <td>\version</td>
1373 <td>replaced with 'Version:'</td>
1374 </tr>
1375 <tr>
1376 <td>\warning</td>
1377 <td>translated to 'Warning:'</td>
1378 </tr>
1379 <tr>
1380 <td>\$</td>
1381 <td>prints $ char</td>
1382 </tr>
1383 <tr>
1384 <td>\@</td>
1385 <td>prints @ char</td>
1386 </tr>
1387 <tr>
1388 <td>\\</td>
1389 <td>prints \ char</td>
1390 </tr>
1391 <tr>
1392 <td>\&</td>
1393 <td>prints & char</td>
1394 </tr>
1395 <tr>
1396 <td>\~</td>
1397 <td>prints ~ char</td>
1398 </tr>
1399 <tr>
1400 <td>\<</td>
1401 <td>prints < char</td>
1402 </tr>
1403 <tr>
1404 <td>\></td>
1405 <td>prints > char</td>
1406 </tr>
1407 <tr>
1408 <td>\#</td>
1409 <td>prints # char</td>
1410 </tr>
1411 <tr>
1412 <td>\%</td>
1413 <td>prints % char</td>
1414 </tr>
1415 <tr>
1416 <td>\"</td>
1417 <td>prints " char</td>
1418 </tr>
1419 <tr>
1420 <td>\.</td>
1421 <td>prints . character</td>
1422 </tr>
1423 <tr>
1424 <td>\::</td>
1425 <td>prints ::</td>
1426 </tr>
1427 </table>
1428 </div>
1429
1430 <H3><a name="Doxygen_python_unsupported_tags">18.4.3 Unsupported tags</a></H3>
1431
1432
1433 <p>
1434 Doxygen has a wealth of tags such as @latexonly that have no
1435 equivalent in Pydoc. As a result several tags that have no
1436 translation (or particular use, such as some linking and section tags)
1437 are suppressed with their content just printed out (if it has any
1438 sense, typically text content).
1439 Here is the list of these tags:
1440 </p>
1441
1442 <div class="diagram">
1443 <b>Unsupported Python Doxygen tags</b>
1444
1445 <ul style="list-style-type:none;column-count:4;">
1446 <li>\addindex</li>
1447 <li>\addtogroup</li>
1448 <li>\anchor</li>
1449 <li>\attention</li>
1450 <li>\brief</li>
1451 <li>\bug</li>
1452 <li>\callergraph</li>
1453 <li>\callgraph</li>
1454 <li>\category</li>
1455 <li>\class</li>
1456 <li>\copybrief</li>
1457 <li>\copydetails</li>
1458 <li>\copydoc</li>
1459 <li>\date</li>
1460 <li>\def</li>
1461 <li>\defgroup</li>
1462 <li>\details</li>
1463 <li>\dir</li>
1464 <li>\dontinclude</li>
1465 <li>\dot</li>
1466 <li>\dotfile</li>
1467 <li>\enddot</li>
1468 <li>\endhtmlonly</li>
1469 <li>\endinternal</li>
1470 <li>\endlatexonly</li>
1471 <li>\endlink</li>
1472 <li>\endmanonly</li>
1473 <li>\endmsc</li>
1474 <li>\endrtfonly</li>
1475 <li>\endxmlonly</li>
1476 <li>\enum</li>
1477 <li>\extends</li>
1478 <li>\file</li>
1479 <li>\fn</li>
1480 <li>\headerfile</li>
1481 <li>\hideinitializer</li>
1482 <li>\htmlinclude</li>
1483 <li>\htmlonly</li>
1484 <li>\image</li>
1485 <li>\implements</li>
1486 <li>\include</li>
1487 <li>\includelineno</li>
1488 <li>\ingroup</li>
1489 <li>\interface</li>
1490 <li>\internal</li>
1491 <li>\invariant</li>
1492 <li>\latexonly</li>
1493 <li>\line</li>
1494 <li>\link</li>
1495 <li>\mainpage</li>
1496 <li>\manonly</li>
1497 <li>\memberof</li>
1498 <li>\msc</li>
1499 <li>\mscfile</li>
1500 <li>\name</li>
1501 <li>\namespace</li>
1502 <li>\nosubgrouping</li>
1503 <li>\package</li>
1504 <li>\page</li>
1505 <li>\paragraph</li>
1506 <li>\post</li>
1507 <li>\pre</li>
1508 <li>\private</li>
1509 <li>\privatesection</li>
1510 <li>\property</li>
1511 <li>\protected</li>
1512 <li>\protectedsection</li>
1513 <li>\protocol</li>
1514 <li>\public</li>
1515 <li>\publicsection</li>
1516 <li>\ref</li>
1517 <li>\related</li>
1518 <li>\relatedalso</li>
1519 <li>\relates</li>
1520 <li>\relatesalso</li>
1521 <li>\retval</li>
1522 <li>\rtfonly</li>
1523 <li>\section</li>
1524 <li>\short</li>
1525 <li>\showinitializer</li>
1526 <li>\skip</li>
1527 <li>\skipline</li>
1528 <li>\snippet</li>
1529 <li>\struct</li>
1530 <li>\subpage</li>
1531 <li>\subsection</li>
1532 <li>\subsubsection</li>
1533 <li>\tableofcontents</li>
1534 <li>\test</li>
1535 <li>\typedef</li>
1536 <li>\union</li>
1537 <li>\until</li>
1538 <li>\var</li>
1539 <li>\verbinclude</li>
1540 <li>\weakgroup</li>
1541 <li>\xmlonly</li>
1542 <li>\xrefitem</li>
1543 </ul>
1544 </div>
1545
1546 <H3><a name="Doxygen_python_further_details">18.4.4 Further details</a></H3>
1547
1548
1549 <p>
1550 TO BE ADDED.
1551 </p>
1552
1553 <H2><a name="Doxygen_troubleshooting">18.5 Troubleshooting</a></H2>
1554
1555
1556 <p>
1557 When running SWIG with command line option <tt>-doxygen</tt>, it may happen
1558 that SWIG will fail to parse the code, which is valid C++ code and
1559 is parsed without problems without the option. The problem is,
1560 that Doxygen comments are not tokens (the C/C++ compiler actually never
1561 sees them) and that they can appear anywhere in the code. That's why it is
1562 practically impossible to handle all corner cases with the parser.
1563 However, these problems can usually be avoided by minor changes in the
1564 code or comment. Known problems and solutions are shown in this section.
1565 </p>
1566
1567
1568 <p>
1569 Recommended approach is to first run SWIG without command line
1570 option <tt>-doxygen</tt>. When it successfully processes the code,
1571 include the option and fix problems with Doxygen comments.
1572 </p>
1573
1574
1575 <H3><a name="troubleshooting_ifndef">18.5.1 Problem with conditional compilation</a></H3>
1576
1577
1578 <p>
1579 Inserting a conditional compilation preprocessor directive between a
1580 Doxygen comment and a commented item may break parsing:
1581 </p>
1582
1583
1584 <div class="code"><pre>
1585 class A {
1586 /**
1587 * Some func.
1588 */
1589 <font color='#ff0000'>#ifndef SWIG</font>
1590 void myfunc()
1591 {
1592 }
1593 #endif
1594 };
1595 </pre></div>
1596
1597 <p>
1598 The solution is to move the directive above the comment:
1599 </p>
1600
1601 <div class="code"><pre>
1602 class A {
1603 <font color='#00d000'>#ifndef SWIG</font>
1604 /**
1605 * Some func.
1606 */
1607 void myfunc()
1608 {
1609 }
1610 #endif
1611 };
1612 </pre></div>
1613
1614
1615 <H2><a name="Doxygen_developer_details">18.6 Developer information</a></H2>
1616
1617
1618 <p>
1619 This section contains information for developers enhancing the Doxygen translator.
1620 </p>
1621
1622 <H3><a name="Doxygen_translator_design">18.6.1 Doxygen translator design</a></H3>
1623
1624
1625 <p>
1626 If this functionality is turned on, SWIG places all comments found
1627 into the SWIG parse tree. Nodes contain an additional attribute
1628 called <tt>doxygen</tt> when a comment is present. Individual nodes
1629 containing Doxygen with Structural Indicators, such as @file, as their
1630 first command, are also present in the parse tree. These individual
1631 "blobs" of Doxygen such as :
1632 </p>
1633 <div class="code"><pre>
1634 /*! This is describing function Foo
1635 \param x some random variable
1636 \author Bob
1637 \return Foo
1638 */
1639 </pre></div>
1640
1641 <p>
1642 are passed on individually to the Doxygen Translator module. This
1643 module builds its own private parse tree and hands it to a separate
1644 class for translation into the target documentation language. For
1645 example, <tt>JavaDocConverter</tt> is the Javadoc module class.
1646 </p>
1647
1648 <H3><a name="Doxygen_debugging_commands">18.6.2 Debugging the Doxygen parser and translator</a></H3>
1649
1650
1651 <p>
1652 There are two handy command line options, that enable lots of
1653 detailed debug information printing.
1654 </p>
1655
1656 <div class="shell"><pre>
1657 -debug-doxygen-parser - Display Doxygen parser module debugging information
1658 -debug-doxygen-translator - Display Doxygen translator module debugging information
1659 </pre></div>
1660
1661 <H3><a name="Doxygen_tests">18.6.3 Tests</a></H3>
1662
1663
1664 <p>
1665 Doxygen tests have been added to the regular SWIG test-suite.
1666 There are a number of tests beginning <tt>doxygen_</tt> in the Examples/test-suite sub-directory.
1667 </p>
1668
1669 <p>
1670 Like any other SWIG test case, the tests are included in Examples/test-suite/common.mk and can be tested with
1671 commands like <tt>make check-test-suite</tt> or <tt>make check-python-test-suite</tt>.
1672 To run them individually, type
1673 <tt>make -s <testname>.cpptest</tt> in the language-specific sub-directory in
1674 <tt>Examples/test-suite</tt> directory. For example:
1675 </p>
1676
1677 <div class="shell"><pre>
1678 Examples/test-suite/java $ make -s doxygen_parsing.cpptest
1679 </pre></div>
1680
1681 <p>
1682 If the test fails, both expected and translated comments are printed to
1683 std out, but also written to files <i>expected.txt</i>
1684 and <i>got.txt</i>. Since it is often difficult to find a single
1685 character difference in several lines of text, we can use some diff
1686 tool, for example:
1687 </p>
1688
1689 <div class="shell"><pre>
1690 Examples/test-suite/java $ kdiff3 expected.txt got.txt
1691 </pre></div>
1692
1693
1694 <p>
1695 Runtime tests in Java are implemented using Javadoc doclets. To make that work, you
1696 should have tools.jar from the JDK in your classpath. Or you should have JAVA_HOME
1697 environment variable defined and pointing to the JDK location.
1698 </p>
1699 <p>
1700 The Java's comment parsing code (the testing part) is located in commentParser.java.
1701 It checks the generated code. It is possible
1702 to run this file as a stand-alone program, with <tt>java commentParser <some java package></tt>,
1703 and it will print the list of comments found in the specified directory (in the format it has used
1704 in the runtime tests). So, when you want to create a new Doxygen test case,
1705 just copy an existing one and replace the actual comment content (section of entries in
1706 form 'wantedComments.put(...)' with the output of the above command.
1707 </p>
1708 <p>
1709 Runtime tests in Python are just plain string comparisons of the __doc__
1710 properties.
1711 </p>
1712
1713 <H2><a name="Doxygen_language_extension">18.7 Extending to other languages</a></H2>
1714
1715
1716 <p>
1717 In general, an extension to another language requires a fairly deep understanding of the target language module, such as Modules/python.cxx for Python.
1718 Searching for "doxygen" in the java.cxx module can give you a good idea of the process for placing documentation comments into the correct areas.
1719 The basic gist is that anywhere a comment may reside on a node, there needs to be a catch for it in front of where that function, class, or other object is written out to a target language file.
1720 The other half of extension is building a target documentation language comment generator that handles one blob at a time.
1721 However, this is relatively simple and nowhere near as complex as the wrapper generating modules in SWIG.
1722 See Source/Doxygen/javadoc.cxx for a good example.
1723 The target language module passes the Doxygen Translator the blob to translate, and receives back the translated text.
1724 </p>
1725 <p>
1726 <b> What is given to the Doxygen Translator</b>
1727 </p>
1728 <div class="code"><pre>
1729 /*! This is describing function Foo
1730 \param x some random variable
1731 \author Bob
1732 \return Foo
1733 */
1734 </pre></div>
1735 <p>
1736 <b> What is received back by java.cxx </b>
1737 </p>
1738 <div class="targetlang"><pre>
1739 /** This is describing function Foo
1740 *
1741 * @param x some random variable
1742 * @author Bob
1743 * @return Foo
1744 */
1745 </pre></div>
1746 <p> Development of the comment translator itself is simplified by the fact that the Doxygen Translator module can easily include a <tt>main</tt> function and thus be developed, compiled, and tested independently of SWIG.
1747 </p>
1748
1749 </body>
1750 </html>