diff options
123 files changed, 12955 insertions, 1335 deletions
diff --git a/CHANGES.current b/CHANGES.current index 7dbb8cd58..e9b566961 100644 --- a/CHANGES.current +++ b/CHANGES.current @@ -7,6 +7,11 @@ the issue number to the end of the URL: https://github.com/swig/swig/issues/ Version 4.0.0 (in progress) =========================== +2018-06-07: cmfoil, kabbi, Jamie Kirkpatrick, markok314, vadz, wsfulton, Yann Diorcet + #170 Doxygen documentation support added. This allows translation of Doxygen comments + into JavaDoc and PyDoc documentation. It is enabled via the -doxygen command line + option. See the Doxygen.html chapter in the documentation for further information. + 2018-06-07: olly [PHP] We've finally removed support for %pragma(php4) which was deprecated back in 2008. Use %pragma(php) instead, which has been @@ -62,7 +62,8 @@ Past SWIG developers and major contributors include: John Lenz (Guile, MzScheme updates, Chicken module, runtime system) Baozeng Ding <sploving1@163.com> (Scilab) Ian Lance Taylor (Go) - Vadim Zeitlin (PCRE, Python) + Dmitry Kabak (userdima@gmail.com) (Doxygen) + Vadim Zeitlin (PCRE, Python, Doxygen) Stefan Zager (szager@gmail.com) (Python) Vincent Couvert (Scilab) Sylvestre Ledru (Scilab) diff --git a/Doc/Devel/plan-gsoc-2012.txt b/Doc/Devel/plan-gsoc-2012.txt new file mode 100644 index 000000000..ac764fb2a --- /dev/null +++ b/Doc/Devel/plan-gsoc-2012.txt @@ -0,0 +1,341 @@ + + + + + Project Plan + ============ + SWIG Code Comments + Google Summer of Code 2012 + + +This document describes goals for the Google Summer of Code 2012, +SWIG code documentation project. + +Author: Marko Klopcic, Dmitry Kabak + + +Introduction +============ + +The goal of this project is _not_ to translate _any_ possible Doxygen +formatted comment to JavaDoc or PyDoc, but to make it possible to +translate a subset of comment types in C/C++ code to +JavaDoc and PyDoc. Covering all the Doxygen functionality would be to +complex for the limited time. However, the code must be flexible so +that implementing missing features would not require redesign of the +comment handling code in SWIG. + +There will also be a possibility to add untranslated comments to Java +and Python code (## comments, see Doxygen manual), if the user will +prefer to use Doxygen on the generated code. + +Note: +'-OK-' tick below means that the item is implemented, committed and +working. + +Abbreviations: + JD - JavaDoc + PD - PyDoc + + +Functionality +============= + + Types of comments + ----------------- + + Note: + See 'http://www.stack.nl/~dimitri/doxygen/docblocks.html' for + the detailed description of Doxygen syntax and terms used in this + section. + + 1. -OK- Only JavaDoc (/** */) and Qt (/*! */) styles of comment blocks + will be supported by SWIG translator. + + 2. -OK- The following doc after members will be supported: + + int var; ///< Detailed description after the member + //!< + + int var; //!< Brief description after the member + + int var; ///< Brief description after the member + + + 3. -OK- Only comments before or after declaration/definition will be + supported. Comments with structural commands will be ignored + (warning will be written). (What about writing them to + 'package.info.java' for JD?) + + + Tags + ---- + + This section contains all doxygen tags taken from + http://www.stack.nl/~dimitri/doxygen/commands.html. If a tag is + marked as 'ignored', then the tag is ignored, but the text is copied + to the destination documentation. 'Not implemented' means that the + tag with it's contents is stripped out of the output. + + Doxygen tags: + + All tags: -OK- + + \a - translated to <i></i> in JD, surrounded with _ in PD + \addindex - ignored + \addtogroup - ignored + \anchor - ignored, not supported by JD and PD + \arg - equivalent to \li + \attention - ignored + \authors, \author - translated to @author in JD, 'Author:' in PD + \b - <b></b> in JD, surrounded with __ in PD + \brief - ignored + \bug - ignored + \c - translated to <code></code> in JD, ignored in PD + \callgraph - ignored, not supported by JD and PD + \callergraph - ignored, not supported by JD and PD + \category - ignored, used only in Objective C + \cite - translated to <i></i> in JD, single quotes in PD + \class - ignored (structural command) + \code - translated to {@code ...} in JD, ignored in PD + \cond - translated to 'Conditional comment: <condition>'. Later + SWIG may support definitions of conditions in config file. + \copybrief - ignored. Later SWIG may support this command by + performing copy + \copydetails - ignored. Later SWIG may support this command by + performing copy + \copydoc - ignored. Later SWIG may support this command by + performing copy + \copyright - replaced with text 'Copyright' in PD and PD + \date - ignored + \def - ignored (structural command) + \defgroup - not supported + \deprecated - translated to @deprecated in JD, 'Deprecated:' in PD + \details - ignored + \dir - not supported + \dontinclude - not supported + \dot - not supported. Later SWIG may call dot and produce the graph image + to include in JD and PD + \dotfile - see note for \dot + \e - equivalent \a + \else - see note for \cond + \elseif - see note for \cond + \em - equivalent to \a + \endcode - see note for \code + \endcond - translated to 'End of conditional comment: <condition>'. Later + SWIG may support definitions of conditions in config file. + \enddot - see note for \dot + \endhtmlonly - ignored + \endif - see note for \cond + \endinternal - ignored + \endlatexonly - ignored + \endlink - see note for \link + \endmanonly - ignored + \endmsc - see note for \msc + \endrtfonly - ignored + \endverbatim - see note for \verbatim + \endxmlonly - ignored + \enum - ignored (structural command) + \example - translated to 'Example:' in JD and PD + \exception - equivalent to throws, but translates to @exception in JD + \extends - not supported + \f$ - ignored. Later swig may call LATeX to produce bitmaps with formulas + to include in JD and PD + \f[ - see note for \f$ + \f] - see note for \f$ + \f{ - see note for \f$ + \f} - see note for \f$ + \file - ignored (structural command) + \fn - ignored (structural command) + \headerfile - not supported + \hideinitializer - not supported + \htmlinclude - not supported + \htmlonly - ignored + \if - see note for \cond + \ifnot - see note for \cond + \image - translated to <img/> in JD only when target=HTML, translated to + 'Image: filename(Title)' + \implements - not supported + \include - not supported + \includelineno - not supported + \ingroup - not supported. Later swig may print group names as plain text + in comments like 'Code group: something' in both JD and PD + \internal - ignored + \invariant - ignored + \interface - ignored (structural command) + \latexonly - ignored + \li - trabslated to <li></li> in JD, ignored in PD + \line - not supported + \link - translated to {@link ...} in JD, ignored in PD + \mainpage - ignored + \manonly - ignored + \memberof - not supported + \msc - not supported. Later SWIG may call dot and produce the graph image + to include in JD and PD + \mscfile - see note for \msc + \n - prints the new line + \name - ignored + \namespace - included in package-info.java if nspace feature is enabled, + otherwise ignored, ignored in PD + \nosubgrouping - ignored + \note - translated to 'Note:' in both JD and PD + \overload - prints 'This is an overloaded member function, provided for + convenience. It differs from the above function only in what + argument(s) it accepts.' to the output in both JD and PD + \p - equivalent to \c + \package - is kept same in JD (it is already a JD tag), ignored in PD + \page - ignored + \par - translated to <p alt='title'></p> in JD, 'Title: ...' in PD + \paragraph - ignored + \param - translated to @param in JD, special formatting in PD + \post - ignored + \pre - ignored + \private - ignored + \privatesection - ignored + \property - ignored + \protected - ignored + \protectedsection - ignored + \protocol - ignored (Objective-C tag) + \public - ignored + \publicsection - ignored + \ref - ignored, not supported by JD and PD + \related - ignored + \relates - ignored + \relatedalso - ignored + \relatesalso - ignored + \remark - translated to 'Remarks:' in both JD and PD + \remarks - equivalent to remark + \result - translated to @return in JD, 'Return:' in PD + \return - equivalent to result + \returns - equivalent to result + \retval - ignored + \rtfonly - ignored + \sa - translated to @see in JD, 'See also:' in PD + \section - not supported + \see - equivalent to \sa + \short - equivalent to \brief + \showinitializer - not supported + \since - translated to @since in JD, 'Since:' in PD + \skip - not supported + \skipline - not supported + \snippet - not supported + \struct - ignored (structural command) + \subpage - not supported + \subsection - not supported + \subsubsection - not supported + \tableofcontents - not supported + \test - ignored + \throw - translated to @throws in JD, 'Throws:' in PD + \throws - equivalent to \throw + \todo - translated to 'TODO:' in both JD and PD + \tparam - similar to \arg + \typedef - ignored (structural command) + \union - ignored (structural command) + \until - not supported + \var - ignored (structural command) + \verbatim - translated to {@literal ...} in JD, ignored in PD + \verbinclude - ignored + \version - translated to @version in JD, 'Version:' in PD + \warning - translated to 'Warning:' in both JD and PD + \weakgroup - not supported + \xmlonly - ignored + \xrefitem - ignored + \$ - this and all the others below: these commands insert single char, + it is escaped as HTML char in JD, kept as-is in PD + \@ + \\ + \& + \~ + \< + \> + \# + \% + \" + \. + \:: + +Optional functionality +====================== + +That section describes some complex cases where the current code +does not behave really well. Like a short to-do list of special cases. + +-OK- When translating functions with default parameters in swig to +java, it creates overloaded functions with all the parameters +except the default ones. We need to copy the doxygen comment to +such functions and correct the list of @param tags. + +-OK- In doxygen there is a special tags (and even a special option) +to create links to some code members from the current comment. +Sometimes it needs a type of parameters specified because of the +overloaded functions. And the same linking tags are supported in JD, +but it has a completely different typesystem, so we need to translate +the types of function parameters in comments also. For example: +{@link MyClass#doSomething(const std::string &)} +does not make sense in Java, so the type should be converted. +{@link MyClass#doSomething(String)} + + +Tests +===== + +The following test cases will be implemented: + +-OK- Class comments. + +-OK- Struct comments. +-OK- Enum comments. +-OK- Function comments. +-OK- Var comments. + +-OK- Class attributes, comment before and after declaration. +-OK- Class methods, comment of parameters in function + comment. +-OK- Class methods, comment of parameters + after parameter declaration. + +-OK- Struct attributes, comment before and after declaration. +-OK- Struct methods, comment of parameters in function + comment. +-OK- Struct methods, comment of parameters + after parameter declaration. + +-OK- Enum items JD and Qt style, comment before items +-OK- Enum items JD and Qt style, comment after items + +-OK- Class comment, with all supported tags. +-OK- Class comment, with all doxygen tags, including + ignored ones. + +The list of all tests, in form of shell commands to make it simple +to test project by copying the text below into terminal program. +make doxygen_parsing.cpptest -s +make doxygen_translate.cpptest -s +make doxygen_translate_all_tags.cpptest -s +make doxygen_basic_translate.cpptest -s +make doxygen_basic_notranslate.cpptest -s +make doxygen_translate_links.cpptest -s +make doxygen_tricky_constructs.cpptest -s + + +Refactoring +=========== + +All the code in directory _Doxygen_ should be refactored: +-OK- all methods should be class members +-OK- most static methods should be normal members +-OK- replace C arrays of strings and sequential searches with STL data + structures and algorithms. +-OK- use singletons instead of class instantiaion for each comment found. + + +Documentation +============= + +SWIG documentation will contain: +-OK- command line options +-OK- list of implemented features (types and placements of comments) +-OK- list of unimplemented features (types and placements of comments) +-OK- list of tags and their translations (all Doxygen tags). +-OK- some amount of debugging and development information + diff --git a/Doc/Manual/Allegrocl.html b/Doc/Manual/Allegrocl.html index 874c4bc2e..a3d631ec4 100644 --- a/Doc/Manual/Allegrocl.html +++ b/Doc/Manual/Allegrocl.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Allegrocl">19 SWIG and Allegro Common Lisp</a></H1> +<H1><a name="Allegrocl">20 SWIG and Allegro Common Lisp</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -135,10 +135,10 @@ be unhappy to see some enterprising folk use this work to add to it. </p> -<H2><a name="Allegrocl_nn2">19.1 Basics</a></H2> +<H2><a name="Allegrocl_nn2">20.1 Basics</a></H2> -<H3><a name="Allegrocl_nn3">19.1.1 Running SWIG</a></H3> +<H3><a name="Allegrocl_nn3">20.1.1 Running SWIG</a></H3> <p> @@ -360,7 +360,7 @@ need to link in the Allegro shared library. The library you create from the C++ wrapper will be what you then load into Allegro CL. </p> -<H3><a name="Allegrocl_nn4">19.1.2 Command Line Options</a></H3> +<H3><a name="Allegrocl_nn4">20.1.2 Command Line Options</a></H3> <p> @@ -396,7 +396,7 @@ See <a href="#Allegrocl_nn47">Section 17.5 Identifier converter functions</a> for more details. </p> -<H3><a name="Allegrocl_nn5">19.1.3 Inserting user code into generated files</a></H3> +<H3><a name="Allegrocl_nn5">20.1.3 Inserting user code into generated files</a></H3> <p> @@ -436,7 +436,7 @@ Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for </p> -<H2><a name="Allegrocl_nn6">19.2 Wrapping Overview</a></H2> +<H2><a name="Allegrocl_nn6">20.2 Wrapping Overview</a></H2> <p> @@ -446,7 +446,7 @@ New users to SWIG are encouraged to read interested in generating an interface to C++. </p> -<H3><a name="Allegrocl_nn7">19.2.1 Function Wrapping</a></H3> +<H3><a name="Allegrocl_nn7">20.2.1 Function Wrapping</a></H3> <p> @@ -499,7 +499,7 @@ interested in generating an interface to C++. </pre> </div> -<H3><a name="Allegrocl_nn8">19.2.2 Foreign Wrappers</a></H3> +<H3><a name="Allegrocl_nn8">20.2.2 Foreign Wrappers</a></H3> <p> @@ -512,7 +512,7 @@ interested in generating an interface to C++. typemap. </p> -<H3><a name="Allegrocl_nn9">19.2.3 FFI Wrappers</a></H3> +<H3><a name="Allegrocl_nn9">20.2.3 FFI Wrappers</a></H3> <p> @@ -593,7 +593,7 @@ char *xxx(); ff:def-foreign-call's. </p> -<H3><a name="Allegrocl_nn10">19.2.4 Non-overloaded Defuns</a></H3> +<H3><a name="Allegrocl_nn10">20.2.4 Non-overloaded Defuns</a></H3> <p> @@ -606,7 +606,7 @@ char *xxx(); this function can be manipulated via the <tt>lout</tt> typemap. </p> -<H3><a name="Allegrocl_nn11">19.2.5 Overloaded Defuns</a></H3> +<H3><a name="Allegrocl_nn11">20.2.5 Overloaded Defuns</a></H3> <p> @@ -622,7 +622,7 @@ char *xxx(); can be manipulated via the <tt>lout</tt> typemap. </p> -<H3><a name="Allegrocl_nn12">19.2.6 What about constant and variable access?</a></H3> +<H3><a name="Allegrocl_nn12">20.2.6 What about constant and variable access?</a></H3> <p> @@ -635,7 +635,7 @@ char *xxx(); into the foreign module. </p> -<H3><a name="Allegrocl_nn13">19.2.7 Object Wrapping</a></H3> +<H3><a name="Allegrocl_nn13">20.2.7 Object Wrapping</a></H3> <p> @@ -657,7 +657,7 @@ char *xxx(); foreign function interface. </p> -<H2><a name="Allegrocl_nn14">19.3 Wrapping Details</a></H2> +<H2><a name="Allegrocl_nn14">20.3 Wrapping Details</a></H2> <p> @@ -665,7 +665,7 @@ char *xxx(); translated into lisp. </p> -<H3><a name="Allegrocl_nn15">19.3.1 Namespaces</a></H3> +<H3><a name="Allegrocl_nn15">20.3.1 Namespaces</a></H3> <p> @@ -742,7 +742,7 @@ namespace car { function such as <tt>(car '(1 2 3)</tt>. </p> -<H3><a name="Allegrocl_nn16">19.3.2 Constants</a></H3> +<H3><a name="Allegrocl_nn16">20.3.2 Constants</a></H3> @@ -803,7 +803,7 @@ namespace car { not use the <tt>-nocwrap</tt> command-line option. </p> -<H3><a name="Allegrocl_nn17">19.3.3 Variables</a></H3> +<H3><a name="Allegrocl_nn17">20.3.3 Variables</a></H3> <p> @@ -881,7 +881,7 @@ globalvar> (globalvar.nnn::glob_float) </pre> </div> -<H3><a name="Allegrocl_nn18">19.3.4 Enumerations</a></H3> +<H3><a name="Allegrocl_nn18">20.3.4 Enumerations</a></H3> <p> @@ -957,7 +957,7 @@ EXPORT const int ACL_ENUM___FOO3__SWIG_0 = FOO3; </pre> </div> -<H3><a name="Allegrocl_nn19">19.3.5 Arrays</a></H3> +<H3><a name="Allegrocl_nn19">20.3.5 Arrays</a></H3> <p> @@ -1105,10 +1105,10 @@ namespace BAR { </pre> </div> -<H3><a name="Allegrocl_nn20">19.3.6 Classes and Structs and Unions (oh my!)</a></H3> +<H3><a name="Allegrocl_nn20">20.3.6 Classes and Structs and Unions (oh my!)</a></H3> -<H4><a name="Allegrocl_nn21">19.3.6.1 CLOS wrapping of</a></H4> +<H4><a name="Allegrocl_nn21">20.3.6.1 CLOS wrapping of</a></H4> <p> @@ -1123,7 +1123,7 @@ namespace BAR { integer values. </p> -<H4><a name="Allegrocl_nn22">19.3.6.2 CLOS Inheritance</a></H4> +<H4><a name="Allegrocl_nn22">20.3.6.2 CLOS Inheritance</a></H4> <p> @@ -1136,7 +1136,7 @@ namespace BAR { parameter. </p> -<H4><a name="Allegrocl_nn23">19.3.6.3 Member fields and functions</a></H4> +<H4><a name="Allegrocl_nn23">20.3.6.3 Member fields and functions</a></H4> <p> @@ -1152,7 +1152,7 @@ namespace BAR { the interface does nothing for <tt>friend</tt> directives, </p> -<H4><a name="Allegrocl_nn24">19.3.6.4 Why not directly access C++ classes using foreign types?</a></H4> +<H4><a name="Allegrocl_nn24">20.3.6.4 Why not directly access C++ classes using foreign types?</a></H4> <p> @@ -1170,11 +1170,11 @@ namespace BAR { use the more robust wrapper functions. </p> -<H3><a name="Allegrocl_nn25">19.3.7 Templates</a></H3> +<H3><a name="Allegrocl_nn25">20.3.7 Templates</a></H3> -<H4><a name="Allegrocl_nn26">19.3.7.1 Generating wrapper code for templates</a></H4> +<H4><a name="Allegrocl_nn26">20.3.7.1 Generating wrapper code for templates</a></H4> <p> @@ -1187,7 +1187,7 @@ them. This is done via the directive. </p> -<H4><a name="Allegrocl_nn27">19.3.7.2 Implicit Template instantiation</a></H4> +<H4><a name="Allegrocl_nn27">20.3.7.2 Implicit Template instantiation</a></H4> <p> @@ -1197,7 +1197,7 @@ to include these templated classes in the foreign-type and CLOS class schema. </p> -<H3><a name="Allegrocl_nn28">19.3.8 Typedef, Templates, and Synonym Types</a></H3> +<H3><a name="Allegrocl_nn28">20.3.8 Typedef, Templates, and Synonym Types</a></H3> <p> @@ -1277,7 +1277,7 @@ synonym> </pre> </div> -<H4><a name="Allegrocl_nn29">19.3.8.1 Choosing a primary type</a></H4> +<H4><a name="Allegrocl_nn29">20.3.8.1 Choosing a primary type</a></H4> <p> @@ -1298,7 +1298,7 @@ synonym> </li> </ul> -<H3><a name="Allegrocl_nn30">19.3.9 Function overloading/Parameter defaulting</a></H3> +<H3><a name="Allegrocl_nn30">20.3.9 Function overloading/Parameter defaulting</a></H3> <p> @@ -1461,7 +1461,7 @@ overload> </pre> </div> -<H3><a name="Allegrocl_nn31">19.3.10 Operator wrapping and Operator overloading</a></H3> +<H3><a name="Allegrocl_nn31">20.3.10 Operator wrapping and Operator overloading</a></H3> <p> @@ -1607,7 +1607,7 @@ opoverload> </pre> </div> -<H3><a name="Allegrocl_nn32">19.3.11 Varargs</a></H3> +<H3><a name="Allegrocl_nn32">20.3.11 Varargs</a></H3> <p> @@ -1628,7 +1628,7 @@ opoverload> with other ways such functions can be wrapped. </p> -<H3><a name="Allegrocl_nn33">19.3.12 C++ Exceptions</a></H3> +<H3><a name="Allegrocl_nn33">20.3.12 C++ Exceptions</a></H3> <p> @@ -1640,7 +1640,7 @@ opoverload> implemented. </p> -<H3><a name="Allegrocl_nn34">19.3.13 Pass by value, pass by reference</a></H3> +<H3><a name="Allegrocl_nn34">20.3.13 Pass by value, pass by reference</a></H3> <p> @@ -1652,7 +1652,7 @@ opoverload> newly defined types. </p> -<H2><a name="Allegrocl_nn35">19.4 Typemaps</a></H2> +<H2><a name="Allegrocl_nn35">20.4 Typemaps</a></H2> <p> @@ -1663,7 +1663,7 @@ opoverload> on <a href="Typemaps.html#Typemaps">Typemaps</a> for more information. </p> -<H3><a name="Allegrocl_nn36">19.4.1 Code Generation in the C++ Wrapper</a></H3> +<H3><a name="Allegrocl_nn36">20.4.1 Code Generation in the C++ Wrapper</a></H3> @@ -1693,7 +1693,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn37">19.4.1.1 IN Typemap</a></H4> +<H4><a name="Allegrocl_nn37">20.4.1.1 IN Typemap</a></H4> <p> @@ -1728,7 +1728,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn38">19.4.1.2 OUT Typemap</a></H4> +<H4><a name="Allegrocl_nn38">20.4.1.2 OUT Typemap</a></H4> <p> @@ -1752,7 +1752,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn39">19.4.1.3 CTYPE Typemap</a></H4> +<H4><a name="Allegrocl_nn39">20.4.1.3 CTYPE Typemap</a></H4> <p> @@ -1784,7 +1784,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) these <a href="Typemaps.html#Typemaps_nn25">common typemaps</a> here. </p> -<H3><a name="Allegrocl_nn40">19.4.2 Code generation in Lisp wrappers</a></H3> +<H3><a name="Allegrocl_nn40">20.4.2 Code generation in Lisp wrappers</a></H3> <p> @@ -1803,7 +1803,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) <a href="#Allegrocl_nn15">16.3.1 Namespaces</a> for details. </p> -<H4><a name="Allegrocl_nn41">19.4.2.1 LIN Typemap</a></H4> +<H4><a name="Allegrocl_nn41">20.4.2.1 LIN Typemap</a></H4> <p> @@ -1846,7 +1846,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn42">19.4.2.2 LOUT Typemap</a></H4> +<H4><a name="Allegrocl_nn42">20.4.2.2 LOUT Typemap</a></H4> <p> @@ -1889,7 +1889,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn43">19.4.2.3 FFITYPE Typemap</a></H4> +<H4><a name="Allegrocl_nn43">20.4.2.3 FFITYPE Typemap</a></H4> @@ -1939,7 +1939,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn44">19.4.2.4 LISPTYPE Typemap</a></H4> +<H4><a name="Allegrocl_nn44">20.4.2.4 LISPTYPE Typemap</a></H4> <p> @@ -1959,7 +1959,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H4><a name="Allegrocl_nn45">19.4.2.5 LISPCLASS Typemap</a></H4> +<H4><a name="Allegrocl_nn45">20.4.2.5 LISPCLASS Typemap</a></H4> <p> @@ -1983,7 +1983,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H3><a name="Allegrocl_nn46">19.4.3 Modifying SWIG behavior using typemaps</a></H3> +<H3><a name="Allegrocl_nn46">20.4.3 Modifying SWIG behavior using typemaps</a></H3> <p> @@ -2017,10 +2017,10 @@ return-val wrapper-name(parm0, parm1, ..., parmN) </pre> </div> -<H2><a name="Allegrocl_nn47">19.5 Identifier Converter functions</a></H2> +<H2><a name="Allegrocl_nn47">20.5 Identifier Converter functions</a></H2> -<H3><a name="Allegrocl_nn48">19.5.1 Creating symbols in the lisp environment</a></H3> +<H3><a name="Allegrocl_nn48">20.5.1 Creating symbols in the lisp environment</a></H3> <p> @@ -2041,11 +2041,11 @@ return-val wrapper-name(parm0, parm1, ..., parmN) of arguments. </p> -<H3><a name="Allegrocl_nn49">19.5.2 Existing identifier-converter functions</a></H3> +<H3><a name="Allegrocl_nn49">20.5.2 Existing identifier-converter functions</a></H3> <p>Two basic identifier routines have been defined. -<H4><a name="Allegrocl_nn50">19.5.2.1 identifier-convert-null</a></H4> +<H4><a name="Allegrocl_nn50">20.5.2.1 identifier-convert-null</a></H4> <p> @@ -2054,7 +2054,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) strings, from which a symbol will be created. </p> -<H4><a name="Allegrocl_nn51">19.5.2.2 identifier-convert-lispify</a></H4> +<H4><a name="Allegrocl_nn51">20.5.2.2 identifier-convert-lispify</a></H4> <p> @@ -2063,7 +2063,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) same symbol transformations. </p> -<H4><a name="Allegrocl_nn52">19.5.2.3 Default identifier to symbol conversions</a></H4> +<H4><a name="Allegrocl_nn52">20.5.2.3 Default identifier to symbol conversions</a></H4> <p> @@ -2072,7 +2072,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) default naming conventions. </p> -<H3><a name="Allegrocl_nn53">19.5.3 Defining your own identifier-converter</a></H3> +<H3><a name="Allegrocl_nn53">20.5.3 Defining your own identifier-converter</a></H3> <p> @@ -2128,7 +2128,7 @@ indicating the number of arguments passed to the routine indicated by this identifier. </p> -<H3><a name="Allegrocl_nn54">19.5.4 Instructing SWIG to use a particular identifier-converter</a></H3> +<H3><a name="Allegrocl_nn54">20.5.4 Instructing SWIG to use a particular identifier-converter</a></H3> <p> diff --git a/Doc/Manual/Android.html b/Doc/Manual/Android.html index cc11ec26e..894724188 100644 --- a/Doc/Manual/Android.html +++ b/Doc/Manual/Android.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="Android">20 SWIG and Android</a></H1> +<H1><a name="Android">21 SWIG and Android</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -31,7 +31,7 @@ This chapter describes SWIG's support of Android. -<H2><a name="Android_overview">20.1 Overview</a></H2> +<H2><a name="Android_overview">21.1 Overview</a></H2> <p> @@ -41,10 +41,10 @@ Everything in the <a href="Java.html#Java">Java chapter</a> applies to generatin This chapter contains a few Android specific notes and examples. </p> -<H2><a name="Android_examples">20.2 Android examples</a></H2> +<H2><a name="Android_examples">21.2 Android examples</a></H2> -<H3><a name="Android_examples_intro">20.2.1 Examples introduction</a></H3> +<H3><a name="Android_examples_intro">21.2.1 Examples introduction</a></H3> <p> @@ -77,7 +77,7 @@ $ android list targets The following examples are shipped with SWIG under the Examples/android directory and include a Makefile to build and install each example. </p> -<H3><a name="Android_example_simple">20.2.2 Simple C example</a></H3> +<H3><a name="Android_example_simple">21.2.2 Simple C example</a></H3> <p> @@ -399,7 +399,7 @@ Run the app again and this time you will see the output pictured below, showing <center><img src="android-simple.png" alt="Android screenshot of SwigSimple example"></center> -<H3><a name="Android_example_class">20.2.3 C++ class example</a></H3> +<H3><a name="Android_example_class">21.2.3 C++ class example</a></H3> <p> @@ -747,7 +747,7 @@ Run the app to see the result of calling the C++ code from Java: <center><img src="android-class.png" alt="Android screenshot of SwigClass example"></center> -<H3><a name="Android_examples_other">20.2.4 Other examples</a></H3> +<H3><a name="Android_examples_other">21.2.4 Other examples</a></H3> <p> @@ -759,7 +759,7 @@ Note that the 'extend' example is demonstrates the directors feature. Normally C++ exception handling and the STL is not available by default in the version of g++ shipped with Android, but this example turns these features on as described in the next section. </p> -<H2><a name="Android_stl">20.3 C++ STL</a></H2> +<H2><a name="Android_stl">21.3 C++ STL</a></H2> <p> diff --git a/Doc/Manual/CCache.html b/Doc/Manual/CCache.html index 77b54e31a..6923b2e95 100644 --- a/Doc/Manual/CCache.html +++ b/Doc/Manual/CCache.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="CCache">18 Using SWIG with ccache - ccache-swig(1) manpage</a></H1> +<H1><a name="CCache">19 Using SWIG with ccache - ccache-swig(1) manpage</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -35,7 +35,7 @@ <p> -<H2><a name="CCache_nn2">18.1 NAME</a></H2> +<H2><a name="CCache_nn2">19.1 NAME</a></H2> <p> @@ -43,7 +43,7 @@ ccache-swig - a fast compiler cache <p> -<H2><a name="CCache_nn3">18.2 SYNOPSIS</a></H2> +<H2><a name="CCache_nn3">19.2 SYNOPSIS</a></H2> <p> @@ -53,7 +53,7 @@ ccache-swig <compiler> [COMPILER OPTIONS] <p> <compiler> [COMPILER OPTIONS] <p> -<H2><a name="CCache_nn4">18.3 DESCRIPTION</a></H2> +<H2><a name="CCache_nn4">19.3 DESCRIPTION</a></H2> <p> @@ -62,7 +62,7 @@ by caching previous compiles and detecting when the same compile is being done again. ccache-swig is ccache plus support for SWIG. ccache and ccache-swig are used interchangeably in this document. <p> -<H2><a name="CCache_nn5">18.4 OPTIONS SUMMARY</a></H2> +<H2><a name="CCache_nn5">19.4 OPTIONS SUMMARY</a></H2> <p> @@ -82,7 +82,7 @@ Here is a summary of the options to ccache-swig. </pre> <p> -<H2><a name="CCache_nn6">18.5 OPTIONS</a></H2> +<H2><a name="CCache_nn6">19.5 OPTIONS</a></H2> <p> @@ -124,7 +124,7 @@ rounded down to the nearest multiple of 16 kilobytes. <p> </dl> <p> -<H2><a name="CCache_nn7">18.6 INSTALLATION</a></H2> +<H2><a name="CCache_nn7">19.6 INSTALLATION</a></H2> <p> @@ -156,7 +156,7 @@ This will work as long as /usr/local/bin comes before the path to gcc Note! Do not use a hard link, use a symbolic link. A hardlink will cause "interesting" problems. <p> -<H2><a name="CCache_nn8">18.7 EXTRA OPTIONS</a></H2> +<H2><a name="CCache_nn8">19.7 EXTRA OPTIONS</a></H2> <p> @@ -176,7 +176,7 @@ file). By using --ccache-skip you can force an option to not be treated as an input file name and instead be passed along to the compiler as a command line option. <p> -<H2><a name="CCache_nn9">18.8 ENVIRONMENT VARIABLES</a></H2> +<H2><a name="CCache_nn9">19.8 ENVIRONMENT VARIABLES</a></H2> <p> @@ -315,7 +315,7 @@ the use of '#pragma SWIG'. <p> </dl> <p> -<H2><a name="CCache_nn10">18.9 CACHE SIZE MANAGEMENT</a></H2> +<H2><a name="CCache_nn10">19.9 CACHE SIZE MANAGEMENT</a></H2> <p> @@ -328,7 +328,7 @@ When these limits are reached ccache will reduce the cache to 20% below the numbers you specified in order to avoid doing the cache clean operation too often. <p> -<H2><a name="CCache_nn11">18.10 CACHE COMPRESSION</a></H2> +<H2><a name="CCache_nn11">19.10 CACHE COMPRESSION</a></H2> <p> @@ -339,7 +339,7 @@ performance slowdown, it significantly increases the number of files that fit in the cache. You can turn off compression setting the CCACHE_NOCOMPRESS environment variable. <p> -<H2><a name="CCache_nn12">18.11 HOW IT WORKS</a></H2> +<H2><a name="CCache_nn12">19.11 HOW IT WORKS</a></H2> <p> @@ -364,7 +364,7 @@ compiler output that you would get without the cache. If you ever discover a case where ccache changes the output of your compiler then please let me know. <p> -<H2><a name="CCache_nn13">18.12 USING CCACHE WITH DISTCC</a></H2> +<H2><a name="CCache_nn13">19.12 USING CCACHE WITH DISTCC</a></H2> <p> @@ -378,7 +378,7 @@ option. You just need to set the environment variable CCACHE_PREFIX to 'distcc' and ccache will prefix the command line used with the compiler with the command 'distcc'. <p> -<H2><a name="CCache_nn14">18.13 SHARING A CACHE</a></H2> +<H2><a name="CCache_nn14">19.13 SHARING A CACHE</a></H2> <p> @@ -407,7 +407,7 @@ following conditions need to be met: versions of ccache that do not support compression. </ul> <p> -<H2><a name="CCache_nn15">18.14 HISTORY</a></H2> +<H2><a name="CCache_nn15">19.14 HISTORY</a></H2> <p> @@ -423,7 +423,7 @@ I wrote ccache because I wanted to get a bit more speed out of a compiler cache and I wanted to remove some of the limitations of the shell-script version. <p> -<H2><a name="CCache_nn16">18.15 DIFFERENCES FROM COMPILERCACHE</a></H2> +<H2><a name="CCache_nn16">19.15 DIFFERENCES FROM COMPILERCACHE</a></H2> <p> @@ -441,7 +441,7 @@ are: <li> ccache avoids a double call to cpp on a cache miss </ul> <p> -<H2><a name="CCache_nn17">18.16 CREDITS</a></H2> +<H2><a name="CCache_nn17">19.16 CREDITS</a></H2> <p> @@ -453,7 +453,7 @@ Thanks to the following people for their contributions to ccache <li> Paul Russell for many suggestions and the debian packaging </ul> <p> -<H2><a name="CCache_nn18">18.17 AUTHOR</a></H2> +<H2><a name="CCache_nn18">19.17 AUTHOR</a></H2> <p> diff --git a/Doc/Manual/CSharp.html b/Doc/Manual/CSharp.html index e710e66b5..d74707708 100644 --- a/Doc/Manual/CSharp.html +++ b/Doc/Manual/CSharp.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="CSharp">21 SWIG and C#</a></H1> +<H1><a name="CSharp">22 SWIG and C#</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -55,7 +55,7 @@ -<H2><a name="CSharp_introduction">21.1 Introduction</a></H2> +<H2><a name="CSharp_introduction">22.1 Introduction</a></H2> <p> @@ -75,7 +75,7 @@ The <a href="http://msdn.microsoft.com">Microsoft Developer Network (MSDN)</a> h Monodoc, available from the Mono project, has a very useful section titled <a href="http://www.mono-project.com/docs/advanced/pinvoke/">Interop with native libraries</a>. </p> -<H3><a name="CSharp_introduction_swig2_compatibility">21.1.1 SWIG 2 Compatibility</a></H3> +<H3><a name="CSharp_introduction_swig2_compatibility">22.1.1 SWIG 2 Compatibility</a></H3> <p> @@ -83,7 +83,7 @@ In order to minimize name collisions between names generated based on input to S </p> -<H3><a name="CSharp_commandline">21.1.2 Additional command line options</a></H3> +<H3><a name="CSharp_commandline">22.1.2 Additional command line options</a></H3> <p> @@ -135,7 +135,7 @@ Note that the file extension (.cs) will not be automatically added and needs to Due to possible compiler limits it is not advisable to use <tt>-outfile</tt> for large projects. </p> -<H2><a name="CSharp_differences_java">21.2 Differences to the Java module</a></H2> +<H2><a name="CSharp_differences_java">22.2 Differences to the Java module</a></H2> <p> @@ -556,7 +556,7 @@ Windows users can also get the examples working using a <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> environment for automatic configuration of the example makefiles. Any one of the C# compilers (Mono or Microsoft) can be detected from within a Cygwin or Mingw environment if installed in your path. -<H2><a name="CSharp_void_pointers">21.3 Void pointers</a></H2> +<H2><a name="CSharp_void_pointers">22.3 Void pointers</a></H2> <p> @@ -574,7 +574,7 @@ void * f(void *v); </pre> </div> -<H2><a name="CSharp_arrays">21.4 C# Arrays</a></H2> +<H2><a name="CSharp_arrays">22.4 C# Arrays</a></H2> <p> @@ -586,7 +586,7 @@ with one of the following three approaches; namely the SWIG C arrays library, P/ pinned arrays. </p> -<H3><a name="CSharp_arrays_swig_library">21.4.1 The SWIG C arrays library</a></H3> +<H3><a name="CSharp_arrays_swig_library">22.4.1 The SWIG C arrays library</a></H3> <p> @@ -623,7 +623,7 @@ example.print_array(c.cast()); // Pass to C </div> -<H3><a name="CSharp_arrays_pinvoke_default_array_marshalling">21.4.2 Managed arrays using P/Invoke default array marshalling</a></H3> +<H3><a name="CSharp_arrays_pinvoke_default_array_marshalling">22.4.2 Managed arrays using P/Invoke default array marshalling</a></H3> <p> @@ -750,7 +750,7 @@ and intermediary class method </div> -<H3><a name="CSharp_arrays_pinning">21.4.3 Managed arrays using pinning</a></H3> +<H3><a name="CSharp_arrays_pinning">22.4.3 Managed arrays using pinning</a></H3> <p> @@ -845,7 +845,7 @@ public static extern void myArrayCopy(global::System.IntPtr jarg1, global::Syste -<H2><a name="CSharp_exceptions">21.5 C# Exceptions</a></H2> +<H2><a name="CSharp_exceptions">22.5 C# Exceptions</a></H2> <p> @@ -942,7 +942,7 @@ set so should only be used when a C# exception is not created. </p> -<H3><a name="CSharp_exception_example_check_typemap">21.5.1 C# exception example using "check" typemap</a></H3> +<H3><a name="CSharp_exception_example_check_typemap">22.5.1 C# exception example using "check" typemap</a></H3> <p> @@ -1124,7 +1124,7 @@ method and C# code does not handle pending exceptions via the canthrow attribute Actually it will issue this warning for any function beginning with <tt>SWIG_CSharpSetPendingException</tt>. </P> -<H3><a name="CSharp_exception_example_percent_exception">21.5.2 C# exception example using %exception</a></H3> +<H3><a name="CSharp_exception_example_percent_exception">22.5.2 C# exception example using %exception</a></H3> <p> @@ -1189,7 +1189,7 @@ The managed code generated does check for the pending exception as mentioned ear </pre> </div> -<H3><a name="CSharp_exception_example_exception_specifications">21.5.3 C# exception example using exception specifications</a></H3> +<H3><a name="CSharp_exception_example_exception_specifications">22.5.3 C# exception example using exception specifications</a></H3> <p> @@ -1245,7 +1245,7 @@ SWIGEXPORT void SWIGSTDCALL CSharp_evensonly(int jarg1) { Multiple catch handlers are generated should there be more than one exception specifications declared. </p> -<H3><a name="CSharp_custom_application_exception">21.5.4 Custom C# ApplicationException example</a></H3> +<H3><a name="CSharp_custom_application_exception">22.5.4 Custom C# ApplicationException example</a></H3> <p> @@ -1379,7 +1379,7 @@ try { </pre> </div> -<H2><a name="CSharp_directors">21.6 C# Directors</a></H2> +<H2><a name="CSharp_directors">22.6 C# Directors</a></H2> <p> @@ -1392,7 +1392,7 @@ The following sections provide information on the C# director implementation and However, the <a href="Java.html#Java_directors">Java directors</a> section should also be read in order to gain more insight into directors. </p> -<H3><a name="CSharp_directors_example">21.6.1 Directors example</a></H3> +<H3><a name="CSharp_directors_example">22.6.1 Directors example</a></H3> <p> @@ -1513,7 +1513,7 @@ CSharpDerived - UIntMethod(123) </pre> </div> -<H3><a name="CSharp_directors_implementation">21.6.2 Directors implementation</a></H3> +<H3><a name="CSharp_directors_implementation">22.6.2 Directors implementation</a></H3> <p> @@ -1721,7 +1721,7 @@ before SWIG parses the Base class will change all the delegates to <tt>internal< </pre> </div> -<H3><a name="CSharp_director_caveats">21.6.3 Director caveats</a></H3> +<H3><a name="CSharp_director_caveats">22.6.3 Director caveats</a></H3> <p> @@ -1769,7 +1769,7 @@ However, a call from C# to <tt>CSharpDefaults.DefaultMethod()</tt> will of cours should pass the call on to <tt>CSharpDefaults.DefaultMethod(int)</tt>using the C++ default value, as shown above. </p> -<H2><a name="CSharp_multiple_modules">21.7 Multiple modules</a></H2> +<H2><a name="CSharp_multiple_modules">22.7 Multiple modules</a></H2> <p> @@ -1804,7 +1804,7 @@ the <tt>[System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrows if you don't want users to easily stumble upon these so called 'internal workings' of the wrappers. </p> -<H2><a name="CSharp_typemap_examples">21.8 C# Typemap examples</a></H2> +<H2><a name="CSharp_typemap_examples">22.8 C# Typemap examples</a></H2> This section includes a few examples of typemaps. For more examples, you @@ -1812,7 +1812,7 @@ might look at the files "<tt>csharp.swg</tt>" and "<tt>typemaps.i</tt>" in the SWIG library. -<H3><a name="CSharp_memory_management_member_variables">21.8.1 Memory management when returning references to member variables</a></H3> +<H3><a name="CSharp_memory_management_member_variables">22.8.1 Memory management when returning references to member variables</a></H3> <p> @@ -1936,7 +1936,7 @@ public class Bike : global::System.IDisposable { Note the <tt>addReference</tt> call. </p> -<H3><a name="CSharp_memory_management_objects">21.8.2 Memory management for objects passed to the C++ layer</a></H3> +<H3><a name="CSharp_memory_management_objects">22.8.2 Memory management for objects passed to the C++ layer</a></H3> <p> @@ -2068,7 +2068,7 @@ as mentioned earlier, <tt>setElement</tt> is actually: </div> -<H3><a name="CSharp_date_marshalling">21.8.3 Date marshalling using the csin typemap and associated attributes</a></H3> +<H3><a name="CSharp_date_marshalling">22.8.3 Date marshalling using the csin typemap and associated attributes</a></H3> <p> @@ -2354,7 +2354,7 @@ public class example { </pre> </div> -<H3><a name="CSharp_date_properties">21.8.4 A date example demonstrating marshalling of C# properties</a></H3> +<H3><a name="CSharp_date_properties">22.8.4 A date example demonstrating marshalling of C# properties</a></H3> <p> @@ -2454,7 +2454,7 @@ Some points to note: <li>The 'csin' typemap has 'pre', 'post' and 'cshin' attributes, and these are all ignored in the property set. The code in these attributes must instead be replicated within the 'csvarin' typemap. The line creating the <tt>temp$csinput</tt> variable is such an example; it is identical to what is in the 'pre' attribute. </ul> -<H3><a name="CSharp_date_pre_post_directors">21.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a></H3> +<H3><a name="CSharp_date_pre_post_directors">22.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a></H3> <p> @@ -2516,7 +2516,7 @@ Pay special attention to the memory management issues, using these attributes. </p> -<H3><a name="CSharp_partial_classes">21.8.6 Turning proxy classes into partial classes</a></H3> +<H3><a name="CSharp_partial_classes">22.8.6 Turning proxy classes into partial classes</a></H3> <p> @@ -2616,7 +2616,7 @@ demonstrating that the class contains methods calling both unmanaged code - <tt> The following example is an alternative approach to adding managed code to the generated proxy class. </p> -<H3><a name="CSharp_sealed_proxy_class">21.8.7 Turning proxy classes into sealed classes</a></H3> +<H3><a name="CSharp_sealed_proxy_class">22.8.7 Turning proxy classes into sealed classes</a></H3> <p> @@ -2706,7 +2706,7 @@ Either suppress the warning or modify the generated code by copying and tweaking 'csbody' typemap code in csharp.swg by modifying swigCMemOwn to not be protected. </p> -<H3><a name="CSharp_extending_proxy_class">21.8.8 Extending proxy classes with additional C# code</a></H3> +<H3><a name="CSharp_extending_proxy_class">22.8.8 Extending proxy classes with additional C# code</a></H3> <p> @@ -2745,7 +2745,7 @@ public class ExtendMe : global::System.IDisposable { </pre> </div> -<H3><a name="CSharp_enum_underlying_type">21.8.9 Underlying type for enums</a></H3> +<H3><a name="CSharp_enum_underlying_type">22.8.9 Underlying type for enums</a></H3> <P> diff --git a/Doc/Manual/Chicken.html b/Doc/Manual/Chicken.html index bf34ae507..3a80811bd 100644 --- a/Doc/Manual/Chicken.html +++ b/Doc/Manual/Chicken.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Chicken">22 SWIG and Chicken</a></H1> +<H1><a name="Chicken">23 SWIG and Chicken</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -72,7 +72,7 @@ </p> -<H2><a name="Chicken_nn2">22.1 Preliminaries</a></H2> +<H2><a name="Chicken_nn2">23.1 Preliminaries</a></H2> <p> @@ -89,7 +89,7 @@ directory for the basic steps to run SWIG CHICKEN. </p> -<H3><a name="Chicken_nn3">22.1.1 Running SWIG in C mode</a></H3> +<H3><a name="Chicken_nn3">23.1.1 Running SWIG in C mode</a></H3> <p> @@ -122,7 +122,7 @@ object files and linked into your project. </p> -<H3><a name="Chicken_nn4">22.1.2 Running SWIG in C++ mode</a></H3> +<H3><a name="Chicken_nn4">23.1.2 Running SWIG in C++ mode</a></H3> <p> @@ -151,10 +151,10 @@ object files and linked into your project. </p> -<H2><a name="Chicken_nn5">22.2 Code Generation</a></H2> +<H2><a name="Chicken_nn5">23.2 Code Generation</a></H2> -<H3><a name="Chicken_nn6">22.2.1 Naming Conventions</a></H3> +<H3><a name="Chicken_nn6">23.2.1 Naming Conventions</a></H3> <p> @@ -170,7 +170,7 @@ <tt>%rename</tt> SWIG directive in the SWIG interface file. </p> -<H3><a name="Chicken_nn7">22.2.2 Modules</a></H3> +<H3><a name="Chicken_nn7">23.2.2 Modules</a></H3> <p> @@ -192,7 +192,7 @@ (uses <i>modulename</i>))</code> CHICKEN Scheme form. </p> -<H3><a name="Chicken_nn8">22.2.3 Constants and Variables</a></H3> +<H3><a name="Chicken_nn8">23.2.3 Constants and Variables</a></H3> <p> @@ -229,7 +229,7 @@ for info on how to apply the %feature. </p> -<H3><a name="Chicken_nn9">22.2.4 Functions</a></H3> +<H3><a name="Chicken_nn9">23.2.4 Functions</a></H3> <p> @@ -248,7 +248,7 @@ parameters). The return values can then be accessed with <code>(call-with-values)</code>. </p> -<H3><a name="Chicken_nn10">22.2.5 Exceptions</a></H3> +<H3><a name="Chicken_nn10">23.2.5 Exceptions</a></H3> <p>The SWIG chicken module has support for exceptions thrown from @@ -290,7 +290,7 @@ </pre></div> -<H2><a name="Chicken_nn11">22.3 TinyCLOS</a></H2> +<H2><a name="Chicken_nn11">23.3 TinyCLOS</a></H2> <p> @@ -333,7 +333,7 @@ </p> -<H2><a name="Chicken_nn12">22.4 Linkage</a></H2> +<H2><a name="Chicken_nn12">23.4 Linkage</a></H2> <p> @@ -354,7 +354,7 @@ </p> -<H3><a name="Chicken_nn13">22.4.1 Static binary or shared library linked at compile time</a></H3> +<H3><a name="Chicken_nn13">23.4.1 Static binary or shared library linked at compile time</a></H3> <p>We can easily use csc to build a static binary.</p> @@ -395,7 +395,7 @@ in which case the test script does not need to be linked with example.so. The t be run with <tt>csi</tt>. </p> -<H3><a name="Chicken_nn14">22.4.2 Building chicken extension libraries</a></H3> +<H3><a name="Chicken_nn14">23.4.2 Building chicken extension libraries</a></H3> <p>Building a shared library like in the above section only works if the library @@ -453,7 +453,7 @@ distributed and used by anyone, even if SWIG is not installed.</p> <p>See the <tt>Examples/chicken/egg</tt> directory in the SWIG source for an example that builds two eggs, one using the first method and one using the second method.</p> -<H3><a name="Chicken_nn15">22.4.3 Linking multiple SWIG modules with TinyCLOS</a></H3> +<H3><a name="Chicken_nn15">23.4.3 Linking multiple SWIG modules with TinyCLOS</a></H3> <p>Linking together multiple modules that share type information using the <code>%import</code> @@ -477,7 +477,7 @@ with <code>(declare (uses ...))</code>. To create an extension library or an egg, just create a <tt>module_load.scm</tt> file that <code>(declare (uses ...))</code> all the modules.</p> -<H2><a name="Chicken_nn16">22.5 Typemaps</a></H2> +<H2><a name="Chicken_nn16">23.5 Typemaps</a></H2> <p> @@ -486,7 +486,7 @@ all the modules.</p> <code>Lib/chicken/chicken.swg</code>. </p> -<H2><a name="Chicken_nn17">22.6 Pointers</a></H2> +<H2><a name="Chicken_nn17">23.6 Pointers</a></H2> <p> @@ -519,7 +519,7 @@ all the modules.</p> type. flags is either zero or SWIG_POINTER_DISOWN (see below). </p> -<H3><a name="Chicken_collection">22.6.1 Garbage collection</a></H3> +<H3><a name="Chicken_collection">23.6.1 Garbage collection</a></H3> <p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a @@ -550,7 +550,7 @@ all the modules.</p> must be called manually. </p> -<H2><a name="Chicken_nn18">22.7 Unsupported features and known problems</a></H2> +<H2><a name="Chicken_nn18">23.7 Unsupported features and known problems</a></H2> <ul> @@ -560,7 +560,7 @@ all the modules.</p> <a href="SWIGPlus.html#SWIGPlus_default_args">%feature(compactdefaultargs)</a>.</li> </ul> -<H3><a name="Chicken_nn19">22.7.1 TinyCLOS problems with Chicken version <= 1.92</a></H3> +<H3><a name="Chicken_nn19">23.7.1 TinyCLOS problems with Chicken version <= 1.92</a></H3> <p>In Chicken versions equal to or below 1.92, TinyCLOS has a limitation such that generic methods do not properly work on methods diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index 6a2daf9a8..ef99ae55b 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -591,7 +591,51 @@ </div> <!-- INDEX --> -<h3><a href="Warnings.html#Warnings">16 Warning Messages</a></h3> +<h3><a href="Doxygen.html#Doxygen">16 SWIG and Doxygen Translation</a></h3> + +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="Doxygen.html#Doxygen_translation_overview">Doxygen translation overview</a> +<li><a href="Doxygen.html#Doxygen_file_preparation">Preparations</a> +<ul> +<li><a href="Doxygen.html#Doxygen_running_swig">Enabling Doxygen translation</a> +<li><a href="Doxygen.html#Doxygen_features">Doxygen-specific %feature directives</a> +<ul> +<li><a href="Doxygen.html#Doxygen_notranslate">doxygen:notranslate</a> +<li><a href="Doxygen.html#Doxygen_alias">doxygen:alias:<command-name></a> +<li><a href="Doxygen.html#Doxygen_ignore">doxygen:ignore:<command-name></a> +<li><a href="Doxygen.html#Doxygen_nolinktranslate">doxygen:nolinktranslate</a> +<li><a href="Doxygen.html#Doxygen_nostripparams">doxygen:nostripparams</a> +</ul> +<li><a href="Doxygen.html#Doxygen_additional_options">Additional command line options</a> +</ul> +<li><a href="Doxygen.html#Doxygen_to_javadoc">Doxygen to Javadoc</a> +<ul> +<li><a href="Doxygen.html#Doxygen_basic_example">Basic example</a> +<li><a href="Doxygen.html#Doxygen_javadoc_tags">Javadoc tags</a> +<li><a href="Doxygen.html#Doxygen_unsupported_tags">Unsupported tags</a> +<li><a href="Doxygen.html#Doxygen_further_details">Further details</a> +</ul> +<li><a href="Doxygen.html#Doxygen_to_pydoc">Doxygen to Pydoc</a> +<ul> +<li><a href="Doxygen.html#Doxygen_python_basic_example">Basic example</a> +<li><a href="Doxygen.html#Doxygen_pydoc_tags">Pydoc translator</a> +<li><a href="Doxygen.html#Doxygen_python_unsupported_tags">Unsupported tags</a> +<li><a href="Doxygen.html#Doxygen_python_further_details">Further details</a> +</ul> +<li><a href="Doxygen.html#Doxygen_developer_details">Developer information</a> +<ul> +<li><a href="Doxygen.html#Doxygen_translator_design">Doxygen translator design</a> +<li><a href="Doxygen.html#Doxygen_debugging_commands">Debugging the Doxygen parser and translator</a> +<li><a href="Doxygen.html#Doxygen_tests">Tests</a> +</ul> +<li><a href="Doxygen.html#Doxygen_language_extension">Extending to other languages</a> +</ul> +</div> +<!-- INDEX --> + +<h3><a href="Warnings.html#Warnings">17 Warning Messages</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -619,7 +663,7 @@ </div> <!-- INDEX --> -<h3><a href="Modules.html#Modules">17 Working with Modules</a></h3> +<h3><a href="Modules.html#Modules">18 Working with Modules</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -635,7 +679,7 @@ </div> <!-- INDEX --> -<h3><a href="CCache.html#CCache">18 Using SWIG with ccache - ccache-swig(1) manpage</a></h3> +<h3><a href="CCache.html#CCache">19 Using SWIG with ccache - ccache-swig(1) manpage</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -661,7 +705,7 @@ </div> <!-- INDEX --> -<h3><a href="Allegrocl.html#Allegrocl">19 SWIG and Allegro Common Lisp</a></h3> +<h3><a href="Allegrocl.html#Allegrocl">20 SWIG and Allegro Common Lisp</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -745,7 +789,7 @@ </div> <!-- INDEX --> -<h3><a href="Android.html#Android">20 SWIG and Android</a></h3> +<h3><a href="Android.html#Android">21 SWIG and Android</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -763,7 +807,7 @@ </div> <!-- INDEX --> -<h3><a href="CSharp.html#CSharp">21 SWIG and C#</a></h3> +<h3><a href="CSharp.html#CSharp">22 SWIG and C#</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -811,7 +855,7 @@ </div> <!-- INDEX --> -<h3><a href="Chicken.html#Chicken">22 SWIG and Chicken</a></h3> +<h3><a href="Chicken.html#Chicken">23 SWIG and Chicken</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -849,7 +893,7 @@ </div> <!-- INDEX --> -<h3><a href="D.html#D">23 SWIG and D</a></h3> +<h3><a href="D.html#D">24 SWIG and D</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -883,7 +927,7 @@ </div> <!-- INDEX --> -<h3><a href="Go.html#Go">24 SWIG and Go</a></h3> +<h3><a href="Go.html#Go">25 SWIG and Go</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -927,7 +971,7 @@ </div> <!-- INDEX --> -<h3><a href="Guile.html#Guile">25 SWIG and Guile</a></h3> +<h3><a href="Guile.html#Guile">26 SWIG and Guile</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -963,7 +1007,7 @@ </div> <!-- INDEX --> -<h3><a href="Java.html#Java">26 SWIG and Java</a></h3> +<h3><a href="Java.html#Java">27 SWIG and Java</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1117,7 +1161,7 @@ </div> <!-- INDEX --> -<h3><a href="Javascript.html#Javascript">27 SWIG and Javascript</a></h3> +<h3><a href="Javascript.html#Javascript">28 SWIG and Javascript</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1159,7 +1203,7 @@ </div> <!-- INDEX --> -<h3><a href="Lisp.html#Lisp">28 SWIG and Common Lisp</a></h3> +<h3><a href="Lisp.html#Lisp">29 SWIG and Common Lisp</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1182,7 +1226,7 @@ </div> <!-- INDEX --> -<h3><a href="Lua.html#Lua">29 SWIG and Lua</a></h3> +<h3><a href="Lua.html#Lua">30 SWIG and Lua</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1250,7 +1294,7 @@ </div> <!-- INDEX --> -<h3><a href="Modula3.html#Modula3">30 SWIG and Modula-3</a></h3> +<h3><a href="Modula3.html#Modula3">31 SWIG and Modula-3</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1288,7 +1332,7 @@ </div> <!-- INDEX --> -<h3><a href="Mzscheme.html#Mzscheme">31 SWIG and MzScheme/Racket</a></h3> +<h3><a href="Mzscheme.html#Mzscheme">32 SWIG and MzScheme/Racket</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1300,7 +1344,7 @@ </div> <!-- INDEX --> -<h3><a href="Ocaml.html#Ocaml">32 SWIG and Ocaml</a></h3> +<h3><a href="Ocaml.html#Ocaml">33 SWIG and Ocaml</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1351,7 +1395,7 @@ </div> <!-- INDEX --> -<h3><a href="Octave.html#Octave">33 SWIG and Octave</a></h3> +<h3><a href="Octave.html#Octave">34 SWIG and Octave</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1391,7 +1435,7 @@ </div> <!-- INDEX --> -<h3><a href="Perl5.html#Perl5">34 SWIG and Perl5</a></h3> +<h3><a href="Perl5.html#Perl5">35 SWIG and Perl5</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1467,7 +1511,7 @@ </div> <!-- INDEX --> -<h3><a href="Php.html#Php">35 SWIG and PHP</a></h3> +<h3><a href="Php.html#Php">36 SWIG and PHP</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1508,7 +1552,7 @@ </div> <!-- INDEX --> -<h3><a href="Pike.html#Pike">36 SWIG and Pike</a></h3> +<h3><a href="Pike.html#Pike">37 SWIG and Pike</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1532,7 +1576,7 @@ </div> <!-- INDEX --> -<h3><a href="Python.html#Python">37 SWIG and Python</a></h3> +<h3><a href="Python.html#Python">38 SWIG and Python</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1668,7 +1712,7 @@ </div> <!-- INDEX --> -<h3><a href="R.html#R">38 SWIG and R</a></h3> +<h3><a href="R.html#R">39 SWIG and R</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1684,7 +1728,7 @@ </div> <!-- INDEX --> -<h3><a href="Ruby.html#Ruby">39 SWIG and Ruby</a></h3> +<h3><a href="Ruby.html#Ruby">40 SWIG and Ruby</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1822,7 +1866,7 @@ </div> <!-- INDEX --> -<h3><a href="Scilab.html#Scilab">40 SWIG and Scilab</a></h3> +<h3><a href="Scilab.html#Scilab">41 SWIG and Scilab</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1891,7 +1935,7 @@ </div> <!-- INDEX --> -<h3><a href="Tcl.html#Tcl">41 SWIG and Tcl</a></h3> +<h3><a href="Tcl.html#Tcl">42 SWIG and Tcl</a></h3> <!-- INDEX --> <div class="sectiontoc"> @@ -1957,7 +2001,7 @@ </div> <!-- INDEX --> -<h3><a href="Extending.html#Extending">42 Extending SWIG to support new languages</a></h3> +<h3><a href="Extending.html#Extending">43 Extending SWIG to support new languages</a></h3> <!-- INDEX --> <div class="sectiontoc"> diff --git a/Doc/Manual/D.html b/Doc/Manual/D.html index a252650ff..5a6ee8f28 100644 --- a/Doc/Manual/D.html +++ b/Doc/Manual/D.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="D">23 SWIG and D</a></H1> +<H1><a name="D">24 SWIG and D</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -41,7 +41,7 @@ -<H2><a name="D_introduction">23.1 Introduction</a></H2> +<H2><a name="D_introduction">24.1 Introduction</a></H2> <p>From the <a href="http://www.digitalmars.com/d/">D Programming Language</a> web site: <em>D is a systems programming language. Its focus is on combining the power and high performance of C and C++ with the programmer productivity of modern languages like Ruby and Python. [...] The D language is statically typed and compiles directly to machine code.</em> As such, it is not very surprising that D is able to directly <a href="http://www.digitalmars.com/d/1.0/interfaceToC.html">interface with C libraries</a>. Why would a SWIG module for D be needed then in the first place?</p> @@ -53,7 +53,7 @@ <p>To help addressing these issues, the SWIG C# module has been forked to support D. Is has evolved quite a lot since then, but there are still many similarities, so if you do not find what you are looking for on this page, it might be worth having a look at the chapter on <a href="CSharp.html#CSharp">C#</a> (and also on <a href="Java.html#Java">Java</a>, since the C# module was in turn forked from it).</p> -<H2><a name="D_command_line_invocation">23.2 Command line invocation</a></H2> +<H2><a name="D_command_line_invocation">24.2 Command line invocation</a></H2> <p>To activate the D module, pass the <tt>-d</tt> option to SWIG at the command line. The same standard command line switches as with any other language module are available, plus the following D specific ones:</p> @@ -83,10 +83,10 @@ </dl> -<H2><a name="D_typemaps">23.3 Typemaps</a></H2> +<H2><a name="D_typemaps">24.3 Typemaps</a></H2> -<H3><a name="D_typemap_name_comparison">23.3.1 C# <-> D name comparison</a></H3> +<H3><a name="D_typemap_name_comparison">24.3.1 C# <-> D name comparison</a></H3> <p>If you already know the SWIG C# module, you might find the following name comparison table useful:</p> @@ -112,7 +112,7 @@ </pre></div> -<H3><a name="D_ctype_imtype_dtype">23.3.2 ctype, imtype, dtype</a></H3> +<H3><a name="D_ctype_imtype_dtype">24.3.2 ctype, imtype, dtype</a></H3> <p>Mapping of types between the C/C++ library, the C/C++ library wrapper exposing the C functions, the D wrapper module importing these functions and the D proxy code.</p> @@ -120,7 +120,7 @@ <p>The <tt>ctype</tt> typemap is used to determine the types to use in the C wrapper functions. The types from the <tt>imtype</tt> typemap are used in the extern(C) declarations of these functions in the intermediary D module. The <tt>dtype</tt> typemap contains the D types used in the D proxy module/class.</p> -<H3><a name="D_in_out_directorin_direcetorout">23.3.3 in, out, directorin, directorout</a></H3> +<H3><a name="D_in_out_directorin_direcetorout">24.3.3 in, out, directorin, directorout</a></H3> <p>Used for converting between the types for C/C++ and D when generating the code for the wrapper functions (on the C++ side).</p> @@ -130,7 +130,7 @@ <p>The <tt>directorin</tt> typemap is used to convert parameters to the type used in the D director callback function, its return value is processed by <tt>directorout</tt> (see below).</p> -<H3><a name="D_din_dout_ddirectorin_ddirectorout">23.3.4 din, dout, ddirectorin, ddirectorout</a></H3> +<H3><a name="D_din_dout_ddirectorin_ddirectorout">24.3.4 din, dout, ddirectorin, ddirectorout</a></H3> <p>Typemaps for code generation in D proxy and type wrapper classes.</p> @@ -157,13 +157,13 @@ dtype DClass.method(dtype a)</pre></div> -<H3><a name="D_typecheck_typemaps">23.3.5 typecheck typemaps</a></H3> +<H3><a name="D_typecheck_typemaps">24.3.5 typecheck typemaps</a></H3> <p>Because, unlike many scripting languages supported by SWIG, D does not need any dynamic dispatch helper to access an overloaded function, the purpose of these is merely to issue a warning for overloaded C++ functions that cannot be overloaded in D (as more than one C++ type maps to a single D type).</p> -<H3><a name="D_code_injection_typemaps">23.3.6 Code injection typemaps</a></H3> +<H3><a name="D_code_injection_typemaps">24.3.6 Code injection typemaps</a></H3> <p>These typemaps are used for generating the skeleton of proxy classes for C++ types.</p> @@ -178,7 +178,7 @@ Code can also be injected into the D proxy class using <tt>%proxycode</tt>. </p> -<H3><a name="D_special_variables">23.3.7 Special variable macros</a></H3> +<H3><a name="D_special_variables">24.3.7 Special variable macros</a></H3> <p>The standard SWIG special variables are available for use within typemaps as described in the <a href="Typemaps.html#Typemaps">Typemaps documentation</a>, for example <tt>$1</tt>, <tt>$input</tt>, <tt>$result</tt> etc.</p> @@ -299,7 +299,7 @@ $importtype(AnotherInterface) </dl> -<H2><a name="D_features">23.4 D and %feature</a></H2> +<H2><a name="D_features">24.4 D and %feature</a></H2> <p>The D module defines a number of directives which modify the <a href="Customization.html#Customization_features">SWIG features</a> set globally or for a specific declaration:</p> @@ -329,7 +329,7 @@ struct A { </dl> -<H2><a name="D_pragmas">23.5 Pragmas</a></H2> +<H2><a name="D_pragmas">24.5 Pragmas</a></H2> <p>There are a few SWIG pragmas specific to the D module, which you can use to influence the D code SWIG generates:</p> @@ -368,7 +368,7 @@ struct A { </dl> -<H2><a name="D_exceptions">23.6 D Exceptions</a></H2> +<H2><a name="D_exceptions">24.6 D Exceptions</a></H2> <p>Out of the box, C++ exceptions are fundamentally incompatible to their equivalent in the D world and cannot simply be propagated to a calling D method. There is, however, an easy way to solve this problem: Just catch the exception in the C/C++ wrapper layer, pass the contents to D, and make the wrapper code rethrow the exception in the D world.</p> @@ -378,7 +378,7 @@ struct A { <p>As this feature is implemented in exactly the same way it is for C#, please see the <a href="CSharp.html#CSharp_exceptions">C# documentation</a> for a more detailed explanation.</p> -<H2><a name="D_directors">23.7 D Directors</a></H2> +<H2><a name="D_directors">24.7 D Directors</a></H2> <p>When the directors feature is activated, SWIG generates extra code on both the C++ and the D side to enable cross-language polymorphism. Essentially, this means that if you subclass a proxy class in D, C++ code can access any overridden virtual methods just as if you created a derived class in C++.</p> @@ -387,16 +387,16 @@ struct A { </p> -<H2><a name="D_other_features">23.8 Other features</a></H2> +<H2><a name="D_other_features">24.8 Other features</a></H2> -<H3><a name="D_nspace">23.8.1 Extended namespace support (nspace)</a></H3> +<H3><a name="D_nspace">24.8.1 Extended namespace support (nspace)</a></H3> <p>By default, SWIG flattens all C++ namespaces into a single target language namespace, but as for Java and C#, the <a href="SWIGPlus.html#SWIGPlus_nspace"><tt>nspace</tt></a> feature is supported for D. If it is active, C++ namespaces are mapped to D packages/modules. Note, however, that like for the other languages, <em>free</em> variables and functions are not supported yet; currently, they are all allows written to the main proxy D module.</p> -<H3><a name="D_native_pointer_support">23.8.2 Native pointer support</a></H3> +<H3><a name="D_native_pointer_support">24.8.2 Native pointer support</a></H3> <p>Contrary to many of the scripting languages supported by SWIG, D fully supports C-style pointers. The D module thus includes a custom mechanism to wrap C pointers directly as D pointers where applicable, that is, if the type that is pointed to is represented the same in C and D (on the bit-level), dubbed a <em>primitive type</em> below.</p> @@ -408,7 +408,7 @@ struct A { <p>To determine if a type should be considered primitive, the <tt>cprimitive</tt> attribute on its <tt>dtype</tt> attribute is used. For example, the <tt>dtype</tt> typemap for <tt>float</tt> has <tt>cprimitive="1"</tt>, so the code from the <tt>nativepointer</tt> attribute is taken into account e.g. for <tt>float **</tt> or the function pointer <tt>float (*)(float *)</tt>.</p> -<H3><a name="D_operator_overloading">23.8.3 Operator overloading</a></H3> +<H3><a name="D_operator_overloading">24.8.3 Operator overloading</a></H3> <p>The D module comes with basic operator overloading support for both D1 and D2. There are, however, a few limitations arising from conceptual differences between C++ and D:</p> @@ -420,7 +420,7 @@ struct A { <p>There are also some cases where the operators can be translated to D, but the differences in the implementation details are big enough that a rather involved scheme would be required for automatic wrapping them, which has not been implemented yet. This affects, for example, the array subscript operator, <tt>[]</tt>, in combination with assignments - while <tt>operator []</tt> in C++ simply returns a reference which is then written to, D resorts to a separate <tt>opIndexAssign</tt> method -, or implicit casting (which was introduced in D2 via <tt>alias this</tt>). Despite the lack of automatic support, manually handling these cases should be perfectly possible.</p> -<H3><a name="D_test_suite">23.8.4 Running the test-suite</a></H3> +<H3><a name="D_test_suite">24.8.4 Running the test-suite</a></H3> <p>As with any other language, the SWIG test-suite can be built for D using the <tt>*-d-test-suite</tt> targets of the top-level Makefile. By default, D1 is targeted, to build it with D2, use the optional <tt>D_VERSION</tt> variable, e.g. <tt>make check-d-test-suite D_VERSION=2</tt>.</p> @@ -428,14 +428,14 @@ struct A { <p>Note: If you want to use GDC on Linux or another platform which requires you to link <tt>libdl</tt> for dynamically loading the shared library, you might have to add <tt>-ldl</tt> manually to the <tt>d_compile</tt> target in <tt>Examples/Makefile</tt>, because GDC does not currently honor the <tt>pragma(lib, ...)</tt> statement.</p> -<H2><a name="D_typemap_examples">23.9 D Typemap examples</a></H2> +<H2><a name="D_typemap_examples">24.9 D Typemap examples</a></H2> <p>There are no D-specific typemap examples yet. However, with the above <a href="D.html#D_typemap_name_comparison">name comparison table</a>, you should be able to get an idea what can be done by looking at the <a href="CSharp.html#CSharp_typemap_examples">corresponding C# section</a>.</p> -<H2><a name="D_planned_features">23.10 Work in progress and planned features</a></H2> +<H2><a name="D_planned_features">24.10 Work in progress and planned features</a></H2> <p>There are a couple of features which are not implemented yet, but would be very useful and might be added in the near future:</p> diff --git a/Doc/Manual/Doxygen.html b/Doc/Manual/Doxygen.html new file mode 100644 index 000000000..842f146d8 --- /dev/null +++ b/Doc/Manual/Doxygen.html @@ -0,0 +1,1772 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<title>SWIG and Doxygen Translation</title> +<link rel="stylesheet" type="text/css" href="style.css"> +</head> +<body bgcolor="#FFFFFF"> +<H1><a name="Doxygen">16 SWIG and Doxygen Translation</a></H1> +<!-- INDEX --> +<div class="sectiontoc"> +<ul> +<li><a href="#Doxygen_translation_overview">Doxygen translation overview</a> +<li><a href="#Doxygen_file_preparation">Preparations</a> +<ul> +<li><a href="#Doxygen_running_swig">Enabling Doxygen translation</a> +<li><a href="#Doxygen_features">Doxygen-specific %feature directives</a> +<ul> +<li><a href="#Doxygen_notranslate">doxygen:notranslate</a> +<li><a href="#Doxygen_alias">doxygen:alias:<command-name></a> +<li><a href="#Doxygen_ignore">doxygen:ignore:<command-name></a> +<li><a href="#Doxygen_nolinktranslate">doxygen:nolinktranslate</a> +<li><a href="#Doxygen_nostripparams">doxygen:nostripparams</a> +</ul> +<li><a href="#Doxygen_additional_options">Additional command line options</a> +</ul> +<li><a href="#Doxygen_to_javadoc">Doxygen to Javadoc</a> +<ul> +<li><a href="#Doxygen_basic_example">Basic example</a> +<li><a href="#Doxygen_javadoc_tags">Javadoc tags</a> +<li><a href="#Doxygen_unsupported_tags">Unsupported tags</a> +<li><a href="#Doxygen_further_details">Further details</a> +</ul> +<li><a href="#Doxygen_to_pydoc">Doxygen to Pydoc</a> +<ul> +<li><a href="#Doxygen_python_basic_example">Basic example</a> +<li><a href="#Doxygen_pydoc_tags">Pydoc translator</a> +<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_developer_details">Developer information</a> +<ul> +<li><a href="#Doxygen_translator_design">Doxygen translator design</a> +<li><a href="#Doxygen_debugging_commands">Debugging the Doxygen parser and translator</a> +<li><a href="#Doxygen_tests">Tests</a> +</ul> +<li><a href="#Doxygen_language_extension">Extending to other languages</a> +</ul> +</div> +<!-- INDEX --> + + + +<p> +This chapter describes SWIG's support for translating Doxygen comments +found in interface and header files into a target language's normal +documentation language. Currently only Javadoc and Pydoc is +supported. +</p> + +<H2><a name="Doxygen_translation_overview">16.1 Doxygen translation overview</a></H2> + + +<p> +The Doxygen Translation module of SWIG adds an extra layer of +functionality to SWIG, allowing automated translation of <a href= +"http://www.stack.nl/~dimitri/doxygen/">Doxygen</a> formatted comments +from input files into a documentation language more suited for the +target language. Currently this module only translates into Javadoc +and Pydoc for the SWIG Java and Python modules. +Other extensions could be added at a later date. +The Doxygen Translation module originally started as +a <a href="http://code.google.com/soc/2008/">Google Summer of +Code</a> proposal from Summer 2008. +</p> + +<H2><a name="Doxygen_file_preparation">16.2 Preparations</a></H2> + + +<p> +To make use of the comment translation system, your documentation +comments must be in properly formatted <a href= +"http://www.stack.nl/~dimitri/doxygen/">Doxygen.</a> Doxygen comments can be +present in your main SWIG interface file or any header file that it +imports. You are advised to be validate that your comments compile +properly with Doxygen before you try to translate them. Doxygen +itself is a more comprehensive tool and can provide you better feedback for +correcting any syntax errors that may be present. Please look at +Doxygen's <a href= +"http://www.stack.nl/~dimitri/doxygen/docblocks.html"> Documenting the +code</a> for the full comment format specifications. However, SWIG's +Doxygen parser will still report many errors and warnings found +in comments (like unterminated strings or missing ending tags). +</p> + +<p> +Currently, the whole subset of Doxygen comment styles is supported +(See <a href="http://www.stack.nl/~dimitri/doxygen/docblocks.html"> +Documenting the code</a>). Here they are: +</p> + +<div class="code"><pre> +/** + * Javadoc style comment, multiline + */ +/*! + * QT-style comment, multiline + */ +/** + Any of the above, but without intermediate *'s + */ +/// Single-line comment +//! Another single-line comment +</pre></div> + +<p> +Also any of the above with '<' added after comment-starting symbol, +like <i>/**<, /*!<, ///<, </i> or <i> //!<</i> will be +treated as a post-comment and will be assigned to the code before the +comment. + +Any number of '*' or '/' within a Doxygen comment is considered to be a +separator and is not included in the final comment, so you may safely use +comments like <i>/*********/</i> or <i>//////////</i>. +</p> + +<p> +Please note, as SWIG parses the input file by itself with strict grammar, +there is only a limited support for various cases of comment placement +in the file. +</p> +<p> +Comments can be placed before C/C++ expressions on separate lines: +</p> + +<div class="code"><pre> +/** + * Some comment + */ +void someOtherFunction(); +/** + * Some comment + */ +void someFunction(); + +class Shape { + /* + * Calculate the area in cm^2 + */ + int getArea(); +} +</pre></div> + +<p> +After C/C++ expressions at the end of the line: +</p> + +<div class="code"><pre> +int someVariable = 9; ///< This is a var holding magic number 9 +void doNothing(); ///< This does nothing, nop +</pre></div> + +<p> +and in some special cases, like function parameter comments: +</p> + +<div class="code"><pre> +void someFunction( + int a ///< Some parameter + ); +</pre></div> + +<p> +or enum element comments: +</p> + +<div class="code"><pre> +enum E_NUMBERS +{ + EN_ZERO, ///< The first enum item, gets zero as it's value + EN_ONE, ///< The second, EN_ONE=1 + EN_THREE +}; +</pre></div> + +<p> +Currently only comments directly before or after the code items +are supported. Doxygen also supports comments containing structural commands, +where the comments for a code item are not put directly before or after the code item. +These structural commands are stripped out by SWIG and are not assigned to anything. +</p> + +<H3><a name="Doxygen_running_swig">16.2.1 Enabling Doxygen translation</a></H3> + + +<p> +Doxygen comments translation is disabled by default and needs to be explicitly +enabled using the command line <tt>-doxygen</tt> switch for the languages that +do support it (currently Java and Python). +</p> + +<H3><a name="Doxygen_features">16.2.2 Doxygen-specific %feature directives</a></H3> + + +<p> +Translation of Doxygen comments is influenced by the following <a +href="Customization.html#Customization_features">%feature directives</a>: +</p> + +<H4><a name="Doxygen_notranslate">16.2.2.1 doxygen:notranslate</a></H4> + + +<p> +Turns off translation of Doxygen comments to the target language syntax: the +original comment will be copied to the output unchanged. This is useful if you +want to use Doxygen itself to generate documentation for the target language +instead of the corresponding language tool (<tt>javadoc</tt>, <tt>sphinx</tt>, +...). +</p> + + +<H4><a name="Doxygen_alias">16.2.2.2 doxygen:alias:<command-name></a></H4> + + +<p> +Specify an alias for a Doxygen command with the given name. This can be useful +for custom Doxygen commands which can be defined using <tt>ALIASES</tt> option +for Doxygen itself but which are unknown to SWIG. <tt>"command-name"</tt> is the +name of the command in the Doxyfile, e.g. if it contains +</p> + +<div class="code"><pre> +ALIASES = "sideeffect=\par Side Effects:\n" +</pre></div> + +<p> +Then you could also specify the same expansion for SWIG with: +</p> + +<div class="code"><pre> +%feature("doxygen:alias:sideeffect") "\par Side Effects:\n" +</pre></div> + +<p> +Please note that command arguments are not currently supported with this +feature. +</p> + +<p> +Notice that it is perfectly possible and potentially useful to define the alias +expansion differently depending on the target language, e.g. with +</p> + +<div class="code"><pre> +#ifdef SWIGJAVA +%feature("doxygen:alias:not_for_java") "This functionality is not available for Java" +#else +%feature("doxygen:alias:not_for_java") "" +#endif +</pre></div> + +<p> +you could use <tt>@not_for_java</tt> in the documentation comments of all +functions which can't, for whatever reason, be currently exposed in Java +wrappers of the C++ API. +</p> + + +<H4><a name="Doxygen_ignore">16.2.2.3 doxygen:ignore:<command-name></a></H4> + + +<p> +This feature makes it possible to just ignore an unknown Doxygen command, instead of +replacing it with the predefined text that <tt>doxygen:alias</tt> does. +For example, you could use +</p> + +<div class="code"><pre> +%feature("doxygen:ignore:transferfull") Fantastic(); +/** + A fantastic function. + + @transferfull Command ignored, but anything here is still included. + */ +int * Fantastic() { } +</pre></div> + +<p> +if you use a custom Doxygen <tt>transferfull</tt> command to indicate that the +return value ownership is transferred to the caller, as this information doesn't +make much sense for the other languages without explicit ownership management. +</p> + +<p> +Doxygen syntax is rather rich and, in addition to simple commands such as +<tt>@transferfull</tt>, it is also possible to define commands with arguments. +As explained in <a href="http://www.stack.nl/~dimitri/doxygen/manual/commands.html">Doxygen documentation</a>, +the arguments can have a range of a single word, everything until the end of +line or everything until the end of the next paragraph. Currently, only the "end +of line" case is supported using the <tt>range="line"</tt> argument of the +feature directive: +</p> + +<div class="code"><pre> +// Ignore occurrences of +// +// @compileroptions Some special C++ compiler options. +// +// in Doxygen comments as C++ options are not interesting for the target language +// developers. +%feature("doxygen:ignore:compileroptions", range="line") Amazing(); + +/** + An amazing function. + + @compileroptions This function must be compiled with /EHa when using MSVC. + */ +void Amazing(); + +</pre></div> + +<p> +In addition, it is also possible to have custom pairs of begin/end tags, +similarly to the standard Doxygen <tt>@code/@endcode</tt>, for example. Such +tags can also be ignored using the special value of <tt>range</tt> starting with +<tt>end</tt> to indicate that the range is an interval, for example: +</p> + +<div class="code"><pre> +%feature("doxygen:ignore:forcpponly", range="end"); // same as "end:endforcpponly" +/** + An incredible function. + + @forcpponly + This is C++-specific. + @endforcpponly + */ +void Incredible(); +</pre></div> + +<p> +would ignore everything between <tt>@forcpponly</tt> and <tt>@endforcpponly</tt> +commands in Doxygen comments. By default, the name of the end command is the +same as of the start one with "end" prefix, following Doxygen conventions, but +this can be overridden by providing the end command name after the colon. +</p> +<p> +This example shows how custom tags can be used to bracket anything specific to +C++ and prevent it from appearing in the target language documentation. +Conversely, another pair of custom tags could be used to put target language +specific information in the C++ comments. In this case, only the custom tags +themselves should be ignored, but their contents should be parsed as usual and +<tt>contents="parse"</tt> can be used for this: +</p> + +<div class="code"><pre> +%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse"); +/** + A splendid function. + + @beginPythonOnly + This is specific to @b Python. + @endPythonOnly + */ +void Splendid(); + +</pre></div> + +<p> +Putting everything together, if these directives are in effect: +</p> + +<div class="code"><pre> +%feature("doxygen:ignore:transferfull"); +%feature("doxygen:ignore:compileroptions", range="line"); +%feature("doxygen:ignore:forcpponly", range="end"); +%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse"); +</pre></div> + +<p> +then the following C++ Doxygen comment: +</p> + +<div class="code"><pre> +/** + A contrived example of ignoring too many commands in one comment. + + @forcpponly + This is C++-specific. + @endforcpponly + + @beginPythonOnly + This is specific to @b Python. + @endPythonOnly + + @transferfull Command ignored, but anything here is still included. + + @compileroptions This function must be compiled with /EHa when using MSVC. + */ +int * Contrived(); +</pre></div> + +<p> +would be translated to this comment in Python: +</p> + +<div class="code"><pre> +def func(): + r""" + A contrived example of ignoring too many commands in one comment. + + This is specific to **Python**. + + Command ignored, but anything here is still included. + """ + ... +</pre></div> + + +<H4><a name="Doxygen_nolinktranslate">16.2.2.4 doxygen:nolinktranslate</a></H4> + + +<p> +Turn off automatic link-objects translation. +This is only applicable to Java at the moment. +</p> + + +<H4><a name="Doxygen_nostripparams">16.2.2.5 doxygen:nostripparams</a></H4> + + +<p> +Turn off stripping of <tt>@param</tt> and <tt>@tparam</tt> +Doxygen commands if the parameter is not found in the function signature. +This is only applicable to Java at the moment. +</p> + + +<H3><a name="Doxygen_additional_options">16.2.3 Additional command line options</a></H3> + + +<p> +ALSO TO BE ADDED (Javadoc auto brief?) +</p> + +<H2><a name="Doxygen_to_javadoc">16.3 Doxygen to Javadoc</a></H2> + + +<p> +If translation is enabled, Javadoc formatted comments should be +automatically placed in the correct locations in the resulting module +and proxy files. +</p> + +<H3><a name="Doxygen_basic_example">16.3.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--; + }; + double x, y; /*!< Important Variables */ + void move(double dx, double dy); /*!< Moves the Shape */ + virtual double area(void) = 0; /*!< \return the area */ + virtual double perimeter(void) = 0; /*!< \return the perimeter */ + static int nshapes; +}; +</pre></div> + +<p> +Simply running SWIG should result in the following code being present in Shapes.java +</p> + +<div class="targetlang"><pre> + +/** + * This is describing class Shape + * @author Bob + * + */ + +public class Shape { + +... + +/** + * Important Variables + */ + public void setX(double value) { + ShapesJNI.Shape_x_set(swigCPtr, this, value); + } + +/** + * Important Variables + */ + public double getX() { + return ShapesJNI.Shape_x_get(swigCPtr, this); + } + +/** + * Moves the Shape + */ + public void move(double dx, double dy) { + ShapesJNI.Shape_move(swigCPtr, this, dx, dy); + } + +/** + * @return the area + */ + public double area() { + return ShapesJNI.Shape_area(swigCPtr, this); + } + +/** + * @return the perimeter + */ + public double perimeter() { + return ShapesJNI.Shape_perimeter(swigCPtr, this); + } +} + +</pre></div> + +<p> +The code Java-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 Javadoc translator will handle most of the tags conversions (see the +table below). It will also automatically translate link-objects +params, in \see and \link...\endlink commands. For example, +'someFunction(std::string)' will be converted to +'someFunction(String)'. If +you don't want such behaviour, you could turn this off by using the +'doxygen:nolinktranslate' feature. 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> +Javadoc translator features summary +(see <a href="Customization.html#Customization_features">%feature +directives</a>): +</p> + +<H3><a name="Doxygen_javadoc_tags">16.3.2 Javadoc tags</a></H3> + + +<p> +Here is the list of all Doxygen tags and the description of how they are translated to Javadoc +</p> +<div class="diagram"> +<table border="0" summary="Java Doxygen tags"> +<tr> + <th align="left">Doxygen tags</th> +</tr> +<tr> +<td>\a</td> +<td>wrapped with <i> html tag</td> +</tr> +<tr> +<td>\arg</td> +<td>wrapped with <li> html tag</td> +</tr> +<tr> +<td>\author</td> +<td>translated to @author</td> +</tr> +<tr> +<td>\authors</td> +<td>translated to @author</td> +</tr> +<tr> +<td>\b</td> +<td>wrapped with <b> html tag</td> +</tr> +<tr> +<td>\c</td> +<td>wrapped with <code> html tag</td> +</tr> +<tr> +<td>\cite</td> +<td>wrapped with <i> html tag</td> +</tr> +<tr> +<td>\code</td> +<td>translated to {@code ...}</td> +</tr> +<tr> +<td>\cond</td> +<td>translated to 'Conditional comment: <condition>'</td> +</tr> +<tr> +<td>\copyright</td> +<td>replaced with 'Copyright:'</td> +</tr> +<tr> +<td>\deprecated</td> +<td>translated to @deprecated</td> +</tr> +<tr> +<td>\e</td> +<td>wrapped with <i> html tag</td> +</tr> +<tr> +<td>\else</td> +<td>replaced with '}Else:{'</td> +</tr> +<tr> +<td>\elseif</td> +<td>replaced with '}Else if: <condition>{'</td> +</tr> +<tr> +<td>\em</td> +<td>wrapped with <i> html tag</td> +</tr> +<tr> +<td>\endcode</td> +<td>see note for \code</td> +</tr> +<tr> +<td>\endcond</td> +<td>replaced with 'End of conditional comment.'</td> +</tr> +<tr> +<td>\endif</td> +<td>replaced with '}'</td> +</tr> +<tr> +<td>\endlink</td> +<td>see note for \link</td> +</tr> +<tr> +<td>\endverbatim</td> +<td>see note for \verbatim</td> +</tr> +<tr> +<td>\exception</td> +<td>translated to @exception</td> +</tr> +<tr> +<td>\f$, \f[, \f], \f{, \f}</td> +<td>LateX formulas are left unchanged</td> +</tr> +<tr> +<td>\if</td> +<td>replaced with 'If: <condition> {'</td> +</tr> +<tr> +<td>\ifnot</td> +<td>replaced with 'If not: <condition> {'</td> +</tr> +<tr> +<td>\image</td> +<td>translated to <img/> html tag only if target=HTML</td> +</tr> +<tr> +<td>\li</td> +<td>wrapped with <li> html tag</td> +</tr> +<tr> +<td>\link</td> +<td>translated to {@link ...}</td> +</tr> +<tr> +<td>\n</td> +<td>replaced with new line char</td> +</tr> +<tr> +<td>\note</td> +<td>replaced with 'Note:'</td> +</tr> +<tr> +<td>\overload</td> +<td>prints 'This is an overloaded ...' according to Doxygen docs</td> +</tr> +<tr> +<td>\p</td> +<td>wrapped with <code> html tag</td> +</tr> +<tr> +<td>\par</td> +<td>replaced with <p alt='title'>...</p></td> +</tr> +<tr> +<td>\param</td> +<td>translated to @param</td> +</tr> +<tr> +<td>\remark</td> +<td>replaced with 'Remarks:'</td> +</tr> +<tr> +<td>\remarks</td> +<td>replaced with 'Remarks:'</td> +</tr> +<tr> +<td>\result</td> +<td>translated to @return</td> +</tr> +<tr> +<td>\return</td> +<td>translated to @return</td> +</tr> +<tr> +<td>\returns</td> +<td>translated to @return</td> +</tr> +<tr> +<td>\sa</td> +<td>translated to @see</td> +</tr> +<tr> +<td>\see</td> +<td>translated to @see</td> +</tr> +<tr> +<td>\since</td> +<td>translated to @since</td> +</tr> +<tr> +<td>\throw</td> +<td>translated to @throws</td> +</tr> +<tr> +<td>\throws</td> +<td>translated to @throws</td> +</tr> +<tr> +<td>\todo</td> +<td>replaced with 'TODO:'</td> +</tr> +<tr> +<td>\tparam</td> +<td>translated to @param</td> +</tr> +<tr> +<td>\verbatim</td> +<td>translated to {@literal ...}</td> +</tr> +<tr> +<td>\version</td> +<td>translated to @version</td> +</tr> +<tr> +<td>\warning</td> +<td>translated to 'Warning:'</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_unsupported_tags">16.3.3 Unsupported tags</a></H3> + + +<p> +Doxygen has a wealth of tags such as @latexonly that have no +equivalent in Javadoc (all supported tags are listed in +<a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html">Javadoc 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"> +<table border="0" summary="Unsupported Java Doxygen Tags"> +<tr> + <th align="left">Unsupported Doxygen tags</th> +</tr> +<tr> +<td>\addindex</td> +<td>\addtogroup</td> +<td>\anchor</td> +<td>\attention</td> +</tr> +<tr> +<td>\brief</td> +<td>\bug</td> +<td>\callgraph</td> +<td>\callergraph</td> +</tr> +<tr> +<td>\class</td> +<td>\copybrief</td> +<td>\copydetails</td> +<td>\copydoc</td> +</tr> +<tr> +<td>\date</td> +<td>\def</td> +<td>\defgroup</td> +<td>\details</td> +</tr> +<tr> +<td>\dir</td> +<td>\dontinclude</td> +<td>\dot</td> +<td>\dotfile</td> +</tr> +<tr> +<td>\enddot</td> +<td>\endhtmlonly</td> +<td>\endinternal</td> +<td>\endlatexonly</td> +</tr> +<tr> +<td>\endmanonly</td> +<td>\endmsc</td> +<td>\endrtfonly</td> +<td>\endxmlonly</td> +</tr> +<tr> +<td>\enum</td> +<td>\example</td> +<td>\extends</td> +</tr> +<tr> +<td>\file</td> +<td>\fn</td> +<td>\headerfile</td> +<td>\hideinitializer</td> +</tr> +<tr> +<td>\htmlinclude</td> +<td>\htmlonly</td> +<td>\implements</td> +<td>\include</td> +</tr> +<tr> +<td>\includelineno</td> +<td>\ingroup</td> +<td>\internal</td> +<td>\invariant</td> +</tr> +<tr> +<td>\interface</td> +<td>\latexonly</td> +<td>\line</td> +<td>\mainpage</td> +</tr> +<tr> +<td>\manonly</td> +<td>\memberof</td> +<td>\msc</td> +<td>\mscfile</td> +</tr> +<tr> +<td>\name</td> +<td>\namespace</td> +<td>\nosubgrouping</td> +<td>\package</td> +</tr> +<tr> +<td>\page</td> +<td>\paragraph</td> +<td>\post</td> +<td>\pre</td> +</tr> +<tr> +<td>\private</td> +<td>\privatesection</td> +<td>\property</td> +<td>\protected</td> +</tr> +<tr> +<td>\protectedsection</td> +<td>\protocol</td> +<td>\public</td> +<td>\publicsection</td> +</tr> +<tr> +<td>\ref</td> +<td>\related</td> +<td>\relates</td> +<td>\relatedalso</td> +</tr> +<tr> +<td>\relatesalso</td> +<td>\retval</td> +<td>\rtfonly</td> +<td>\section</td> +</tr> +<tr> +<td>\short</td> +<td>\showinitializer</td> +<td>\skip</td> +<td>\skipline</td> +</tr> +<tr> +<td>\snippet</td> +<td>\struct</td> +<td>\subpage</td> +<td>\subsection</td> +</tr> +<tr> +<td>\subsubsection</td> +<td>\tableofcontents</td> +<td>\test</td> +<td>\typedef</td> +</tr> +<tr> +<td>\union</td> +<td>\until</td> +<td>\var</td> +<td>\verbinclude</td> +</tr> +<tr> +<td>\weakgroup</td> +<td>\xmlonly</td> +<td>\xrefitem</td> +<td>\category</td> +</tr> +</table> +</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"> +<table border="0" summary="Ignored Java Doxygen Tags"> +<tr> + <th align="left">Ignored Doxygen tags</th> +</tr> +<tr> +<td>\addtogroup</td> +<td>\callgraph</td> +<td>\callergraph</td> +<td>\category</td> +</tr> +<tr> +<td>\class</td> +<td>\def</td> +<td>\defgroup</td> +<td>\dir</td> +</tr> +<tr> +<td>\enum</td> +<td>\example</td> +<td>\file</td> +<td>\fn</td> +</tr> +<tr> +<td>\headerfile</td> +<td>\hideinitializer</td> +<td>\interface</td> +<td>\internal</td> +</tr> +<tr> +<td>\mainpage</td> +<td>\name</td> +<td>\namespace</td> +<td>\nosubgrouping</td> +</tr> +<tr> +<td>\overload</td> +<td>\package</td> +<td>\page</td> +<td>\property</td> +</tr> +<tr> +<td>\protocol</td> +<td>\relates</td> +<td>\relatesalso</td> +<td>\showinitializer</td> +</tr> +<tr> +<td>\struct</td> +<td>\name</td> +<td>\namespace</td> +<td>\nosubgrouping</td> +</tr> +<tr> +<td>\typedef</td> +<td>\union</td> +<td>\var</td> +<td>\weakgroup</td> +</tr> + +</table> +</div> + + + +<H3><a name="Doxygen_further_details">16.3.4 Further details</a></H3> + + +<p> +TO BE ADDED. +</p> + +<H2><a name="Doxygen_to_pydoc">16.4 Doxygen to Pydoc</a></H2> + + +<p> +If translation is enabled, Pydoc formatted comments should be +automatically placed in the correct locations in the resulting module +and proxy files. The problem is that Pydoc has no tag mechanism like +Doxygen or Javadoc, so most of Doxygen commands are translated by merely +copying the appropriate command text. +</p> + +<H3><a name="Doxygen_python_basic_example">16.4.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--; + }; + double x, y; /*!< Important Variables */ + void move(double dx, double dy); /*!< Moves the Shape */ + virtual double area(void) = 0; /*!< \return the area */ + virtual double perimeter(void) = 0; /*!< \return the perimeter */ + static int nshapes; +}; +</pre></div> + +<p> +Simply running SWIG should result in the following code being present in Shapes.py +</p> + +<div class="targetlang"><pre> + +... + +class Shape(_object): + """ + This is describing class Shape + Authors: + Bob + + """ + + ... + + def move(self, *args): + """ + Moves the Shape + """ + return _Shapes.Shape_move(self, *args) + + def area(self): + """ + Return: + the area + """ + return _Shapes.Shape_area(self) + + def perimeter(self): + """ + Return: + the perimeter + """ + return _Shapes.Shape_perimeter(self) +</pre></div> + +<p> +If any parameters of a function or a method are documented in the Doxygen comment, +their description is copied into the generated output using +<a href="http://sphinx-doc.org/">Sphinx </a> documentation conventions. For example +</p> +<div class="code"><pre> +/** + Set a breakpoint at the given location. + + @param filename The full path to the file. + @param line_number The line number in the file. + */ +bool SetBreakpoint(const char* filename, int line_number); +</pre></div> + +<p> +would be translated to +</p> + +<div class="targetlang"><pre> +def SetBreakpoint(filename, line_number): + r""" + Set a breakpoint at the given location. + + :type filename: string + :param filename: The full path to the file. + :type line_number: int + :param line_number: The line number in the file. + """ +</pre></div> +<p> +The types used for the parameter documentation come from the "doctype" typemap which +is defined for all the primitive types and a few others (e.g. <tt>std::string</tt> and +<tt>shared_ptr<T></tt>) but for non-primitive types is taken to be just the C++ +name of the type with namespace scope delimiters (<tt>::</tt>) replaced with a dot. To +change this, you can define your own typemaps for the custom types, e.g: +</p> +<div class="code"><pre> +%typemap(doctype) MyDate "datetime.date"; +</pre></div> + +<p> +Currently Doxygen comments assigned to global variables and static member variables +are not present in generated code, so they have no comment translated for them. +</p> + +<p> + <b>Whitespace and tables</b> + Whitespace is preserved when translating comments, so it makes + sense to have Doxygen comments formatted in a readable way. This + includes tables, where tags <th>, <td> and </tr>are translated + to '|'. The line after line with <th> tags contains dashes. + If we take care about whitespace, comments in Python are much more + readable. Example: + +<div class="code"><pre> +/** + * <table border = '1'> + * <caption>Animals</caption> + * <tr><th> Column 1 </th><th> Column 2 </th></tr> + * <tr><td> cow </td><td> dog </td></tr> + * <tr><td> cat </td><td> mouse </td></tr> + * <tr><td> horse </td><td> parrot </td></tr> + * </table> + */ +</pre></div> +<p> +translates to Python as: +</p> +<div class="diagram"><pre> + Animals + | Column 1 | Column 2 | + ----------------------- + | cow | dog | + | cat | mouse | + | horse | parrot | +</pre></div> + +<p> + <b>Overloaded functions</b> +Since all the overloaded functions in c++ are wrapped into one Python +function, Pydoc translator will combine every comment of every +overloaded function and put it into the comment for the one wrapper function. +</p> +<p> +If you intend to use resulting generated Python file with the Doxygen docs +generator, rather than Pydoc, you may want to turn off translation +completely (doxygen:notranslate feature). Then SWIG will just copy +the comments to the proxy file and reformat them if needed, but all +the comment content will be left as is. As Doxygen doesn't support +special commands in Python comments +(see <a href="http://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks">Doxygen +docs</a>), you may want to use some tool like doxypy +(<a href="http://code.foosel.org/doxypy">http://code.foosel.org/doxypy</a>) +to do the work. +</p> + +<H3><a name="Doxygen_pydoc_tags">16.4.2 Pydoc translator</a></H3> + + +<p> +Here is the list of all Doxygen tags and the description of how they are translated to Pydoc +</p> +<div class="diagram"> +<table border="0" summary="Python Doxygen tags"> +<tr> + <th align="left">Doxygen tags</th> +</tr> +<tr> +<td>\a</td> +<td>wrapped with '_'</td> +</tr> +<tr> +<td>\arg</td> +<td>prepended with ' --'</td> +</tr> +<tr> +<td>\author</td> +<td>prints 'Author:'</td> +</tr> +<tr> +<td>\authors</td> +<td>prints 'Author:'</td> +</tr> +<tr> +<td>\b</td> +<td>wrapped with '__'</td> +</tr> +<tr> +<td>\cite</td> +<td>wrapped with single quotes</td> +</tr> +<tr> +<td>\cond</td> +<td>translated to 'Conditional comment: <condition>'</td> +</tr> +<tr> +<td>\copyright</td> +<td>prints 'Copyright:'</td> +</tr> +<tr> +<td>\deprecated</td> +<td>prints 'Deprecated:'</td> +</tr> +<tr> +<td>\e</td> +<td>wrapped with '_'</td> +</tr> +<tr> +<td>\else</td> +<td>replaced with '}Else:{'</td> +</tr> +<tr> +<td>\elseif</td> +<td>replaced with '}Else if: <condition>{'</td> +</tr> +<tr> +<td>\em</td> +<td>wrapped with '_'</td> +</tr> +<tr> +<td>\endcond</td> +<td>replaced with 'End of conditional comment.'</td> +</tr> +<tr> +<td>\endif</td> +<td>replaced with '}'</td> +</tr> +<tr> +<td>\exception</td> +<td>replaced with 'Throws:'</td> +</tr> +<tr> +<td>\if</td> +<td>replaced with 'If: <condition> {'</td> +</tr> +<tr> +<td>\ifnot</td> +<td>replaced with 'If not: <condition> {'</td> +</tr> +<tr> +<td>\li</td> +<td>prepended with ' --'</td> +</tr> +<tr> +<td>\n</td> +<td>replaced with new line char</td> +</tr> +<tr> +<td>\note</td> +<td>replaced with 'Note:'</td> +</tr> +<tr> +<td>\overload</td> +<td>prints 'This is an overloaded ...' according to Doxygen docs</td> +</tr> +<tr> +<td>\par</td> +<td>replaced with 'Title: ...'</td> +</tr> +<tr> +<td>\param</td> +<td>translated to 'Arguments:\n param(type) --description'</td> +</tr> +<tr> +<td>\remark</td> +<td>replaced with 'Remarks:'</td> +</tr> +<tr> +<td>\remarks</td> +<td>replaced with 'Remarks:'</td> +</tr> +<tr> +<td>\result</td> +<td>replaced with 'Result:'</td> +</tr> +<tr> +<td>\return</td> +<td>replaced with 'Result:'</td> +</tr> +<tr> +<td>\returns</td> +<td>replaced with 'Result:'</td> +</tr> +<tr> +<td>\sa</td> +<td>replaced with 'See also:'</td> +</tr> +<tr> +<td>\see</td> +<td>replaced with 'See also:'</td> +</tr> +<tr> +<td>\since</td> +<td>replaced with 'Since:'</td> +</tr> +<tr> +<td>\throw</td> +<td>replaced with 'Throws:'</td> +</tr> +<tr> +<td>\throws</td> +<td>replaced wih 'Throws:'</td> +</tr> +<tr> +<td>\todo</td> +<td>replaced with 'TODO:'</td> +</tr> +<tr> +<td>\tparam</td> +<td>translated to 'Arguments:\n param(type) --description'</td> +</tr> +<tr> +<td>\version</td> +<td>replaced with 'Version:'</td> +</tr> +<tr> +<td>\warning</td> +<td>translated to 'Warning:'</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 . character</td> +</tr> +<tr> +<td>\::</td> +<td>prints ::</td> +</tr> +</table> +</div> + +<H3><a name="Doxygen_python_unsupported_tags">16.4.3 Unsupported tags</a></H3> + + +<p> +Doxygen has a wealth of tags such as @latexonly that have no +equivalent in Pydoc. As a result several tags that have no +translation (or particular use, such as some linking and section tags) +are suppressed with their content just printed out (if it has any +sense, typically text content). +Here is the list of these tags: +</p> +<div class="diagram"> +<table border="0" summary="Unsupported Python Doxygen Tags"> +<tr> + <th align="left">Unsupported Doxygen tags</th> +</tr> +<tr> +<td>\addindex</td> +<td>\addtogroup</td> +<td>\anchor</td> +<td>\attention</td> +</tr> +<tr> +<td>\brief</td> +<td>\bug</td> +<td>\callgraph</td> +<td>\callergraph</td> +</tr> +<tr> +<td>\class</td> +<td>\copybrief</td> +<td>\copydetails</td> +<td>\copydoc</td> +</tr> +<tr> +<td>\date</td> +<td>\def</td> +<td>\defgroup</td> +<td>\details</td> +</tr> +<tr> +<td>\dir</td> +<td>\dontinclude</td> +<td>\dot</td> +<td>\dotfile</td> +</tr> +<tr> +<td>\code</td> +<td>\endcode</td> +<td>\endverbatim</td> +<td>\endlink</td> +</tr> +<tr> +<td>\enddot</td> +<td>\endhtmlonly</td> +<td>\endinternal</td> +<td>\endlatexonly</td> +</tr> +<tr> +<td>\endmanonly</td> +<td>\endmsc</td> +<td>\endrtfonly</td> +<td>\endxmlonly</td> +</tr> +<tr> +<td>\enum</td> +<td>\example</td> +<td>\extends</td> +<td>\f$</td> +</tr> +<tr> +<td>\f[</td> +<td>\f]</td> +<td>\f{</td> +<td>\f}</td> +</tr> +<tr> +<td>\file</td> +<td>\fn</td> +<td>\headerfile</td> +<td>\hideinitializer</td> +</tr> +<tr> +<td>\htmlinclude</td> +<td>\htmlonly</td> +<td>\implements</td> +<td>\include</td> +</tr> +<tr> +<td>\image</td> +<td>\link</td> +<td>\verbatim</td> +<td>\p</td> +</tr> +<tr> +<td>\includelineno</td> +<td>\ingroup</td> +<td>\internal</td> +<td>\invariant</td> +</tr> +<tr> +<td>\interface</td> +<td>\latexonly</td> +<td>\line</td> +<td>\mainpage</td> +</tr> +<tr> +<td>\manonly</td> +<td>\memberof</td> +<td>\msc</td> +<td>\mscfile</td> +</tr> +<tr> +<td>\name</td> +<td>\namespace</td> +<td>\nosubgrouping</td> +<td>\package</td> +</tr> +<tr> +<td>\page</td> +<td>\paragraph</td> +<td>\post</td> +<td>\pre</td> +</tr> +<tr> +<td>\private</td> +<td>\privatesection</td> +<td>\property</td> +<td>\protected</td> +</tr> +<tr> +<td>\protectedsection</td> +<td>\protocol</td> +<td>\public</td> +<td>\publicsection</td> +</tr> +<tr> +<td>\ref</td> +<td>\related</td> +<td>\relates</td> +<td>\relatedalso</td> +</tr> +<tr> +<td>\relatesalso</td> +<td>\retval</td> +<td>\rtfonly</td> +<td>\section</td> +</tr> +<tr> +<td>\short</td> +<td>\showinitializer</td> +<td>\skip</td> +<td>\skipline</td> +</tr> +<tr> +<td>\snippet</td> +<td>\struct</td> +<td>\subpage</td> +<td>\subsection</td> +</tr> +<tr> +<td>\subsubsection</td> +<td>\tableofcontents</td> +<td>\test</td> +<td>\typedef</td> +</tr> +<tr> +<td>\union</td> +<td>\until</td> +<td>\var</td> +<td>\verbinclude</td> +</tr> +<tr> +<td>\weakgroup</td> +<td>\xmlonly</td> +<td>\xrefitem</td> +<td>\category</td> +</tr> +<tr> +<td>\c</td> +</tr> +</table> +</div> + +<H3><a name="Doxygen_python_further_details">16.4.4 Further details</a></H3> + + +<p> +TO BE ADDED. +</p> + +<H2><a name="Doxygen_developer_details">16.5 Developer information</a></H2> + + +<p> +This section contains information for developers enhancing the Doxygen translator. +</p> + +<H3><a name="Doxygen_translator_design">16.5.1 Doxygen translator design</a></H3> + + +<p> +If this functionality is turned on, SWIG places all comments found +into the SWIG parse tree. Nodes contain an additional attribute +called <tt>doxygen</tt> when a comment is present. Individual nodes +containing Doxygen with Structural Indicators, such as @file, as their +first command, are also present in the parse tree. These individual +"blobs" of Doxygen such as : +</p> +<div class="code"><pre> +/*! This is describing function Foo + \param x some random variable + \author Bob + \return Foo + */ +</pre></div> + +<p> +are passed on individually to the Doxygen Translator module. This +module builds its own private parse tree and hands it to a separate +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">16.5.2 Debugging the Doxygen parser and translator</a></H3> + + +<p> +There are two handy command line switches, that enable lots of +detailed debug information printing. +</p> + +<div class="shell"><pre> + -debug-doxygen-parser - Display Doxygen parser module debugging information + -debug-doxygen-translator - Display Doxygen translator module debugging information +</pre></div> + +<H3><a name="Doxygen_tests">16.5.3 Tests</a></H3> + + +<p> +Doxygen tests have been added to the regular SWIG test-suite. +There are a number of tests beginning <tt>doxygen_</tt> in the Examples/test-suite sub-directory. +</p> + +<p> +Like any other SWIG test case, the tests are included in Examples/test-suite/common.mk and can be tested with +commands like <tt>make check-test-suite</tt> or <tt>make check-python-test-suite</tt>. +To run them individually, type +<tt>make -s <testname>.cpptest</tt> in the language-specific sub-directory in +<tt>Examples/test-suite</tt> directory. For example: +</p> + +<div class="shell"><pre> + Examples/test-suite/java $ make -s doxygen_parsing.cpptest +</pre></div> + +<p> +If the test fails, both expected and translated comments are printed to +std out, but also written to files <i>expected.txt</i> +and <i>got.txt</i>. Since it is often difficult to find a single +character difference in several lines of text, we can use some diff +tool, for example: +</p> + +<div class="shell"><pre> + 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 +environment variable defined and pointing to the JDK location. +</p> +<p> +The Java's comment parsing code (the testing part) is located in commentParser.java. +It checks the generated code. It is possible +to run this file as a stand-alone program, with <tt>java commentParser <some java package></tt>, +and it will print the list of comments found in the specified directory (in the format it has used +in the runtime tests). So, when you want to create a new Doxygen test case, +just copy an existing one and replace the actual comment content (section of entries in +form 'wantedComments.put(...)' with the output of the above command. +</p> +<p> +Runtime tests in Python are just plain string comparisons of the __doc__ +properties. +</p> + +<H2><a name="Doxygen_language_extension">16.6 Extending to other languages</a></H2> + + +<p> +In general, an extension to another language requires a fairly deep understanding of the target language module, such as Modules/python.cxx for Python. +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. +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. +The other half of extension is building a target documentation language comment generator that handles one blob at a time. +However, this is relatively simple and nowhere near as complex as the wrapper generating modules in SWIG. +See Source/Doxygen/javadoc.cxx for a good example. +The target language module passes the Doxygen Translator the blob to translate, and receives back the translated text. +</p> +<p> +<b> What is given to the Doxygen Translator</b> +</p> +<div class="code"><pre> +/*! This is describing function Foo + \param x some random variable + \author Bob + \return Foo + */ +</pre></div> +<p> +<b> What is received back by java.cxx </b> +</p> +<div class="targetlang"><pre> +/** This is describing function Foo + * + * @param x some random variable + * @author Bob + * @return Foo + */ +</pre></div> +<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. +</p> + +</body> +</html> diff --git a/Doc/Manual/Extending.html b/Doc/Manual/Extending.html index f752ebbdc..9d69ac2d1 100644 --- a/Doc/Manual/Extending.html +++ b/Doc/Manual/Extending.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Extending">42 Extending SWIG to support new languages</a></H1> +<H1><a name="Extending">43 Extending SWIG to support new languages</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -76,7 +76,7 @@ -<H2><a name="Extending_nn2">42.1 Introduction</a></H2> +<H2><a name="Extending_nn2">43.1 Introduction</a></H2> <p> @@ -92,7 +92,7 @@ Also, this chapter is not meant to be a hand-holding tutorial. As a starting po you should probably look at one of SWIG's existing modules. </p> -<H2><a name="Extending_nn3">42.2 Prerequisites</a></H2> +<H2><a name="Extending_nn3">43.2 Prerequisites</a></H2> <p> @@ -122,7 +122,7 @@ obvious, but almost all SWIG directives as well as the low-level generation of wrapper code are driven by C++ datatypes. </p> -<H2><a name="Extending_nn4">42.3 The Big Picture</a></H2> +<H2><a name="Extending_nn4">43.3 The Big Picture</a></H2> <p> @@ -159,7 +159,7 @@ role in making the system work. For example, both typemaps and declaration anno based on pattern matching and interact heavily with the underlying type system. </p> -<H2><a name="Extending_nn5">42.4 Execution Model</a></H2> +<H2><a name="Extending_nn5">43.4 Execution Model</a></H2> <p> @@ -204,7 +204,7 @@ latter stage of compilation. The next few sections briefly describe some of these stages. </p> -<H3><a name="Extending_nn6">42.4.1 Preprocessing</a></H3> +<H3><a name="Extending_nn6">43.4.1 Preprocessing</a></H3> <p> @@ -285,7 +285,7 @@ been expanded as well as everything else that goes into the low-level construction of the wrapper code. </p> -<H3><a name="Extending_nn7">42.4.2 Parsing</a></H3> +<H3><a name="Extending_nn7">43.4.2 Parsing</a></H3> <p> @@ -386,7 +386,7 @@ returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as arguments). </p> -<H3><a name="Extending_nn8">42.4.3 Parse Trees</a></H3> +<H3><a name="Extending_nn8">43.4.3 Parse Trees</a></H3> <p> @@ -641,7 +641,7 @@ $ swig -c++ -python -debug-module 4 example.i </pre> </div> -<H3><a name="Extending_nn9">42.4.4 Attribute namespaces</a></H3> +<H3><a name="Extending_nn9">43.4.4 Attribute namespaces</a></H3> <p> @@ -660,7 +660,7 @@ that matches the name of the target language. For example, <tt>python:foo</tt> <tt>perl:foo</tt>. </p> -<H3><a name="Extending_nn10">42.4.5 Symbol Tables</a></H3> +<H3><a name="Extending_nn10">43.4.5 Symbol Tables</a></H3> <p> @@ -751,7 +751,7 @@ example.i:5. Previous declaration is foo_i(int ) </pre> </div> -<H3><a name="Extending_nn11">42.4.6 The %feature directive</a></H3> +<H3><a name="Extending_nn11">43.4.6 The %feature directive</a></H3> <p> @@ -807,7 +807,7 @@ For example, the exception code above is simply stored without any modifications. </p> -<H3><a name="Extending_nn12">42.4.7 Code Generation</a></H3> +<H3><a name="Extending_nn12">43.4.7 Code Generation</a></H3> <p> @@ -929,7 +929,7 @@ public : The role of these functions is described shortly. </p> -<H3><a name="Extending_nn13">42.4.8 SWIG and XML</a></H3> +<H3><a name="Extending_nn13">43.4.8 SWIG and XML</a></H3> <p> @@ -942,7 +942,7 @@ internal data structures, it may be useful to keep XML in the back of your mind as a model. </p> -<H2><a name="Extending_nn14">42.5 Primitive Data Structures</a></H2> +<H2><a name="Extending_nn14">43.5 Primitive Data Structures</a></H2> <p> @@ -988,7 +988,7 @@ typedef Hash Typetab; </pre> </div> -<H3><a name="Extending_nn15">42.5.1 Strings</a></H3> +<H3><a name="Extending_nn15">43.5.1 Strings</a></H3> <p> @@ -1129,7 +1129,7 @@ Returns the number of replacements made (if any). </div> -<H3><a name="Extending_nn16">42.5.2 Hashes</a></H3> +<H3><a name="Extending_nn16">43.5.2 Hashes</a></H3> <p> @@ -1206,7 +1206,7 @@ Returns the list of hash table keys. </div> -<H3><a name="Extending_nn17">42.5.3 Lists</a></H3> +<H3><a name="Extending_nn17">43.5.3 Lists</a></H3> <p> @@ -1295,7 +1295,7 @@ If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt> and is used to create a String object. </div> -<H3><a name="Extending_nn18">42.5.4 Common operations</a></H3> +<H3><a name="Extending_nn18">43.5.4 Common operations</a></H3> The following operations are applicable to all datatypes. @@ -1350,7 +1350,7 @@ objects and report errors. Gets the line number associated with <tt>x</tt>. </div> -<H3><a name="Extending_nn19">42.5.5 Iterating over Lists and Hashes</a></H3> +<H3><a name="Extending_nn19">43.5.5 Iterating over Lists and Hashes</a></H3> To iterate over the elements of a list or a hash table, the following functions are used: @@ -1395,7 +1395,7 @@ for (j = First(j); j.item; j= Next(j)) { </div> -<H3><a name="Extending_nn20">42.5.6 I/O</a></H3> +<H3><a name="Extending_nn20">43.5.6 I/O</a></H3> Special I/O functions are used for all internal I/O. These operations @@ -1529,7 +1529,7 @@ Printf(f, "%s\n", s); Similarly, the preprocessor and parser all operate on string-files. </p> -<H2><a name="Extending_nn21">42.6 Navigating and manipulating parse trees</a></H2> +<H2><a name="Extending_nn21">43.6 Navigating and manipulating parse trees</a></H2> Parse trees are built as collections of hash tables. Each node is a hash table in which @@ -1663,7 +1663,7 @@ Deletes a node from the parse tree. Deletion reconnects siblings and properly u the parent so that sibling nodes are unaffected. </div> -<H2><a name="Extending_nn22">42.7 Working with attributes</a></H2> +<H2><a name="Extending_nn22">43.7 Working with attributes</a></H2> <p> @@ -1780,7 +1780,7 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after function. </div> -<H2><a name="Extending_nn23">42.8 Type system</a></H2> +<H2><a name="Extending_nn23">43.8 Type system</a></H2> <p> @@ -1789,7 +1789,7 @@ pointers, references, and pointers to members. A detailed discussion of type theory is impossible here. However, let's cover the highlights. </p> -<H3><a name="Extending_nn24">42.8.1 String encoding of types</a></H3> +<H3><a name="Extending_nn24">43.8.1 String encoding of types</a></H3> <p> @@ -1890,7 +1890,7 @@ make the final type, the two parts are just joined together using string concatenation. </p> -<H3><a name="Extending_nn25">42.8.2 Type construction</a></H3> +<H3><a name="Extending_nn25">43.8.2 Type construction</a></H3> <p> @@ -2059,7 +2059,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is <tt>ty</tt> is unmodified. </div> -<H3><a name="Extending_nn26">42.8.3 Type tests</a></H3> +<H3><a name="Extending_nn26">43.8.3 Type tests</a></H3> <p> @@ -2146,7 +2146,7 @@ Checks if <tt>ty</tt> is a varargs type. Checks if <tt>ty</tt> is a templatized type. </div> -<H3><a name="Extending_nn27">42.8.4 Typedef and inheritance</a></H3> +<H3><a name="Extending_nn27">43.8.4 Typedef and inheritance</a></H3> <p> @@ -2248,7 +2248,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype will consist only of primitive typenames. </div> -<H3><a name="Extending_nn28">42.8.5 Lvalues</a></H3> +<H3><a name="Extending_nn28">43.8.5 Lvalues</a></H3> <p> @@ -2285,7 +2285,7 @@ Literal y; // type = 'Literal', ltype='p.char' </pre> </div> -<H3><a name="Extending_nn29">42.8.6 Output functions</a></H3> +<H3><a name="Extending_nn29">43.8.6 Output functions</a></H3> <p> @@ -2347,7 +2347,7 @@ SWIG, but is most commonly associated with type-descriptor objects that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>). </div> -<H2><a name="Extending_nn30">42.9 Parameters</a></H2> +<H2><a name="Extending_nn30">43.9 Parameters</a></H2> <p> @@ -2446,7 +2446,7 @@ included. Used to emit prototypes. Returns the number of required (non-optional) arguments in <tt>p</tt>. </div> -<H2><a name="Extending_nn31">42.10 Writing a Language Module</a></H2> +<H2><a name="Extending_nn31">43.10 Writing a Language Module</a></H2> <p> @@ -2461,7 +2461,7 @@ describes the creation of a minimal Python module. You should be able to extra this to other languages. </p> -<H3><a name="Extending_nn32">42.10.1 Execution model</a></H3> +<H3><a name="Extending_nn32">43.10.1 Execution model</a></H3> <p> @@ -2471,7 +2471,7 @@ the parsing of command line options, all aspects of code generation are controll different methods of the <tt>Language</tt> that must be defined by your module. </p> -<H3><a name="Extending_starting_out">42.10.2 Starting out</a></H3> +<H3><a name="Extending_starting_out">43.10.2 Starting out</a></H3> <p> @@ -2579,7 +2579,7 @@ that activates your module. For example, <tt>swig -python foo.i</tt>. The messages from your new module should appear. </p> -<H3><a name="Extending_nn34">42.10.3 Command line options</a></H3> +<H3><a name="Extending_nn34">43.10.3 Command line options</a></H3> <p> @@ -2638,7 +2638,7 @@ to mark the option as valid. If you forget to do this, SWIG will terminate wit unrecognized command line option error. </p> -<H3><a name="Extending_nn35">42.10.4 Configuration and preprocessing</a></H3> +<H3><a name="Extending_nn35">43.10.4 Configuration and preprocessing</a></H3> <p> @@ -2687,7 +2687,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file <tt>python.swg</tt>. </p> -<H3><a name="Extending_nn36">42.10.5 Entry point to code generation</a></H3> +<H3><a name="Extending_nn36">43.10.5 Entry point to code generation</a></H3> <p> @@ -2745,7 +2745,7 @@ int Python::top(Node *n) { </pre> </div> -<H3><a name="Extending_nn37">42.10.6 Module I/O and wrapper skeleton</a></H3> +<H3><a name="Extending_nn37">43.10.6 Module I/O and wrapper skeleton</a></H3> <!-- please report bugs in this section to mgossage --> @@ -2893,7 +2893,7 @@ functionWrapper : void Shape_y_set(Shape *self, double y) </pre> </div> -<H3><a name="Extending_nn38">42.10.7 Low-level code generators</a></H3> +<H3><a name="Extending_nn38">43.10.7 Low-level code generators</a></H3> <!-- please report bugs in this section to mgossage --> @@ -3047,7 +3047,7 @@ but without the typemaps, there is still work to do. </p> -<H3><a name="Extending_configuration_files">42.10.8 Configuration files</a></H3> +<H3><a name="Extending_configuration_files">43.10.8 Configuration files</a></H3> <!-- please report bugs in this section to ttn --> @@ -3191,7 +3191,7 @@ politely displays the ignoring language message. </dl> -<H3><a name="Extending_nn40">42.10.9 Runtime support</a></H3> +<H3><a name="Extending_nn40">43.10.9 Runtime support</a></H3> <p> @@ -3200,7 +3200,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g. the SWIG files that implement those functions. </p> -<H3><a name="Extending_nn41">42.10.10 Standard library files</a></H3> +<H3><a name="Extending_nn41">43.10.10 Standard library files</a></H3> <p> @@ -3219,7 +3219,7 @@ The following are the minimum that are usually supported: Please copy these and modify for any new language. </p> -<H3><a name="Extending_nn42">42.10.11 User examples</a></H3> +<H3><a name="Extending_nn42">43.10.11 User examples</a></H3> <p> @@ -3248,7 +3248,7 @@ during this process, see the section on <a href="#Extending_configuration_files" files</a>. </p> -<H3><a name="Extending_test_suite">42.10.12 Test driven development and the test-suite</a></H3> +<H3><a name="Extending_test_suite">43.10.12 Test driven development and the test-suite</a></H3> <p> @@ -3307,7 +3307,7 @@ It is therefore essential that the runtime tests are written in a manner that di but error/exception out with an error message on stderr on failure. </p> -<H4><a name="Extending_running_test_suite">42.10.12.1 Running the test-suite</a></H4> +<H4><a name="Extending_running_test_suite">43.10.12.1 Running the test-suite</a></H4> <p> @@ -3499,7 +3499,7 @@ It can be run in the same way as the other language test-suites, replacing [lang The test cases used and the way it works is described in <tt>Examples/test-suite/errors/Makefile.in</tt>. </p> -<H3><a name="Extending_nn43">42.10.13 Documentation</a></H3> +<H3><a name="Extending_nn43">43.10.13 Documentation</a></H3> <p> @@ -3531,7 +3531,7 @@ Some topics that you'll want to be sure to address include: if available. </ul> -<H3><a name="Extending_prerequisites">42.10.14 Prerequisites for adding a new language module to the SWIG distribution</a></H3> +<H3><a name="Extending_prerequisites">43.10.14 Prerequisites for adding a new language module to the SWIG distribution</a></H3> <p> @@ -3588,7 +3588,7 @@ should be added should there be an area not already covered by the existing tests. </p> -<H3><a name="Extending_coding_style_guidelines">42.10.15 Coding style guidelines</a></H3> +<H3><a name="Extending_coding_style_guidelines">43.10.15 Coding style guidelines</a></H3> <p> @@ -3612,7 +3612,7 @@ The generated C/C++ code should also follow this style as close as possible. How should be avoided as unlike the SWIG developers, users will never have consistent tab settings. </p> -<H2><a name="Extending_debugging_options">42.11 Debugging Options</a></H2> +<H2><a name="Extending_debugging_options">43.11 Debugging Options</a></H2> <p> @@ -3639,7 +3639,7 @@ There are various command line options which can aid debugging a SWIG interface The complete list of command line options for SWIG are available by running <tt>swig -help</tt>. </p> -<H2><a name="Extending_nn46">42.12 Guide to parse tree nodes</a></H2> +<H2><a name="Extending_nn46">43.12 Guide to parse tree nodes</a></H2> <p> @@ -4047,7 +4047,7 @@ extern "X" { ... } declaration. </pre> </div> -<H2><a name="Extending_further_info">42.13 Further Development Information</a></H2> +<H2><a name="Extending_further_info">43.13 Further Development Information</a></H2> <p> diff --git a/Doc/Manual/Go.html b/Doc/Manual/Go.html index 4a60e45e0..3b8d872ae 100644 --- a/Doc/Manual/Go.html +++ b/Doc/Manual/Go.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="Go">24 SWIG and Go</a></H1> +<H1><a name="Go">25 SWIG and Go</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -57,7 +57,7 @@ the Go programming language see <a href="http://golang.org/">golang.org</a>. </p> -<H2><a name="Go_overview">24.1 Overview</a></H2> +<H2><a name="Go_overview">25.1 Overview</a></H2> <p> @@ -86,7 +86,7 @@ type-safe as well. In case of type issues the build will fail and hence SWIG's are not used. </p> -<H2><a name="Go_examples">24.2 Examples</a></H2> +<H2><a name="Go_examples">25.2 Examples</a></H2> <p> @@ -101,7 +101,7 @@ SWIG interface file extension for backwards compatibility with Go 1. </p> -<H2><a name="Go_running_swig">24.3 Running SWIG with Go</a></H2> +<H2><a name="Go_running_swig">25.3 Running SWIG with Go</a></H2> <p> @@ -181,7 +181,7 @@ sequence for this approach would look like this: </pre></div> -<H3><a name="Go_commandline">24.3.1 Go-specific Commandline Options</a></H3> +<H3><a name="Go_commandline">25.3.1 Go-specific Commandline Options</a></H3> <p> @@ -264,7 +264,7 @@ swig -go -help </table> -<H3><a name="Go_outputs">24.3.2 Generated Wrapper Files</a></H3> +<H3><a name="Go_outputs">25.3.2 Generated Wrapper Files</a></H3> <p>There are two different approaches to generating wrapper files, @@ -308,7 +308,7 @@ combined with the compiled MODULE.go using go tool pack. </ul> -<H2><a name="Go_basic_tour">24.4 A tour of basic C/C++ wrapping</a></H2> +<H2><a name="Go_basic_tour">25.4 A tour of basic C/C++ wrapping</a></H2> <p> @@ -318,7 +318,7 @@ modifications have to occur. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Go_package">24.4.1 Go Package Name</a></H3> +<H3><a name="Go_package">25.4.1 Go Package Name</a></H3> <p> @@ -328,7 +328,7 @@ directive. You may override this by using SWIG's <tt>-package</tt> command line option. </p> -<H3><a name="Go_names">24.4.2 Go Names</a></H3> +<H3><a name="Go_names">25.4.2 Go Names</a></H3> <p> @@ -360,7 +360,7 @@ followed by that name, and the destructor will be named <tt>Delete</tt> followed by that name. </p> -<H3><a name="Go_constants">24.4.3 Go Constants</a></H3> +<H3><a name="Go_constants">25.4.3 Go Constants</a></H3> <p> @@ -368,7 +368,7 @@ C/C++ constants created via <tt>#define</tt> or the <tt>%constant</tt> directive become Go constants, declared with a <tt>const</tt> declaration. -<H3><a name="Go_enumerations">24.4.4 Go Enumerations</a></H3> +<H3><a name="Go_enumerations">25.4.4 Go Enumerations</a></H3> <p> @@ -378,7 +378,7 @@ usual). The values of the enumeration will become variables in Go; code should avoid modifying those variables. </p> -<H3><a name="Go_classes">24.4.5 Go Classes</a></H3> +<H3><a name="Go_classes">25.4.5 Go Classes</a></H3> <p> @@ -456,7 +456,7 @@ returns a go interface. If the returned pointer can be null, you can check for this by calling the Swigcptr() method. </p> -<H4><a name="Go_class_memory">24.4.5.1 Go Class Memory Management</a></H4> +<H4><a name="Go_class_memory">25.4.5.1 Go Class Memory Management</a></H4> <p> @@ -578,7 +578,7 @@ func (o *GoClassName) Close() { </pre> </div> -<H4><a name="Go_class_inheritance">24.4.5.2 Go Class Inheritance</a></H4> +<H4><a name="Go_class_inheritance">25.4.5.2 Go Class Inheritance</a></H4> <p> @@ -590,7 +590,7 @@ Doing the reverse will require an explicit type assertion, which will be checked dynamically. </p> -<H3><a name="Go_templates">24.4.6 Go Templates</a></H3> +<H3><a name="Go_templates">25.4.6 Go Templates</a></H3> <p> @@ -599,7 +599,7 @@ wrappers for a particular template instantation. To do this, use the <tt>%template</tt> directive. -<H3><a name="Go_director_classes">24.4.7 Go Director Classes</a></H3> +<H3><a name="Go_director_classes">25.4.7 Go Director Classes</a></H3> <p> @@ -617,7 +617,7 @@ completely to avoid common pitfalls with directors in Go. </p> -<H4><a name="Go_director_example_cpp_code">24.4.7.1 Example C++ code</a></H4> +<H4><a name="Go_director_example_cpp_code">25.4.7.1 Example C++ code</a></H4> <p> @@ -689,7 +689,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>. </p> -<H4><a name="Go_director_enable">24.4.7.2 Enable director feature</a></H4> +<H4><a name="Go_director_enable">25.4.7.2 Enable director feature</a></H4> <p> @@ -724,7 +724,7 @@ documentation on directors. </p> -<H4><a name="Go_director_ctor_dtor">24.4.7.3 Constructor and destructor</a></H4> +<H4><a name="Go_director_ctor_dtor">25.4.7.3 Constructor and destructor</a></H4> <p> @@ -777,7 +777,7 @@ embedding</a>. </p> -<H4><a name="Go_director_overriding">24.4.7.4 Override virtual methods</a></H4> +<H4><a name="Go_director_overriding">25.4.7.4 Override virtual methods</a></H4> <p> @@ -843,7 +843,7 @@ the Go methods. </p> -<H4><a name="Go_director_base_methods">24.4.7.5 Call base methods</a></H4> +<H4><a name="Go_director_base_methods">25.4.7.5 Call base methods</a></H4> <p> @@ -880,7 +880,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>. </p> -<H4><a name="Go_director_subclass">24.4.7.6 Subclass via embedding</a></H4> +<H4><a name="Go_director_subclass">25.4.7.6 Subclass via embedding</a></H4> <p> @@ -948,7 +948,7 @@ class. </p> -<H4><a name="Go_director_finalizer">24.4.7.7 Memory management with runtime.SetFinalizer</a></H4> +<H4><a name="Go_director_finalizer">25.4.7.7 Memory management with runtime.SetFinalizer</a></H4> <p> @@ -1013,7 +1013,7 @@ before using <tt>runtime.SetFinalizer</tt> to know all of its gotchas. </p> -<H4><a name="Go_director_foobargo_class">24.4.7.8 Complete FooBarGo example class</a></H4> +<H4><a name="Go_director_foobargo_class">25.4.7.8 Complete FooBarGo example class</a></H4> <p> @@ -1142,7 +1142,7 @@ SWIG/Examples/go/director/</a>. </p> -<H3><a name="Go_primitive_type_mappings">24.4.8 Default Go primitive type mappings</a></H3> +<H3><a name="Go_primitive_type_mappings">25.4.8 Default Go primitive type mappings</a></H3> <p> @@ -1249,7 +1249,7 @@ that typemap, or add new values, to control how C/C++ types are mapped into Go types. </p> -<H3><a name="Go_output_arguments">24.4.9 Output arguments</a></H3> +<H3><a name="Go_output_arguments">25.4.9 Output arguments</a></H3> <p>Because of limitations in the way output arguments are processed in swig, @@ -1302,7 +1302,7 @@ void f(char *output); </pre> </div> -<H3><a name="Go_adding_additional_code">24.4.10 Adding additional go code</a></H3> +<H3><a name="Go_adding_additional_code">25.4.10 Adding additional go code</a></H3> <p>Often the APIs generated by swig are not very natural in go, especially if @@ -1397,7 +1397,7 @@ func bar() { </pre> </div> -<H3><a name="Go_typemaps">24.4.11 Go typemaps</a></H3> +<H3><a name="Go_typemaps">25.4.11 Go typemaps</a></H3> <p> diff --git a/Doc/Manual/Guile.html b/Doc/Manual/Guile.html index 31d822599..9d55b632b 100644 --- a/Doc/Manual/Guile.html +++ b/Doc/Manual/Guile.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Guile">25 SWIG and Guile</a></H1> +<H1><a name="Guile">26 SWIG and Guile</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -48,7 +48,7 @@ <p> This section details guile-specific support in SWIG. -<H2><a name="Guile_nn1">25.1 Supported Guile Versions</a></H2> +<H2><a name="Guile_nn1">26.1 Supported Guile Versions</a></H2> <p> @@ -62,7 +62,7 @@ improved performance. This is currently not tested with swig so your mileage may vary. To be safe set environment variable GUILE_AUTO_COMPILE to 0 when using swig generated guile code. -<H2><a name="Guile_nn2">25.2 Meaning of "Module"</a></H2> +<H2><a name="Guile_nn2">26.2 Meaning of "Module"</a></H2> <p> @@ -70,7 +70,7 @@ There are three different concepts of "module" involved, defined separately for SWIG, Guile, and Libtool. To avoid horrible confusion, we explicitly prefix the context, e.g., "guile-module". -<H2><a name="Guile_nn3">25.3 Old GH Guile API</a></H2> +<H2><a name="Guile_nn3">26.3 Old GH Guile API</a></H2> <p>Guile 1.8 and older could be interfaced using two different api's, the SCM @@ -81,7 +81,7 @@ or the GH API. The GH interface to guile is deprecated. Read more about why in version of SWIG that can still generate guile GH wrapper code is 2.0.9. Please use that version if you really need the GH wrapper code. -<H2><a name="Guile_nn4">25.4 Linkage</a></H2> +<H2><a name="Guile_nn4">26.4 Linkage</a></H2> <p> @@ -89,7 +89,7 @@ Guile support is complicated by a lack of user community cohesiveness, which manifests in multiple shared-library usage conventions. A set of policies implementing a usage convention is called a <b>linkage</b>. -<H3><a name="Guile_nn5">25.4.1 Simple Linkage</a></H3> +<H3><a name="Guile_nn5">26.4.1 Simple Linkage</a></H3> <p> @@ -194,7 +194,7 @@ placed between the <code>define-module</code> form and the <code>SWIG_init</code> via a preprocessor define to avoid symbol clashes. For this case, however, passive linkage is available. -<H3><a name="Guile_nn6">25.4.2 Passive Linkage</a></H3> +<H3><a name="Guile_nn6">26.4.2 Passive Linkage</a></H3> <p>Passive linkage is just like simple linkage, but it generates an @@ -204,7 +204,7 @@ package name (see below). <p>You should use passive linkage rather than simple linkage when you are using multiple modules. -<H3><a name="Guile_nn7">25.4.3 Native Guile Module Linkage</a></H3> +<H3><a name="Guile_nn7">26.4.3 Native Guile Module Linkage</a></H3> <p>SWIG can also generate wrapper code that does all the Guile module @@ -245,7 +245,7 @@ Newer Guile versions have a shorthand procedure for this: </div> </ul> -<H3><a name="Guile_nn8">25.4.4 Old Auto-Loading Guile Module Linkage</a></H3> +<H3><a name="Guile_nn8">26.4.4 Old Auto-Loading Guile Module Linkage</a></H3> <p>Guile used to support an autoloading facility for object-code @@ -271,7 +271,7 @@ option, SWIG generates an exported module initialization function with an appropriate name. -<H3><a name="Guile_nn9">25.4.5 Hobbit4D Linkage</a></H3> +<H3><a name="Guile_nn9">26.4.5 Hobbit4D Linkage</a></H3> <p> @@ -296,7 +296,7 @@ my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very experimental; the (hobbit4d link) conventions are not well understood. </p> -<H2><a name="Guile_nn10">25.5 Underscore Folding</a></H2> +<H2><a name="Guile_nn10">26.5 Underscore Folding</a></H2> <p> @@ -308,7 +308,7 @@ complained so far. <code>%rename</code> to specify the Guile name of the wrapped functions and variables (see CHANGES). -<H2><a name="Guile_nn11">25.6 Typemaps</a></H2> +<H2><a name="Guile_nn11">26.6 Typemaps</a></H2> <p> @@ -400,7 +400,7 @@ constant will appear as a scheme variable. See <a href="Customization.html#Customization_features">Features and the %feature directive</a> for info on how to apply the %feature.</p> -<H2><a name="Guile_nn12">25.7 Representation of pointers as smobs</a></H2> +<H2><a name="Guile_nn12">26.7 Representation of pointers as smobs</a></H2> <p> @@ -421,7 +421,7 @@ representing the expected pointer type. See also If the Scheme object passed was not a SWIG smob representing a compatible pointer, a <code>wrong-type-arg</code> exception is raised. -<H3><a name="Guile_nn14">25.7.1 Smobs</a></H3> +<H3><a name="Guile_nn14">26.7.1 Smobs</a></H3> <p> @@ -440,7 +440,7 @@ structure describing this type. If a generated GOOPS module has been loaded, sm the corresponding GOOPS class.</p> -<H3><a name="Guile_nn15">25.7.2 Garbage Collection</a></H3> +<H3><a name="Guile_nn15">26.7.2 Garbage Collection</a></H3> <p>Garbage collection is a feature of Guile since version 1.6. As SWIG now requires Guile > 1.8, @@ -454,14 +454,14 @@ is exactly like described in <a href="Customization.html#Customization_ownership Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and the guile module replaces $owner with 0 or 1 depending on feature:new.</p> -<H2><a name="Guile_nn16">25.8 Native Guile pointers</a></H2> +<H2><a name="Guile_nn16">26.8 Native Guile pointers</a></H2> <p> In addition to SWIG smob pointers, <a href="https://www.gnu.org/software/guile/manual/html_node/Foreign-Pointers.html">Guile's native pointer type</a> are accepted as arguments to wrapped SWIG functions. This can be useful for passing <a href="https://www.gnu.org/software/guile/manual/html_node/Void-Pointers-and-Byte-Access.html#">pointers to bytevector data</a> to wrapped functions. </p> -<H2><a name="Guile_nn17">25.9 Exception Handling</a></H2> +<H2><a name="Guile_nn17">26.9 Exception Handling</a></H2> <p> @@ -487,7 +487,7 @@ mapping: The default when not specified here is to use "swig-error". See Lib/exception.i for details. -<H2><a name="Guile_nn18">25.10 Procedure documentation</a></H2> +<H2><a name="Guile_nn18">26.10 Procedure documentation</a></H2> <p>If invoked with the command-line option <code>-procdoc @@ -522,7 +522,7 @@ like this: typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for details. -<H2><a name="Guile_nn19">25.11 Procedures with setters</a></H2> +<H2><a name="Guile_nn19">26.11 Procedures with setters</a></H2> <p>For global variables, SWIG creates a single wrapper procedure @@ -550,7 +550,7 @@ struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get pointer)</code> and <code>(<var>struct-member</var>-set pointer value)</code> are <em>not</em> generated. -<H2><a name="Guile_nn20">25.12 GOOPS Proxy Classes</a></H2> +<H2><a name="Guile_nn20">26.12 GOOPS Proxy Classes</a></H2> <p>SWIG can also generate classes and generic functions for use with @@ -696,7 +696,7 @@ Notice that <Foo> is used before it is defined. The fix is to just put th <code>%import "foo.h"</code> before the <code>%inline</code> block. </p> -<H3><a name="Guile_nn21">25.12.1 Naming Issues</a></H3> +<H3><a name="Guile_nn21">26.12.1 Naming Issues</a></H3> <p>As you can see in the example above, there are potential naming conflicts. The default exported @@ -733,7 +733,7 @@ guile-modules. For example,</p> (use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:))) </pre></div> -<H3><a name="Guile_nn22">25.12.2 Linking</a></H3> +<H3><a name="Guile_nn22">26.12.2 Linking</a></H3> <p>The guile-modules generated above all need to be linked together. GOOPS support requires diff --git a/Doc/Manual/Java.html b/Doc/Manual/Java.html index 4c7b6d058..ac92252e0 100644 --- a/Doc/Manual/Java.html +++ b/Doc/Manual/Java.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="Java">26 SWIG and Java</a></H1> +<H1><a name="Java">27 SWIG and Java</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -167,7 +167,7 @@ It covers most SWIG features, but certain low-level details are covered in less </p> -<H2><a name="Java_overview">26.1 Overview</a></H2> +<H2><a name="Java_overview">27.1 Overview</a></H2> <p> @@ -202,7 +202,7 @@ Various customisation tips and techniques using SWIG directives are covered. The latter sections cover the advanced techniques of using typemaps for complete control of the wrapping process. </p> -<H2><a name="Java_preliminaries">26.2 Preliminaries</a></H2> +<H2><a name="Java_preliminaries">27.2 Preliminaries</a></H2> <p> @@ -222,7 +222,7 @@ This is the commonly used method to load JNI code so your system will more than Android uses Java JNI and also works with SWIG. Please read the <a href="Android.html#Android">Android chapter</a> in conjunction with this one if you are targeting Android. </p> -<H3><a name="Java_running_swig">26.2.1 Running SWIG</a></H3> +<H3><a name="Java_running_swig">27.2.1 Running SWIG</a></H3> <p> @@ -281,7 +281,7 @@ The following sections have further practical examples and details on how you mi compiling and using the generated files. </p> -<H3><a name="Java_commandline">26.2.2 Additional Commandline Options</a></H3> +<H3><a name="Java_commandline">27.2.2 Additional Commandline Options</a></H3> <p> @@ -318,7 +318,7 @@ swig -java -help Their use will become clearer by the time you have finished reading this section on SWIG and Java. </p> -<H3><a name="Java_getting_right_headers">26.2.3 Getting the right header files</a></H3> +<H3><a name="Java_getting_right_headers">27.2.3 Getting the right header files</a></H3> <p> @@ -333,7 +333,7 @@ They are usually in directories like this:</p> <p> The exact location may vary on your machine, but the above locations are typical. </p> -<H3><a name="Java_compiling_dynamic">26.2.4 Compiling a dynamic module</a></H3> +<H3><a name="Java_compiling_dynamic">27.2.4 Compiling a dynamic module</a></H3> <p> @@ -368,7 +368,7 @@ The name of the shared library output file is important. If the name of your SWIG module is "<tt>example</tt>", the name of the corresponding shared library file should be "<tt>libexample.so</tt>" (or equivalent depending on your machine, see <a href="#Java_dynamic_linking_problems">Dynamic linking problems</a> for more information). The name of the module is specified using the <tt>%module</tt> directive or <tt>-module</tt> command line option.</p> -<H3><a name="Java_using_module">26.2.5 Using your module</a></H3> +<H3><a name="Java_using_module">27.2.5 Using your module</a></H3> <p> @@ -403,7 +403,7 @@ $ If it doesn't work have a look at the following section which discusses problems loading the shared library. </p> -<H3><a name="Java_dynamic_linking_problems">26.2.6 Dynamic linking problems</a></H3> +<H3><a name="Java_dynamic_linking_problems">27.2.6 Dynamic linking problems</a></H3> <p> @@ -490,7 +490,7 @@ The following section also contains some C++ specific linking problems and solut </p> -<H3><a name="Java_compilation_problems_cpp">26.2.7 Compilation problems and compiling with C++</a></H3> +<H3><a name="Java_compilation_problems_cpp">27.2.7 Compilation problems and compiling with C++</a></H3> <p> @@ -542,7 +542,7 @@ Finally make sure the version of JDK header files matches the version of Java th </p> -<H3><a name="Java_building_windows">26.2.8 Building on Windows</a></H3> +<H3><a name="Java_building_windows">27.2.8 Building on Windows</a></H3> <p> @@ -551,7 +551,7 @@ You will want to produce a DLL that can be loaded by the Java Virtual Machine. This section covers the process of using SWIG with Microsoft Visual C++ 6 although the procedure may be similar with other compilers. In order for everything to work, you will need to have a JDK installed on your machine in order to read the JNI header files.</p> -<H4><a name="Java_visual_studio">26.2.8.1 Running SWIG from Visual Studio</a></H4> +<H4><a name="Java_visual_studio">27.2.8.1 Running SWIG from Visual Studio</a></H4> <p> @@ -590,7 +590,7 @@ To run the native code in the DLL (example.dll), make sure that it is in your pa If the library fails to load have a look at <a href="#Java_dynamic_linking_problems">Dynamic linking problems</a>. </p> -<H4><a name="Java_nmake">26.2.8.2 Using NMAKE</a></H4> +<H4><a name="Java_nmake">27.2.8.2 Using NMAKE</a></H4> <p> @@ -649,7 +649,7 @@ Of course you may want to make changes for it to work for C++ by adding in the - </p> -<H2><a name="Java_basic_tour">26.3 A tour of basic C/C++ wrapping</a></H2> +<H2><a name="Java_basic_tour">27.3 A tour of basic C/C++ wrapping</a></H2> <p> @@ -659,7 +659,7 @@ variables are wrapped with JavaBean type getters and setters and so forth. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Java_module_packages_classes">26.3.1 Modules, packages and generated Java classes</a></H3> +<H3><a name="Java_module_packages_classes">27.3.1 Modules, packages and generated Java classes</a></H3> <p> @@ -695,7 +695,7 @@ swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i SWIG won't create the directory, so make sure it exists beforehand. </p> -<H3><a name="Java_functions">26.3.2 Functions</a></H3> +<H3><a name="Java_functions">27.3.2 Functions</a></H3> <p> @@ -729,7 +729,7 @@ System.out.println(example.fact(4)); </pre></div> -<H3><a name="Java_global_variables">26.3.3 Global variables</a></H3> +<H3><a name="Java_global_variables">27.3.3 Global variables</a></H3> <p> @@ -816,7 +816,7 @@ extern char *path; // Read-only (due to %immutable) </div> -<H3><a name="Java_constants">26.3.4 Constants</a></H3> +<H3><a name="Java_constants">27.3.4 Constants</a></H3> <p> @@ -956,7 +956,7 @@ Or if you decide this practice isn't so bad and your own class implements <tt>ex </p> -<H3><a name="Java_enumerations">26.3.5 Enumerations</a></H3> +<H3><a name="Java_enumerations">27.3.5 Enumerations</a></H3> <p> @@ -970,7 +970,7 @@ The final two approaches use simple integers for each enum item. Before looking at the various approaches for wrapping named C/C++ enums, anonymous enums are considered. </p> -<H4><a name="Java_anonymous_enums">26.3.5.1 Anonymous enums</a></H4> +<H4><a name="Java_anonymous_enums">27.3.5.1 Anonymous enums</a></H4> <p> @@ -1033,7 +1033,7 @@ As in the case of constants, you can access them through either the module class </p> -<H4><a name="Java_typesafe_enums">26.3.5.2 Typesafe enums</a></H4> +<H4><a name="Java_typesafe_enums">27.3.5.2 Typesafe enums</a></H4> <p> @@ -1127,7 +1127,7 @@ When upgrading to JDK 1.5 or later, proper Java enums could be used instead, wit The following section details proper Java enum generation. </p> -<H4><a name="Java_proper_enums">26.3.5.3 Proper Java enums</a></H4> +<H4><a name="Java_proper_enums">27.3.5.3 Proper Java enums</a></H4> <p> @@ -1180,7 +1180,7 @@ The additional support methods need not be generated if none of the enum items h <a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section. </p> -<H4><a name="Java_typeunsafe_enums">26.3.5.4 Type unsafe enums</a></H4> +<H4><a name="Java_typeunsafe_enums">27.3.5.4 Type unsafe enums</a></H4> <p> @@ -1228,7 +1228,7 @@ Note that unlike typesafe enums, this approach requires users to mostly use diff Thus the upgrade path to proper enums provided in JDK 1.5 is more painful. </p> -<H4><a name="Java_simple_enums">26.3.5.5 Simple enums</a></H4> +<H4><a name="Java_simple_enums">27.3.5.5 Simple enums</a></H4> <p> @@ -1247,7 +1247,7 @@ SWIG-1.3.21 and earlier versions wrapped all enums using this approach. The type unsafe approach is preferable to this one and this simple approach is only included for backwards compatibility with these earlier versions of SWIG. </p> -<H3><a name="Java_pointers">26.3.6 Pointers</a></H3> +<H3><a name="Java_pointers">27.3.6 Pointers</a></H3> <p> @@ -1335,7 +1335,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return a NULL pointer if the conversion can't be performed. </p> -<H3><a name="Java_structures">26.3.7 Structures</a></H3> +<H3><a name="Java_structures">27.3.7 Structures</a></H3> <p> @@ -1503,7 +1503,7 @@ x.setA(3); // Modify x.a - this is the same as b.f.a </div> -<H3><a name="Java_classes">26.3.8 C++ classes</a></H3> +<H3><a name="Java_classes">27.3.8 C++ classes</a></H3> <p> @@ -1566,7 +1566,7 @@ int bar = Spam.getBar(); </div> -<H3><a name="Java_inheritance">26.3.9 C++ inheritance</a></H3> +<H3><a name="Java_inheritance">27.3.9 C++ inheritance</a></H3> <p> @@ -1627,7 +1627,7 @@ Note that Java does not support multiple inheritance so any multiple inheritance A warning is given when multiple inheritance is detected and only the first base class is used. </p> -<H3><a name="Java_pointers_refs_arrays">26.3.10 Pointers, references, arrays and pass by value</a></H3> +<H3><a name="Java_pointers_refs_arrays">27.3.10 Pointers, references, arrays and pass by value</a></H3> <p> @@ -1682,7 +1682,7 @@ to hold the result and a pointer is returned (Java will release this memory when the returned object's finalizer is run by the garbage collector). </p> -<H4><a name="Java_null_pointers">26.3.10.1 Null pointers</a></H4> +<H4><a name="Java_null_pointers">27.3.10.1 Null pointers</a></H4> <p> @@ -1706,7 +1706,7 @@ For <tt>spam1</tt> and <tt>spam4</tt> above the Java <tt>null</tt> gets translat The converse also occurs, that is, NULL pointers are translated into <tt>null</tt> Java objects when returned from a C/C++ function. </p> -<H3><a name="Java_overloaded_functions">26.3.11 C++ overloaded functions</a></H3> +<H3><a name="Java_overloaded_functions">27.3.11 C++ overloaded functions</a></H3> <p> @@ -1821,7 +1821,7 @@ void spam(unsigned short); // Ignored </pre> </div> -<H3><a name="Java_default_arguments">26.3.12 C++ default arguments</a></H3> +<H3><a name="Java_default_arguments">27.3.12 C++ default arguments</a></H3> <p> @@ -1864,7 +1864,7 @@ Further details on default arguments and how to restore this approach are given </p> -<H3><a name="Java_namespaces">26.3.13 C++ namespaces</a></H3> +<H3><a name="Java_namespaces">27.3.13 C++ namespaces</a></H3> <p> @@ -1954,7 +1954,7 @@ If the resulting use of the nspace feature and hence packages results in a proxy you will need to open up the visibility for the pointer constructor and <tt>getCPtr</tt> method from the default 'protected' to 'public' with the <tt>SWIG_JAVABODY_PROXY</tt> macro. See <a href="#Java_code_typemaps">Java code typemaps</a>. </p> -<H3><a name="Java_templates">26.3.14 C++ templates</a></H3> +<H3><a name="Java_templates">27.3.14 C++ templates</a></H3> <p> @@ -2003,10 +2003,10 @@ Obviously, there is more to template wrapping than shown in this example. More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter. </p> -<H3><a name="Java_smart_pointers">26.3.15 C++ Smart Pointers</a></H3> +<H3><a name="Java_smart_pointers">27.3.15 C++ Smart Pointers</a></H3> -<H4><a name="Java_smart_pointers_shared_ptr">26.3.15.1 The shared_ptr Smart Pointer</a></H4> +<H4><a name="Java_smart_pointers_shared_ptr">27.3.15.1 The shared_ptr Smart Pointer</a></H4> <p> @@ -2017,7 +2017,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a </p> -<H4><a name="Java_smart_pointers_generic">26.3.15.2 Generic Smart Pointers</a></H4> +<H4><a name="Java_smart_pointers_generic">27.3.15.2 Generic Smart Pointers</a></H4> <p> @@ -2101,7 +2101,7 @@ Foo f = p.__deref__(); // Returns underlying Foo * </pre> </div> -<H2><a name="Java_further_details">26.4 Further details on the generated Java classes</a></H2> +<H2><a name="Java_further_details">27.4 Further details on the generated Java classes</a></H2> <p> @@ -2116,7 +2116,7 @@ Finally enum classes are covered. First, the crucial intermediary JNI class is considered. </p> -<H3><a name="Java_imclass">26.4.1 The intermediary JNI class</a></H3> +<H3><a name="Java_imclass">27.4.1 The intermediary JNI class</a></H3> <p> @@ -2236,7 +2236,7 @@ If <tt>name</tt> is the same as <tt>modulename</tt> then the module class name g from <tt>modulename</tt> to <tt>modulenameModule</tt>. </p> -<H4><a name="Java_imclass_pragmas">26.4.1.1 The intermediary JNI class pragmas</a></H4> +<H4><a name="Java_imclass_pragmas">27.4.1.1 The intermediary JNI class pragmas</a></H4> <p> @@ -2318,7 +2318,7 @@ For example, let's change the intermediary JNI class access to just the default All the methods in the intermediary JNI class will then not be callable outside of the package as the method modifiers have been changed from public access to default access. This is useful if you want to prevent users calling these low level functions. </p> -<H3><a name="Java_module_class">26.4.2 The Java module class</a></H3> +<H3><a name="Java_module_class">27.4.2 The Java module class</a></H3> <p> @@ -2349,7 +2349,7 @@ example.egg(new Foo()); The primary reason for having the module class wrapping the calls in the intermediary JNI class is to implement static type checking. In this case only a <tt>Foo</tt> can be passed to the <tt>egg</tt> function, whereas any <tt>long</tt> can be passed to the <tt>egg</tt> function in the intermediary JNI class. </p> -<H4><a name="Java_module_class_pragmas">26.4.2.1 The Java module class pragmas</a></H4> +<H4><a name="Java_module_class_pragmas">27.4.2.1 The Java module class pragmas</a></H4> <p> @@ -2400,7 +2400,7 @@ See <a href="#Java_imclass_pragmas">The intermediary JNI class pragmas</a> secti </p> -<H3><a name="Java_proxy_classes">26.4.3 Java proxy classes</a></H3> +<H3><a name="Java_proxy_classes">27.4.3 Java proxy classes</a></H3> <p> @@ -2476,7 +2476,7 @@ int y = f.spam(5, new Foo()); </pre> </div> -<H4><a name="Java_memory_management">26.4.3.1 Memory management</a></H4> +<H4><a name="Java_memory_management">27.4.3.1 Memory management</a></H4> <p> @@ -2638,7 +2638,7 @@ and </p> -<H4><a name="Java_inheritance_mirroring">26.4.3.2 Inheritance</a></H4> +<H4><a name="Java_inheritance_mirroring">27.4.3.2 Inheritance</a></H4> <p> @@ -2754,7 +2754,7 @@ However, true cross language polymorphism can be achieved using the <a href="#Ja </p> -<H4><a name="Java_proxy_classes_gc">26.4.3.3 Proxy classes and garbage collection</a></H4> +<H4><a name="Java_proxy_classes_gc">27.4.3.3 Proxy classes and garbage collection</a></H4> <p> @@ -2837,7 +2837,7 @@ The section on <a href="#Java_typemaps">Java typemaps</a> details how to specify See the <a href="http://www.devx.com/Java/Article/30192">How to Handle Java Finalization's Memory-Retention Issues</a> article for alternative approaches to managing memory by avoiding finalizers altogether. </p> -<H4><a name="Java_pgcpp">26.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling</a></H4> +<H4><a name="Java_pgcpp">27.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling</a></H4> <p> @@ -2959,7 +2959,7 @@ For example: <b>Compatibility note:</b> The generation of this additional parameter did not occur in versions prior to SWIG-1.3.30. </p> -<H4><a name="Java_multithread_libraries">26.4.3.5 Single threaded applications and thread safety</a></H4> +<H4><a name="Java_multithread_libraries">27.4.3.5 Single threaded applications and thread safety</a></H4> <p> @@ -3047,7 +3047,7 @@ for (int i=0; i<100000; i++) { </pre></div> -<H3><a name="Java_type_wrapper_classes">26.4.4 Type wrapper classes</a></H3> +<H3><a name="Java_type_wrapper_classes">27.4.4 Type wrapper classes</a></H3> <p> @@ -3134,7 +3134,7 @@ public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... } </div> -<H3><a name="Java_enum_classes">26.4.5 Enum classes</a></H3> +<H3><a name="Java_enum_classes">27.4.5 Enum classes</a></H3> <p> @@ -3143,7 +3143,7 @@ The <a href="#Java_enumerations">Enumerations</a> section discussed these but om The following sub-sections detail the various types of enum classes that can be generated. </p> -<H4><a name="Java_typesafe_enums_classes">26.4.5.1 Typesafe enum classes</a></H4> +<H4><a name="Java_typesafe_enums_classes">27.4.5.1 Typesafe enum classes</a></H4> <p> @@ -3227,7 +3227,7 @@ The <tt>swigValue</tt> method is used for marshalling in the other direction. The <tt>toString</tt> method is overridden so that the enum name is available. </p> -<H4><a name="Java_proper_enums_classes">26.4.5.2 Proper Java enum classes</a></H4> +<H4><a name="Java_proper_enums_classes">27.4.5.2 Proper Java enum classes</a></H4> <p> @@ -3305,7 +3305,7 @@ These needn't be generated if the enum being wrapped does not have any initializ <a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section describes how typemaps can be used to achieve this. </p> -<H4><a name="Java_typeunsafe_enums_classes">26.4.5.3 Type unsafe enum classes</a></H4> +<H4><a name="Java_typeunsafe_enums_classes">27.4.5.3 Type unsafe enum classes</a></H4> <p> @@ -3336,7 +3336,7 @@ public final class Beverage { </pre> </div> -<H3><a name="Java_interfaces">26.4.6 Interfaces</a></H3> +<H3><a name="Java_interfaces">27.4.6 Interfaces</a></H3> <p> @@ -3581,7 +3581,7 @@ typemap which is only used when a class is marked with the <tt>interface</tt> fe See <a href="Java.html#Java_code_typemaps">Java code typemaps</a> for details. </p> -<H2><a name="Java_directors">26.5 Cross language polymorphism using directors</a></H2> +<H2><a name="Java_directors">27.5 Cross language polymorphism using directors</a></H2> <p> @@ -3603,7 +3603,7 @@ The upshot is that C++ classes can be extended in Java and from C++ these extens Neither C++ code nor Java code needs to know where a particular method is implemented: the combination of proxy classes, director classes, and C wrapper functions transparently takes care of all the cross-language method routing. </p> -<H3><a name="Java_enabling_directors">26.5.1 Enabling directors</a></H3> +<H3><a name="Java_enabling_directors">27.5.1 Enabling directors</a></H3> <p> @@ -3671,7 +3671,7 @@ public: </pre> </div> -<H3><a name="Java_directors_classes">26.5.2 Director classes</a></H3> +<H3><a name="Java_directors_classes">27.5.2 Director classes</a></H3> <p> @@ -3698,7 +3698,7 @@ If the correct implementation is in Java, the Java API is used to call the metho </p> -<H3><a name="Java_directors_overhead">26.5.3 Overhead and code bloat</a></H3> +<H3><a name="Java_directors_overhead">27.5.3 Overhead and code bloat</a></H3> <p> @@ -3716,7 +3716,7 @@ This situation can be optimized by selectively enabling director methods (using </p> -<H3><a name="Java_directors_example">26.5.4 Simple directors example</a></H3> +<H3><a name="Java_directors_example">27.5.4 Simple directors example</a></H3> <p> @@ -3779,7 +3779,7 @@ DirectorDerived.upcall_method() invoked. </pre> </div> -<H3><a name="Java_directors_threading">26.5.5 Director threading issues</a></H3> +<H3><a name="Java_directors_threading">27.5.5 Director threading issues</a></H3> <p> @@ -3799,7 +3799,7 @@ Macros can be defined on the commandline when compiling your C++ code, or altern </pre> </div> -<H3><a name="Java_directors_performance">26.5.6 Director performance tuning</a></H3> +<H3><a name="Java_directors_performance">27.5.6 Director performance tuning</a></H3> <p> @@ -3820,7 +3820,7 @@ However, if all director methods are expected to usually be overridden by Java s The disadvantage is that invocation of director methods from C++ when Java doesn't actually override the method will require an additional call up into Java and back to C++. As such, this option is only useful when overrides are extremely common and instantiation is frequent enough that its performance is critical. </p> -<H3><a name="Java_exceptions_from_directors">26.5.7 Java exceptions from directors</a></H3> +<H3><a name="Java_exceptions_from_directors">27.5.7 Java exceptions from directors</a></H3> <p> @@ -3896,7 +3896,7 @@ Exception in thread "main" java.lang.RuntimeException: There was a problem! More on the <tt>Swig::DirectorException</tt> class can be found in the next section which details how to customize the handling of director exceptions. </p> -<H4><a name="Java_customizing_director_exceptions">26.5.7.1 Customizing director exceptions</a></H4> +<H4><a name="Java_customizing_director_exceptions">27.5.7.1 Customizing director exceptions</a></H4> <p> @@ -4454,7 +4454,7 @@ Exception in thread "main" java.lang.IndexOutOfBoundsException: Index is negativ </pre> </div> -<H2><a name="Java_allprotected">26.6 Accessing protected members</a></H2> +<H2><a name="Java_allprotected">27.6 Accessing protected members</a></H2> <p> @@ -4550,7 +4550,7 @@ class MyProtectedBase extends ProtectedBase -<H2><a name="Java_common_customization">26.7 Common customization features</a></H2> +<H2><a name="Java_common_customization">27.7 Common customization features</a></H2> <p> @@ -4562,7 +4562,7 @@ be awkward. This section describes some common SWIG features that are used to improve the interface to existing C/C++ code. </p> -<H3><a name="Java_helper_functions">26.7.1 C/C++ helper functions</a></H3> +<H3><a name="Java_helper_functions">27.7.1 C/C++ helper functions</a></H3> <p> @@ -4628,7 +4628,7 @@ hard to implement. It is possible to improve on this using Java code, typemaps, customization features as covered in later sections, but sometimes helper functions are a quick and easy solution to difficult cases. </p> -<H3><a name="Java_class_extension">26.7.2 Class extension with %extend</a></H3> +<H3><a name="Java_class_extension">27.7.2 Class extension with %extend</a></H3> <p> @@ -4691,7 +4691,7 @@ Vector(2, 3, 4) in any way---the extensions only show up in the Java interface. </p> -<H3><a name="Java_proxycode">26.7.3 Class extension with %proxycode</a></H3> +<H3><a name="Java_proxycode">27.7.3 Class extension with %proxycode</a></H3> <p> @@ -4828,7 +4828,7 @@ public class ValueUnsignedInt { </pre> </div> -<H3><a name="Java_exception_handling">26.7.4 Exception handling with %exception and %javaexception</a></H3> +<H3><a name="Java_exception_handling">27.7.4 Exception handling with %exception and %javaexception</a></H3> <p> @@ -4987,7 +4987,7 @@ to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> ch The typemap example <a href="#Java_exception_typemap">Handling C++ exception specifications as Java exceptions</a> provides further exception handling capabilities. </p> -<H3><a name="Java_method_access">26.7.5 Method access with %javamethodmodifiers</a></H3> +<H3><a name="Java_method_access">27.7.5 Method access with %javamethodmodifiers</a></H3> <p> @@ -5013,7 +5013,7 @@ protected static void protect_me() { </pre> </div> -<H2><a name="Java_tips_techniques">26.8 Tips and techniques</a></H2> +<H2><a name="Java_tips_techniques">27.8 Tips and techniques</a></H2> <p> @@ -5023,7 +5023,7 @@ strings and arrays. This chapter discusses the common techniques for solving these problems. </p> -<H3><a name="Java_input_output_parameters">26.8.1 Input and output parameters using primitive pointers and references</a></H3> +<H3><a name="Java_input_output_parameters">27.8.1 Input and output parameters using primitive pointers and references</a></H3> <p> @@ -5197,7 +5197,7 @@ void foo(Bar *OUTPUT); will not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>. </p> -<H3><a name="Java_simple_pointers">26.8.2 Simple pointers</a></H3> +<H3><a name="Java_simple_pointers">27.8.2 Simple pointers</a></H3> <p> @@ -5263,7 +5263,7 @@ System.out.println("3 + 4 = " + result); See the <a href="Library.html#Library">SWIG Library</a> chapter for further details. </p> -<H3><a name="Java_c_arrays">26.8.3 Wrapping C arrays with Java arrays</a></H3> +<H3><a name="Java_c_arrays">27.8.3 Wrapping C arrays with Java arrays</a></H3> <p> @@ -5330,7 +5330,7 @@ Please be aware that the typemaps in this library are not efficient as all the e There is an alternative approach using the SWIG array library and this is covered in the next section. </p> -<H3><a name="Java_unbounded_c_arrays">26.8.4 Unbounded C Arrays</a></H3> +<H3><a name="Java_unbounded_c_arrays">27.8.4 Unbounded C Arrays</a></H3> <p> @@ -5475,7 +5475,7 @@ well suited for applications in which you need to create buffers, package binary data, etc. </p> -<H3><a name="Java_binary_char">26.8.5 Binary data vs Strings</a></H3> +<H3><a name="Java_binary_char">27.8.5 Binary data vs Strings</a></H3> <p> @@ -5519,7 +5519,7 @@ len: 5 data: 68 69 0 6a 6b </pre></div> -<H3><a name="Java_heap_allocations">26.8.6 Overriding new and delete to allocate from Java heap</a></H3> +<H3><a name="Java_heap_allocations">27.8.6 Overriding new and delete to allocate from Java heap</a></H3> <p> @@ -5636,7 +5636,7 @@ model and use these functions in place of malloc and free in your own code. </p> -<H2><a name="Java_typemaps">26.9 Java typemaps</a></H2> +<H2><a name="Java_typemaps">27.9 Java typemaps</a></H2> <p> @@ -5657,7 +5657,7 @@ Before proceeding, it should be stressed that typemaps are not a required part of using SWIG---the default wrapping behavior is enough in most cases. Typemaps are only used if you want to change some aspect of the generated code. -<H3><a name="Java_default_primitive_type_mappings">26.9.1 Default primitive type mappings</a></H3> +<H3><a name="Java_default_primitive_type_mappings">27.9.1 Default primitive type mappings</a></H3> <p> @@ -5809,7 +5809,7 @@ However, the mappings allow the full range of values for each C type from Java. </p> -<H3><a name="Java_default_non_primitive_typemaps">26.9.2 Default typemaps for non-primitive types</a></H3> +<H3><a name="Java_default_non_primitive_typemaps">27.9.2 Default typemaps for non-primitive types</a></H3> <p> @@ -5824,7 +5824,7 @@ So in summary, the C/C++ pointer to non-primitive types is cast into the 64 bit The Java type is either the proxy class or type wrapper class. </p> -<H3><a name="Java_jvm64">26.9.3 Sixty four bit JVMs</a></H3> +<H3><a name="Java_jvm64">27.9.3 Sixty four bit JVMs</a></H3> <p> @@ -5837,7 +5837,7 @@ Unfortunately it won't of course hold true for JNI code. </p> -<H3><a name="Java_what_is_typemap">26.9.4 What is a typemap?</a></H3> +<H3><a name="Java_what_is_typemap">27.9.4 What is a typemap?</a></H3> <p> @@ -5960,7 +5960,7 @@ int c = example.count('e', "Hello World"); </pre> </div> -<H3><a name="Java_typemaps_c_to_java_types">26.9.5 Typemaps for mapping C/C++ types to Java types</a></H3> +<H3><a name="Java_typemaps_c_to_java_types">27.9.5 Typemaps for mapping C/C++ types to Java types</a></H3> <p> @@ -6240,7 +6240,7 @@ These are listed below: </table> -<H3><a name="Java_typemap_attributes">26.9.6 Java typemap attributes</a></H3> +<H3><a name="Java_typemap_attributes">27.9.6 Java typemap attributes</a></H3> <p> @@ -6286,7 +6286,7 @@ The "javain" typemap has the optional 'pre', 'post' and 'pgcppname' attributes. Note that when the 'pre' or 'post' attributes are specified and the associated type is used in a constructor, a constructor helper function is generated. This is necessary as the Java proxy constructor wrapper makes a call to a support constructor using a <i>this</i> call. In Java the <i>this</i> call must be the first statement in the constructor body. The constructor body thus calls the helper function and the helper function instead makes the JNI call, ensuring the 'pre' code is called before the JNI call is made. There is a <a href="#Java_date_marshalling">Date marshalling</a> example showing 'pre', 'post' and 'pgcppname' attributes in action. </p> -<H3><a name="Java_special_variables">26.9.7 Java special variables</a></H3> +<H3><a name="Java_special_variables">27.9.7 Java special variables</a></H3> <p> @@ -6468,7 +6468,7 @@ in that it is not fully qualified with the package name when using the <a href="SWIGPlus.html#SWIGPlus_nspace">nspace feature</a>. </p> -<H3><a name="Java_typemaps_for_c_and_cpp">26.9.8 Typemaps for both C and C++ compilation</a></H3> +<H3><a name="Java_typemaps_for_c_and_cpp">27.9.8 Typemaps for both C and C++ compilation</a></H3> <p> @@ -6505,7 +6505,7 @@ If you do not intend your code to be targeting both C and C++ then your typemaps </p> -<H3><a name="Java_code_typemaps">26.9.9 Java code typemaps</a></H3> +<H3><a name="Java_code_typemaps">27.9.9 Java code typemaps</a></H3> <p> @@ -6801,7 +6801,7 @@ to make the method and constructor public: </pre> </div> -<H3><a name="Java_directors_typemaps">26.9.10 Director specific typemaps</a></H3> +<H3><a name="Java_directors_typemaps">27.9.10 Director specific typemaps</a></H3> <p> @@ -7078,7 +7078,7 @@ The basic strategy here is to provide a default package typemap for the majority </div> -<H2><a name="Java_typemap_examples">26.10 Typemap Examples</a></H2> +<H2><a name="Java_typemap_examples">27.10 Typemap Examples</a></H2> <p> @@ -7088,7 +7088,7 @@ the SWIG library. </p> -<H3><a name="Java_simpler_enum_classes">26.10.1 Simpler Java enums for enums without initializers</a></H3> +<H3><a name="Java_simpler_enum_classes">27.10.1 Simpler Java enums for enums without initializers</a></H3> <p> @@ -7167,7 +7167,7 @@ This would be done by using the original versions of these typemaps in "enums.sw </p> -<H3><a name="Java_exception_typemap">26.10.2 Handling C++ exception specifications as Java exceptions</a></H3> +<H3><a name="Java_exception_typemap">27.10.2 Handling C++ exception specifications as Java exceptions</a></H3> <p> @@ -7292,7 +7292,7 @@ We could alternatively have used <tt>%rename</tt> to rename <tt>what()</tt> into </p> -<H3><a name="Java_nan_exception_typemap">26.10.3 NaN Exception - exception handling for a particular type</a></H3> +<H3><a name="Java_nan_exception_typemap">27.10.3 NaN Exception - exception handling for a particular type</a></H3> <p> @@ -7447,7 +7447,7 @@ If we were a martyr to the JNI cause, we could replace the succinct code within If we had, we would have put it in the "in" typemap which, like all JNI and Java typemaps, also supports the 'throws' attribute. </p> -<H3><a name="Java_converting_java_string_arrays">26.10.4 Converting Java String arrays to char ** </a></H3> +<H3><a name="Java_converting_java_string_arrays">27.10.4 Converting Java String arrays to char ** </a></H3> <p> @@ -7591,7 +7591,7 @@ Lastly the "jni", "jtype" and "jstype" typemaps are also required to specify what Java types to use. </p> -<H3><a name="Java_expanding_java_object">26.10.5 Expanding a Java object to multiple arguments</a></H3> +<H3><a name="Java_expanding_java_object">27.10.5 Expanding a Java object to multiple arguments</a></H3> <p> @@ -7673,7 +7673,7 @@ example.foo(new String[]{"red", "green", "blue", "white"}); </div> -<H3><a name="Java_using_typemaps_return_arguments">26.10.6 Using typemaps to return arguments</a></H3> +<H3><a name="Java_using_typemaps_return_arguments">27.10.6 Using typemaps to return arguments</a></H3> <p> @@ -7791,7 +7791,7 @@ $ java runme 1 12.0 340.0 </pre></div> -<H3><a name="Java_adding_downcasts">26.10.7 Adding Java downcasts to polymorphic return types</a></H3> +<H3><a name="Java_adding_downcasts">27.10.7 Adding Java downcasts to polymorphic return types</a></H3> <p> @@ -7997,7 +7997,7 @@ SWIG usually generates code which constructs the proxy classes using Java code a Note that the JNI code above uses a number of string lookups to call a constructor, whereas this would not occur using byte compiled Java code. </p> -<H3><a name="Java_adding_equals_method">26.10.8 Adding an equals method to the Java classes</a></H3> +<H3><a name="Java_adding_equals_method">27.10.8 Adding an equals method to the Java classes</a></H3> <p> @@ -8041,7 +8041,7 @@ System.out.println("foo1? " + foo1.equals(foo2)); </div> -<H3><a name="Java_void_pointers">26.10.9 Void pointers and a common Java base class</a></H3> +<H3><a name="Java_void_pointers">27.10.9 Void pointers and a common Java base class</a></H3> <p> @@ -8100,7 +8100,7 @@ This example contains some useful functionality which you may want in your code. <li> It also has a function which effectively implements a cast from the type of the proxy/type wrapper class to a void pointer. This is necessary for passing a proxy class or a type wrapper class to a function that takes a void pointer. </ul> -<H3><a name="Java_struct_pointer_pointer">26.10.10 Struct pointer to pointer</a></H3> +<H3><a name="Java_struct_pointer_pointer">27.10.10 Struct pointer to pointer</a></H3> <p> @@ -8280,7 +8280,7 @@ The C functional interface has been completely morphed into an object-oriented i the Butler class would behave much like any pure Java class and feel more natural to Java users. </p> -<H3><a name="Java_memory_management_member_variables">26.10.11 Memory management when returning references to member variables</a></H3> +<H3><a name="Java_memory_management_member_variables">27.10.11 Memory management when returning references to member variables</a></H3> <p> @@ -8403,7 +8403,7 @@ public class Bike { Note the <tt>addReference</tt> call. </p> -<H3><a name="Java_memory_management_objects">26.10.12 Memory management for objects passed to the C++ layer</a></H3> +<H3><a name="Java_memory_management_objects">27.10.12 Memory management for objects passed to the C++ layer</a></H3> <p> @@ -8531,7 +8531,7 @@ as mentioned earlier, <tt>setElement</tt> is actually: </pre> </div> -<H3><a name="Java_date_marshalling">26.10.13 Date marshalling using the javain typemap and associated attributes</a></H3> +<H3><a name="Java_date_marshalling">27.10.13 Date marshalling using the javain typemap and associated attributes</a></H3> <p> @@ -8708,7 +8708,7 @@ A few things to note: -<H2><a name="Java_directors_faq">26.11 Living with Java Directors</a></H2> +<H2><a name="Java_directors_faq">27.11 Living with Java Directors</a></H2> <p> @@ -8887,10 +8887,10 @@ public abstract class UserVisibleFoo extends Foo { </li> </ol> -<H2><a name="Java_odds_ends">26.12 Odds and ends</a></H2> +<H2><a name="Java_odds_ends">27.12 Odds and ends</a></H2> -<H3><a name="Java_javadoc_comments">26.12.1 JavaDoc comments</a></H3> +<H3><a name="Java_javadoc_comments">27.12.1 JavaDoc comments</a></H3> <p> @@ -8946,7 +8946,7 @@ public class Barmy { -<H3><a name="Java_functional_interface">26.12.2 Functional interface without proxy classes</a></H3> +<H3><a name="Java_functional_interface">27.12.2 Functional interface without proxy classes</a></H3> <p> @@ -9007,7 +9007,7 @@ All destructors have to be called manually for example the <tt>delete_Foo(foo)</ </p> -<H3><a name="Java_using_own_jni_functions">26.12.3 Using your own JNI functions</a></H3> +<H3><a name="Java_using_own_jni_functions">27.12.3 Using your own JNI functions</a></H3> <p> @@ -9057,7 +9057,7 @@ This directive is only really useful if you want to mix your own hand crafted JN </p> -<H3><a name="Java_performance">26.12.4 Performance concerns and hints</a></H3> +<H3><a name="Java_performance">27.12.4 Performance concerns and hints</a></H3> <p> @@ -9078,7 +9078,7 @@ However, you will have to be careful about memory management and make sure that This method normally calls the C++ destructor or <tt>free()</tt> for C code. </p> -<H3><a name="Java_debugging">26.12.5 Debugging</a></H3> +<H3><a name="Java_debugging">27.12.5 Debugging</a></H3> <p> @@ -9100,7 +9100,7 @@ The -verbose:jni and -verbose:gc are also useful options for monitoring code beh </p> -<H2><a name="Java_examples">26.13 Java Examples</a></H2> +<H2><a name="Java_examples">27.13 Java Examples</a></H2> <p> diff --git a/Doc/Manual/Javascript.html b/Doc/Manual/Javascript.html index c328bbb6b..ab7ee5157 100644 --- a/Doc/Manual/Javascript.html +++ b/Doc/Manual/Javascript.html @@ -7,7 +7,7 @@ </head> <body> -<H1><a name="Javascript">27 SWIG and Javascript</a></H1> +<H1><a name="Javascript">28 SWIG and Javascript</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -52,7 +52,7 @@ <p>This chapter describes SWIG's support of Javascript. It does not cover SWIG basics, but only information that is specific to this module.</p> -<H2><a name="Javascript_overview">27.1 Overview</a></H2> +<H2><a name="Javascript_overview">28.1 Overview</a></H2> <p>Javascript is a prototype-based scripting language that is dynamic, weakly typed and has first-class functions. Its arguably the most popular language for web development. @@ -63,10 +63,10 @@ Javascript has gone beyond being a browser-based scripting language and with <a With <a href="https://github.com/rogerwang/node-webkit">node-webkit</a> there is a platform which uses Google's <code>Chromium</code> as Web-Browser widget and <code>node.js</code> for javascript extensions. </p> -<H2><a name="Javascript_preliminaries">27.2 Preliminaries</a></H2> +<H2><a name="Javascript_preliminaries">28.2 Preliminaries</a></H2> -<H3><a name="Javascript_running_swig">27.2.1 Running SWIG</a></H3> +<H3><a name="Javascript_running_swig">28.2.1 Running SWIG</a></H3> <p>Suppose that you defined a SWIG module such as the following:</p> @@ -121,7 +121,7 @@ void example_initialize(v8::Handle<v8::Object> exports)</pre> <b>Note</b>: be aware that <code>v8</code> has a C++ API, and thus, the generated modules must be compiled as C++. </p> -<H3><a name="Javascript_running_tests_examples">27.2.2 Running Tests and Examples</a></H3> +<H3><a name="Javascript_running_tests_examples">28.2.2 Running Tests and Examples</a></H3> <p>The configuration for tests and examples currently supports Linux and Mac only and not MinGW (Windows) yet.</p> @@ -153,7 +153,7 @@ $ make check-javascript-test-suite ENGINE=jsc</pre> $ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8</pre> </div> -<H3><a name="Javascript_known_issues">27.2.3 Known Issues</a></H3> +<H3><a name="Javascript_known_issues">28.2.3 Known Issues</a></H3> <p>At the moment, the Javascript generators pass all tests syntactically, i.e., the generated source code compiles. However, there are still remaining runtime issues.</p> @@ -170,12 +170,12 @@ $ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8</pre> <p>The primary development environment has been Linux (Ubuntu 12.04). Windows and Mac OS X have been tested sporadically. Therefore, the generators might have more issues on those platforms. Please report back any problem you observe to help us improving this module quickly.</p> -<H2><a name="Javascript_integration">27.3 Integration</a></H2> +<H2><a name="Javascript_integration">28.3 Integration</a></H2> <p>This chapter gives a short introduction how to use a native Javascript extension: as a <code>node.js</code> module, and as an extension for an embedded Webkit.</p> -<H3><a name="Javascript_node_extensions">27.3.1 Creating node.js Extensions</a></H3> +<H3><a name="Javascript_node_extensions">28.3.1 Creating node.js Extensions</a></H3> <p>To install <code>node.js</code> you can download an installer from their <a href="https://launchpad.net/~chris-lea/+archive/node.js">web-site</a> for Mac OS X and Windows. For Linux you can either build the source yourself and run <code>sudo checkinstall</code> or keep to the (probably stone-age) packaged version. For Ubuntu there is a <a href="https://launchpad.net/~chris-lea/+archive/ubuntu/node.js/">PPA</a> available.</p> @@ -221,7 +221,7 @@ require("./build/Release/example")</pre> </div> <p>A more detailed explanation is given in the <a href="#Javascript_examples">Examples</a> section.</p> -<H4><a name="Javascript_troubleshooting">27.3.1.1 Troubleshooting</a></H4> +<H4><a name="Javascript_troubleshooting">28.3.1.1 Troubleshooting</a></H4> <ul> @@ -233,12 +233,12 @@ require("./build/Release/example")</pre> $ sudo apt-get remove gyp</pre> </div> -<H3><a name="Javascript_embedded_webkit">27.3.2 Embedded Webkit</a></H3> +<H3><a name="Javascript_embedded_webkit">28.3.2 Embedded Webkit</a></H3> <p>Webkit is pre-installed on Mac OS X and available as a library for GTK.</p> -<H4><a name="Javascript_osx">27.3.2.1 Mac OS X</a></H4> +<H4><a name="Javascript_osx">28.3.2.1 Mac OS X</a></H4> <p>There is general information about programming with WebKit on <a href="https://developer.apple.com/library/mac/documentation/cocoa/conceptual/DisplayWebContent/DisplayWebContent.html">Apple Developer Documentation</a>. Details about <code>Cocoa</code> programming are not covered here.</p> @@ -286,7 +286,7 @@ extern bool example_initialize(JSGlobalContextRef context, JSObjectRef* exports) @end</pre> </div> -<H4><a name="Javascript_gtk">27.3.2.2 GTK</a></H4> +<H4><a name="Javascript_gtk">28.3.2.2 GTK</a></H4> <p>There is general information about programming GTK at <a href="https://developer.gnome.org/gtk2/">GTK documentation</a> and in the <a href="https://developer.gnome.org/gtk-tutorial">GTK tutorial</a>, and for Webkit there is a <a href="http://webkitgtk.org/reference/webkitgtk/stable/index.html">Webkit GTK+ API Reference</a>.</p> @@ -331,7 +331,7 @@ int main(int argc, char* argv[]) }</pre> </div> -<H3><a name="Javascript_applications_webkit">27.3.3 Creating Applications with node-webkit</a></H3> +<H3><a name="Javascript_applications_webkit">28.3.3 Creating Applications with node-webkit</a></H3> <p>To get started with <code>node-webkit</code> there is a very informative set of <a href="https://github.com/rogerwang/node-webkit/wiki">wiki pages</a>.</p> @@ -422,12 +422,12 @@ open new windows, and many more things. };</pre> </div> -<H2><a name="Javascript_examples">27.4 Examples</a></H2> +<H2><a name="Javascript_examples">28.4 Examples</a></H2> <p>Some basic examples are shown here in more detail.</p> -<H3><a name="Javascript_simple_example">27.4.1 Simple</a></H3> +<H3><a name="Javascript_simple_example">28.4.1 Simple</a></H3> <p>The common example <code>simple</code> looks like this:</p> @@ -477,7 +477,7 @@ example.Foo = 3.1415926;</pre> <p><b>Note</b>: ECMAScript 5, the currently implemented Javascript standard, does not have modules. <code>node.js</code> and other implementations provide this mechanism defined by the <a href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> group. For browsers this is provided by <a href="http://browserify.org">Browserify</a>, for instance.</p> -<H3><a name="Javascript_class_example">27.4.2 Class</a></H3> +<H3><a name="Javascript_class_example">28.4.2 Class</a></H3> <p>The common example <code>class</code> defines three classes, <code>Shape</code>, <code>Circle</code>, and <code>Square</code>:</p> @@ -607,12 +607,12 @@ at emitKey (readline.js:1095:12)</pre> <b>Note</b>: In ECMAScript 5 there is no concept for classes. Instead each function can be used as a constructor function which is executed by the 'new' operator. Furthermore, during construction the key property <code>prototype</code> of the constructor function is used to attach a prototype instance to the created object. A prototype is essentially an object itself that is the first-class delegate of a class used whenever the access to a property of an object fails. The very same prototype instance is shared among all instances of one type. Prototypal inheritance is explained in more detail on in <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain">Inheritance and the prototype chain</a>, for instance. </p> -<H2><a name="Javascript_implementation">27.5 Implementation</a></H2> +<H2><a name="Javascript_implementation">28.5 Implementation</a></H2> <p>The Javascript Module implementation has taken a very different approach compared to other language modules in order to support different Javascript interpreters.</p> -<H3><a name="Javascript_source_code">27.5.1 Source Code</a></H3> +<H3><a name="Javascript_source_code">28.5.1 Source Code</a></H3> <p>The Javascript module is implemented in <code>Source/Modules/javascript.cxx</code>. It dispatches the code generation to a <code>JSEmitter</code> instance, <code>V8Emitter</code> or <code>JSCEmitter</code>. Additionally there are some helpers: <code>Template</code>, for templated code generation, and <code>JSEmitterState</code>, which is used to manage state information during AST traversal. This rough map shall make it easier to find a way through this huge source file:</p> @@ -713,7 +713,7 @@ Template::Template(const String *code_) { ... } ...</pre> </div> -<H3><a name="Javascript_code_templates">27.5.2 Code Templates</a></H3> +<H3><a name="Javascript_code_templates">28.5.2 Code Templates</a></H3> <p>All generated code is created on the basis of code templates. The templates for <em>JavascriptCore</em> can be found in <code>Lib/javascript/jsc/javascriptcode.swg</code>, for <em>v8</em> in <code>Lib/javascript/v8/javascriptcode.swg</code>.</p> @@ -752,7 +752,7 @@ t_register.replace("$jsparent", state.clazz(NAME_MANGLED)) </div> <p><code>Template</code> creates a copy of that string and <code>Template::replace</code> uses Swig's <code>Replaceall</code> to replace variables in the template. <code>Template::trim</code> can be used to eliminate leading and trailing whitespaces. <code>Template::print</code> is used to write the final template string to a Swig <code>DOH</code> (based on <code>Printv</code>). All methods allow chaining.</p> -<H3><a name="Javascript_emitter">27.5.3 Emitter</a></H3> +<H3><a name="Javascript_emitter">28.5.3 Emitter</a></H3> <p>The Javascript module delegates code generation to a <code>JSEmitter</code> instance. The following extract shows the essential interface:</p> @@ -871,7 +871,7 @@ int JAVASCRIPT::classHandler(Node *n) { </div> <p>In <code>enterClass</code> the emitter stores state information that is necessary when processing class members. In <code>exitClass</code> the wrapper code for the whole class is generated.</p> -<H3><a name="Javascript_emitter_states">27.5.4 Emitter states</a></H3> +<H3><a name="Javascript_emitter_states">28.5.4 Emitter states</a></H3> <p>For storing information during the AST traversal the emitter provides a <code>JSEmitterState</code> with different slots to store data representing the scopes global, class, function, and variable.</p> @@ -915,7 +915,7 @@ state.clazz(NAME, Getattr(n, "sym:name"));</pre> <p>State information can be retrieved using <code>state.clazz(NAME)</code> or with <code>Getattr</code> on <code>state.clazz()</code> which actually returns a <code>Hash</code> instance.</p> -<H3><a name="Javascript_jsc_exceptions">27.5.5 Handling Exceptions in JavascriptCore</a></H3> +<H3><a name="Javascript_jsc_exceptions">28.5.5 Handling Exceptions in JavascriptCore</a></H3> <p>Applications with an embedded JavascriptCore should be able to present detailed exception messages that occur in the Javascript engine. Below is an example derived from code provided by Brian Barnes on how these exception details can be extracted.</p> diff --git a/Doc/Manual/Lisp.html b/Doc/Manual/Lisp.html index 2e6ca8dda..2d65f883b 100644 --- a/Doc/Manual/Lisp.html +++ b/Doc/Manual/Lisp.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Lisp">28 SWIG and Common Lisp</a></H1> +<H1><a name="Lisp">29 SWIG and Common Lisp</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -42,7 +42,7 @@ Lisp, Common Foreign Function Interface(CFFI), CLisp and UFFI foreign function interfaces. </p> -<H2><a name="Lisp_nn2">28.1 Allegro Common Lisp</a></H2> +<H2><a name="Lisp_nn2">29.1 Allegro Common Lisp</a></H2> <p> @@ -51,7 +51,7 @@ <a href="Allegrocl.html#Allegrocl">here</a> </p> -<H2><a name="Lisp_nn3">28.2 Common Foreign Function Interface(CFFI)</a></H2> +<H2><a name="Lisp_nn3">29.2 Common Foreign Function Interface(CFFI)</a></H2> <p> @@ -78,7 +78,7 @@ swig -cffi -module <i>module-name</i> <i>file-name</i> files and the various things which you can do with them. </p> -<H3><a name="Lisp_nn4">28.2.1 Additional Commandline Options </a></H3> +<H3><a name="Lisp_nn4">29.2.1 Additional Commandline Options </a></H3> <p> @@ -119,7 +119,7 @@ swig -cffi -help </table> -<H3><a name="Lisp_nn5">28.2.2 Generating CFFI bindings</a></H3> +<H3><a name="Lisp_nn5">29.2.2 Generating CFFI bindings</a></H3> <p> @@ -403,7 +403,7 @@ The feature <i>intern_function</i> ensures that all C names are </pre></div> -<H3><a name="Lisp_nn6">28.2.3 Generating CFFI bindings for C++ code</a></H3> +<H3><a name="Lisp_nn6">29.2.3 Generating CFFI bindings for C++ code</a></H3> <p>This feature to SWIG (for CFFI) is very new and still far from @@ -582,7 +582,7 @@ If you have any questions, suggestions, patches, etc., related to CFFI module feel free to contact us on the SWIG mailing list, and also please add a "[CFFI]" tag in the subject line. -<H3><a name="Lisp_nn7">28.2.4 Inserting user code into generated files</a></H3> +<H3><a name="Lisp_nn7">29.2.4 Inserting user code into generated files</a></H3> <p> @@ -622,7 +622,7 @@ Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for </p> -<H2><a name="Lisp_nn8">28.3 CLISP</a></H2> +<H2><a name="Lisp_nn8">29.3 CLISP</a></H2> <p> @@ -652,7 +652,7 @@ swig -clisp -module <i>module-name</i> <i>file-name</i> interface file for the CLISP module. The CLISP module tries to produce code which is both human readable and easily modifiable. </p> -<H3><a name="Lisp_nn9">28.3.1 Additional Commandline Options </a></H3> +<H3><a name="Lisp_nn9">29.3.1 Additional Commandline Options </a></H3> <p> @@ -685,7 +685,7 @@ shortcuts according to the typedefs in the input. </table> -<H3><a name="Lisp_nn10">28.3.2 Details on CLISP bindings</a></H3> +<H3><a name="Lisp_nn10">29.3.2 Details on CLISP bindings</a></H3> <p> @@ -809,7 +809,7 @@ struct bar { </pre></div> -<H2><a name="Lisp_nn11">28.4 UFFI </a></H2> +<H2><a name="Lisp_nn11">29.4 UFFI </a></H2> </body> diff --git a/Doc/Manual/Lua.html b/Doc/Manual/Lua.html index 8e545776f..944223f3c 100644 --- a/Doc/Manual/Lua.html +++ b/Doc/Manual/Lua.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Lua">29 SWIG and Lua</a></H1> +<H1><a name="Lua">30 SWIG and Lua</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -83,14 +83,14 @@ Lua is an extension programming language designed to support general procedural eLua stands for Embedded Lua (can be thought of as a flavor of Lua) and offers the full implementation of the Lua programming language to the embedded world, extending it with specific features for efficient and portable software embedded development. eLua runs on smaller devices like microcontrollers and provides the full features of the regular Lua desktop version. More information on eLua can be found here: <a href="http://www.eluaproject.net">http://www.eluaproject.net</a> </p> -<H2><a name="Lua_nn2">29.1 Preliminaries</a></H2> +<H2><a name="Lua_nn2">30.1 Preliminaries</a></H2> <p> The current SWIG implementation is designed to work with Lua 5.0.x, 5.1.x and 5.2.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. It is possible to either static link or dynamic link a Lua module into the interpreter (normally Lua static links its libraries, as dynamic linking is not available on all platforms). SWIG also has support for eLua starting from eLua 0.8. Due to substantial changes between SWIG 2.x and SWIG 3.0 and unavailability of testing platform, eLua status was downgraded to 'experimental'. </p> -<H2><a name="Lua_nn3">29.2 Running SWIG</a></H2> +<H2><a name="Lua_nn3">30.2 Running SWIG</a></H2> <p> @@ -138,7 +138,7 @@ $ swig -lua -eluac example.i The <tt>-elua</tt> option puts all the C function wrappers and variable get/set wrappers in rotables. It also generates a metatable which will control the access to these variables from eLua. It also offers a significant amount of module size compression. On the other hand, the <tt>-eluac</tt> option puts all the wrappers in a single rotable. With this option, no matter how huge the module, it will consume no additional microcontroller SRAM (crass compression). There is a catch though: Metatables are not generated with <tt>-eluac</tt>. To access any value from eLua, one must directly call the wrapper function associated with that value. </p> -<H3><a name="Lua_commandline">29.2.1 Additional command line options</a></H3> +<H3><a name="Lua_commandline">30.2.1 Additional command line options</a></H3> <p> @@ -179,7 +179,7 @@ swig -lua -help </tr> </table> -<H3><a name="Lua_nn4">29.2.2 Compiling and Linking and Interpreter</a></H3> +<H3><a name="Lua_nn4">30.2.2 Compiling and Linking and Interpreter</a></H3> <p> @@ -250,7 +250,7 @@ LUALIB_API int ( luaopen_mod )(lua_State *L ); More information on building and configuring eLua can be found here: <a href="http://www.eluaproject.net/doc/v0.8/en_building.html">http://www.eluaproject.net/doc/v0.8/en_building.html</a> </p> -<H3><a name="Lua_nn5">29.2.3 Compiling a dynamic module</a></H3> +<H3><a name="Lua_nn5">30.2.3 Compiling a dynamic module</a></H3> <p> @@ -318,7 +318,7 @@ Is quite obvious (Go back and consult the Lua documents on how to enable loadlib -<H3><a name="Lua_nn6">29.2.4 Using your module</a></H3> +<H3><a name="Lua_nn6">30.2.4 Using your module</a></H3> <p> @@ -336,19 +336,19 @@ $ ./my_lua > </pre></div> -<H2><a name="Lua_nn7">29.3 A tour of basic C/C++ wrapping</a></H2> +<H2><a name="Lua_nn7">30.3 A tour of basic C/C++ wrapping</a></H2> <p> By default, SWIG tries to build a very natural Lua interface to your C/C++ code. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Lua_nn8">29.3.1 Modules</a></H3> +<H3><a name="Lua_nn8">30.3.1 Modules</a></H3> <p> The SWIG module directive specifies the name of the Lua module. If you specify `module example', then everything is wrapped into a Lua table 'example' containing all the functions and variables. When choosing a module name, make sure you don't use the same name as a built-in Lua command or standard module name. </p> -<H3><a name="Lua_nn9">29.3.2 Functions</a></H3> +<H3><a name="Lua_nn9">30.3.2 Functions</a></H3> <p> @@ -389,7 +389,7 @@ It is also possible to rename the module with an assignment. 24 </pre></div> -<H3><a name="Lua_nn10">29.3.3 Global variables</a></H3> +<H3><a name="Lua_nn10">30.3.3 Global variables</a></H3> <p> @@ -477,7 +477,7 @@ If you have used the <tt>-eluac</tt> option for your eLua module, you will have In general, functions of the form <tt>"variable_get()"</tt> and <tt>"variable_set()"</tt> are automatically generated by SWIG for use with <tt>-eluac</tt>. </p> -<H3><a name="Lua_nn11">29.3.4 Constants and enums</a></H3> +<H3><a name="Lua_nn11">30.3.4 Constants and enums</a></H3> <p> @@ -512,7 +512,7 @@ If you're using eLua and have used <tt>-elua</tt> or <tt>-eluac</tt> to generate Hello World </pre></div> -<H4><a name="Lua_nn13">29.3.4.1 Constants/enums and classes/structures</a></H4> +<H4><a name="Lua_nn13">30.3.4.1 Constants/enums and classes/structures</a></H4> <p> @@ -568,7 +568,7 @@ If the <tt>-no-old-metatable-bindings</tt> option is used, then these old-style It is worth mentioning, that <tt>example.Test.TEST1</tt> and <tt>example.Test_TEST1</tt> are different entities and changing one does not change the other. Given the fact that these are constantes and they are not supposed to be changed, it is up to you to avoid such issues. </p> -<H3><a name="Lua_nn12">29.3.5 Pointers</a></H3> +<H3><a name="Lua_nn12">30.3.5 Pointers</a></H3> <p> @@ -606,7 +606,7 @@ Lua enforces the integrity of its userdata, so it is virtually impossible to cor nil </pre></div> -<H3><a name="Lua_structures">29.3.6 Structures</a></H3> +<H3><a name="Lua_structures">30.3.6 Structures</a></H3> <p> @@ -710,7 +710,7 @@ For eLua with the <tt>-eluac</tt> option, structure manipulation has to be perfo In general, functions of the form <tt>"new_struct()"</tt>, <tt>"struct_member_get()"</tt>, <tt>"struct_member_set()"</tt> and <tt>"free_struct()"</tt> are automatically generated by SWIG for each structure defined in C. (Please note: This doesn't apply for modules generated with the <tt>-elua</tt> option) </p> -<H3><a name="Lua_nn14">29.3.7 C++ classes</a></H3> +<H3><a name="Lua_nn14">30.3.7 C++ classes</a></H3> <p> @@ -785,7 +785,7 @@ Both style names are generated by default now. However, if the <tt>-no-old-metatable-bindings</tt> option is used, then the backward compatible names are not generated in addition to ordinary ones. </p> -<H3><a name="Lua_nn15">29.3.8 C++ inheritance</a></H3> +<H3><a name="Lua_nn15">30.3.8 C++ inheritance</a></H3> <p> @@ -810,7 +810,7 @@ then the function <tt>spam()</tt> accepts a Foo pointer or a pointer to any clas <p> It is safe to use multiple inheritance with SWIG. </p> -<H3><a name="Lua_nn16">29.3.9 Pointers, references, values, and arrays</a></H3> +<H3><a name="Lua_nn16">30.3.9 Pointers, references, values, and arrays</a></H3> <p> @@ -841,7 +841,7 @@ Foo spam7(); <p> then all three functions will return a pointer to some Foo object. Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Lua will release this memory when the return value is garbage collected). The other two are pointers which are assumed to be managed by the C code and so will not be garbage collected. </p> -<H3><a name="Lua_nn17">29.3.10 C++ overloaded functions</a></H3> +<H3><a name="Lua_nn17">30.3.10 C++ overloaded functions</a></H3> <p> @@ -927,7 +927,7 @@ Please refer to the "SWIG and C++" chapter for more information about overloadin <p> Dealing with the Lua coercion mechanism, the priority is roughly (integers, floats, strings, userdata). But it is better to rename the functions rather than rely upon the ordering. </p> -<H3><a name="Lua_nn18">29.3.11 C++ operators</a></H3> +<H3><a name="Lua_nn18">30.3.11 C++ operators</a></H3> <p> @@ -1059,7 +1059,7 @@ operators and pseudo-operators):</p> </ul> <p>No other lua metafunction is inherited. For example, __gc is not inherited and must be redefined in every class. <tt>__tostring</tt> is subject to a special handling. If absent in class and in class bases, a default one will be provided by SWIG. </p> -<H3><a name="Lua_nn19">29.3.12 Class extension with %extend</a></H3> +<H3><a name="Lua_nn19">30.3.12 Class extension with %extend</a></H3> <p> @@ -1116,7 +1116,7 @@ true Extend works with both C and C++ code, on classes and structs. It does not modify the underlying object in any way---the extensions only show up in the Lua interface. The only item to take note of is the code has to use the '$self' instead of 'this', and that you cannot access protected/private members of the code (as you are not officially part of the class). </p> -<H3><a name="Lua_nn20">29.3.13 Using %newobject to release memory</a></H3> +<H3><a name="Lua_nn20">30.3.13 Using %newobject to release memory</a></H3> <p> If you have a function that allocates memory like this,</p> @@ -1140,7 +1140,7 @@ char *foo(); </div> <p> This will release the allocated memory.</p> -<H3><a name="Lua_nn21">29.3.14 C++ templates</a></H3> +<H3><a name="Lua_nn21">30.3.14 C++ templates</a></H3> <p> @@ -1175,7 +1175,7 @@ In Lua: <p> Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. Some more complicated examples will appear later. </p> -<H3><a name="Lua_nn22">29.3.15 C++ Smart Pointers</a></H3> +<H3><a name="Lua_nn22">30.3.15 C++ Smart Pointers</a></H3> <p> @@ -1227,7 +1227,7 @@ If you ever need to access the underlying pointer returned by <tt>operator->( > f = p:__deref__() -- Returns underlying Foo * </pre></div> -<H3><a name="Lua_nn23">29.3.16 C++ Exceptions</a></H3> +<H3><a name="Lua_nn23">30.3.16 C++ Exceptions</a></H3> <p> @@ -1370,7 +1370,7 @@ and the "<a href="Customization.html#Customization_exception">Exception handling add exception specification to functions or globally (respectively). </p> -<H3><a name="Lua_namespaces">29.3.17 Namespaces </a></H3> +<H3><a name="Lua_namespaces">30.3.17 Namespaces </a></H3> <p> @@ -1421,7 +1421,7 @@ Now, from Lua usage is as follows: 19 > </pre></div> -<H4><a name="Lua_nn27">29.3.17.1 Compatibility Note </a></H4> +<H4><a name="Lua_nn27">30.3.17.1 Compatibility Note </a></H4> <p> @@ -1437,7 +1437,7 @@ If SWIG is running in a backwards compatible way, i.e. without the <tt>-no-old-m </pre></div> -<H4><a name="Lua_nn29">29.3.17.2 Names </a></H4> +<H4><a name="Lua_nn29">30.3.17.2 Names </a></H4> <p> If SWIG is launched without <tt>-no-old-metatable-bindings</tt> option, then it enters backward-compatible mode. While in this mode, it tries @@ -1481,7 +1481,7 @@ surrounding scope without any prefixing. Pretending that Test2 is a struct, not > </pre></div> -<H4><a name="Lua_nn30">29.3.17.3 Inheritance </a></H4> +<H4><a name="Lua_nn30">30.3.17.3 Inheritance </a></H4> <p> The internal organization of inheritance has changed. @@ -1522,12 +1522,12 @@ function > </pre></div> -<H2><a name="Lua_nn24">29.4 Typemaps</a></H2> +<H2><a name="Lua_nn24">30.4 Typemaps</a></H2> <p>This section explains what typemaps are and how to use them. The default wrapping behaviour of SWIG is enough in most cases. However sometimes SWIG may need a little additional assistance to know which typemap to apply to provide the best wrapping. This section will be explaining how to use typemaps to best effect</p> -<H3><a name="Lua_nn25">29.4.1 What is a typemap?</a></H3> +<H3><a name="Lua_nn25">30.4.1 What is a typemap?</a></H3> <p>A typemap is nothing more than a code generation rule that is attached to a specific C datatype. For example, to convert integers from Lua to C, you might define a typemap like this:</p> @@ -1555,7 +1555,7 @@ Received an integer : 6 720 </pre></div> -<H3><a name="Lua_nn26">29.4.2 Using typemaps</a></H3> +<H3><a name="Lua_nn26">30.4.2 Using typemaps</a></H3> <p>There are many ready written typemaps built into SWIG for all common types (int, float, short, long, char*, enum and more), which SWIG uses automatically, with no effort required on your part.</p> @@ -1608,7 +1608,7 @@ void swap(int *sx, int *sy); <p>Note: C++ references must be handled exactly the same way. However SWIG will automatically wrap a <tt>const int&</tt> as an input parameter (since that it obviously input).</p> -<H3><a name="Lua_typemap_arrays">29.4.3 Typemaps and arrays</a></H3> +<H3><a name="Lua_typemap_arrays">30.4.3 Typemaps and arrays</a></H3> <p>Arrays present a challenge for SWIG, because like pointers SWIG does not know whether these are input or output values, nor @@ -1672,7 +1672,7 @@ and Lua tables to be 1..N, (the indexing follows the norm for the language). In <p>Note: SWIG also can support arrays of pointers in a similar manner.</p> -<H3><a name="Lua_typemaps_ptr_ptr_functions">29.4.4 Typemaps and pointer-pointer functions</a></H3> +<H3><a name="Lua_typemaps_ptr_ptr_functions">30.4.4 Typemaps and pointer-pointer functions</a></H3> <p>Several C++ libraries use a pointer-pointer functions to create its objects. These functions require a pointer to a pointer which is then filled with the pointer to the new object. Microsoft's COM and DirectX as well as many other libraries have this kind of function. An example is given below:</p> @@ -1706,7 +1706,7 @@ int Create_Math(iMath** pptr); // its creator (assume it mallocs) ptr=nil -- the iMath* will be GC'ed as normal </pre></div> -<H2><a name="Lua_writing_typemaps">29.5 Writing typemaps</a></H2> +<H2><a name="Lua_writing_typemaps">30.5 Writing typemaps</a></H2> <p>This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the <tt>%typemap</tt> directive. This is an advanced topic that assumes familiarity with the Lua C API as well as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.</p> @@ -1715,7 +1715,7 @@ ptr=nil -- the iMath* will be GC'ed as normal <p>Before proceeding, you should read the previous section on using typemaps, and look at the existing typemaps found in luatypemaps.swg and typemaps.i. These are both well documented and fairly easy to read. You should not attempt to write your own typemaps until you have read and can understand both of these files (they may well also give you an idea to base your work on).</p> -<H3><a name="Lua_typemaps_write">29.5.1 Typemaps you can write</a></H3> +<H3><a name="Lua_typemaps_write">30.5.1 Typemaps you can write</a></H3> <p>There are many different types of typemap that can be written, the full list can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. However the following are the most commonly used ones.</p> @@ -1728,7 +1728,7 @@ ptr=nil -- the iMath* will be GC'ed as normal (the syntax for the typecheck is different from the typemap, see typemaps for details).</li> </ul> -<H3><a name="Lua_nn31">29.5.2 SWIG's Lua-C API</a></H3> +<H3><a name="Lua_nn31">30.5.2 SWIG's Lua-C API</a></H3> <p>This section explains the SWIG specific Lua-C API. It does not cover the main Lua-C api, as this is well documented and not worth covering.</p> @@ -1777,7 +1777,7 @@ This macro, when called within the context of a SWIG wrapped function, will disp <div class="indent"> Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.</div> -<H2><a name="Lua_nn32">29.6 Customization of your Bindings</a></H2> +<H2><a name="Lua_nn32">30.6 Customization of your Bindings</a></H2> <p> @@ -1786,7 +1786,7 @@ This section covers adding of some small extra bits to your module to add the la -<H3><a name="Lua_nn33">29.6.1 Writing your own custom wrappers</a></H3> +<H3><a name="Lua_nn33">30.6.1 Writing your own custom wrappers</a></H3> <p> @@ -1805,7 +1805,7 @@ int native_function(lua_State*L) // my native code The <tt>%native</tt> directive in the above example, tells SWIG that there is a function <tt>int native_function(lua_State*L);</tt> which is to be added into the module under the name '<tt>my_func</tt>'. SWIG will not add any wrapper for this function, beyond adding it into the function table. How you write your code is entirely up to you. </p> -<H3><a name="Lua_nn34">29.6.2 Adding additional Lua code</a></H3> +<H3><a name="Lua_nn34">30.6.2 Adding additional Lua code</a></H3> <p> @@ -1843,7 +1843,7 @@ Good uses for this feature is adding of new code, or writing helper functions to See Examples/lua/arrays for an example of this code. </p> -<H2><a name="Lua_nn35">29.7 Details on the Lua binding</a></H2> +<H2><a name="Lua_nn35">30.7 Details on the Lua binding</a></H2> <p> @@ -1854,7 +1854,7 @@ See Examples/lua/arrays for an example of this code. </i> </p> -<H3><a name="Lua_nn36">29.7.1 Binding global data into the module.</a></H3> +<H3><a name="Lua_nn36">30.7.1 Binding global data into the module.</a></H3> <p> @@ -1914,7 +1914,7 @@ end <p> That way when you call '<tt>a=example.Foo</tt>', the interpreter looks at the table 'example' sees that there is no field 'Foo' and calls __index. This will in turn check in '.get' table and find the existence of 'Foo' and then return the value of the C function call 'Foo_get()'. Similarly for the code '<tt>example.Foo=10</tt>', the interpreter will check the table, then call the __newindex which will then check the '.set' table and call the C function 'Foo_set(10)'. </p> -<H3><a name="Lua_nn37">29.7.2 Userdata and Metatables</a></H3> +<H3><a name="Lua_nn37">30.7.2 Userdata and Metatables</a></H3> <p> @@ -1994,7 +1994,7 @@ Note: Both the opaque structures (like the FILE*) and normal wrapped classes/str <p> Note: Operator overloads are basically done in the same way, by adding functions such as '__add' & '__call' to the class' metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload. </p> -<H3><a name="Lua_nn38">29.7.3 Memory management</a></H3> +<H3><a name="Lua_nn38">30.7.3 Memory management</a></H3> <p> diff --git a/Doc/Manual/Modula3.html b/Doc/Manual/Modula3.html index bdfc5992d..fc4ffa03c 100644 --- a/Doc/Manual/Modula3.html +++ b/Doc/Manual/Modula3.html @@ -6,7 +6,7 @@ <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body bgcolor="#FFFFFF"> -<H1><a name="Modula3">30 SWIG and Modula-3</a></H1> +<H1><a name="Modula3">31 SWIG and Modula-3</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -55,7 +55,7 @@ especially <a href="Typemaps.html#Typemaps">typemaps</a>. </p> -<H2><a name="Modula3_modula3_overview">30.1 Overview</a></H2> +<H2><a name="Modula3_modula3_overview">31.1 Overview</a></H2> <p> @@ -85,7 +85,7 @@ FFTW </li> </ol> -<H3><a name="Modula3_motivation">30.1.1 Motivation</a></H3> +<H3><a name="Modula3_motivation">31.1.1 Motivation</a></H3> <p> @@ -132,10 +132,10 @@ functions), but it doesn't allow you to easily integrate a Modula-3 module into a C/C++ project. </p> -<H2><a name="Modula3_conception">30.2 Conception</a></H2> +<H2><a name="Modula3_conception">31.2 Conception</a></H2> -<H3><a name="Modula3_cinterface">30.2.1 Interfaces to C libraries</a></H3> +<H3><a name="Modula3_cinterface">31.2.1 Interfaces to C libraries</a></H3> <p> @@ -284,7 +284,7 @@ and the principal type must be renamed (<tt>%typemap</tt>). </p> -<H3><a name="Modula3_cppinterface">30.2.2 Interfaces to C++ libraries</a></H3> +<H3><a name="Modula3_cppinterface">31.2.2 Interfaces to C++ libraries</a></H3> <p> @@ -385,10 +385,10 @@ There is no C++ library I wrote a SWIG interface for, so I'm not sure if this is possible or sensible, yet. </p> -<H2><a name="Modula3_preliminaries">30.3 Preliminaries</a></H2> +<H2><a name="Modula3_preliminaries">31.3 Preliminaries</a></H2> -<H3><a name="Modula3_compilers">30.3.1 Compilers</a></H3> +<H3><a name="Modula3_compilers">31.3.1 Compilers</a></H3> <p> @@ -401,7 +401,7 @@ For testing examples I use Critical Mass cm3. </p> -<H3><a name="Modula3_commandline">30.3.2 Additional Commandline Options</a></H3> +<H3><a name="Modula3_commandline">31.3.2 Additional Commandline Options</a></H3> <p> @@ -478,10 +478,10 @@ Instead generate templates for some basic typemaps. </tr> </table> -<H2><a name="Modula3_typemaps">30.4 Modula-3 typemaps</a></H2> +<H2><a name="Modula3_typemaps">31.4 Modula-3 typemaps</a></H2> -<H3><a name="Modula3_inoutparam">30.4.1 Inputs and outputs</a></H3> +<H3><a name="Modula3_inoutparam">31.4.1 Inputs and outputs</a></H3> <p> @@ -695,7 +695,7 @@ consist of the following parts: </table> -<H3><a name="Modula3_ordinals">30.4.2 Subranges, Enumerations, Sets</a></H3> +<H3><a name="Modula3_ordinals">31.4.2 Subranges, Enumerations, Sets</a></H3> <p> @@ -747,7 +747,7 @@ that I'd like to automate. </p> -<H3><a name="Modula3_class">30.4.3 Objects</a></H3> +<H3><a name="Modula3_class">31.4.3 Objects</a></H3> <p> @@ -760,7 +760,7 @@ is not really useful, yet. </p> -<H3><a name="Modula3_imports">30.4.4 Imports</a></H3> +<H3><a name="Modula3_imports">31.4.4 Imports</a></H3> <p> @@ -793,7 +793,7 @@ IMPORT M3toC; </pre></div> -<H3><a name="Modula3_exceptions">30.4.5 Exceptions</a></H3> +<H3><a name="Modula3_exceptions">31.4.5 Exceptions</a></H3> <p> @@ -817,7 +817,7 @@ you should declare <tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>. </p> -<H3><a name="Modula3_typemap_example">30.4.6 Example</a></H3> +<H3><a name="Modula3_typemap_example">31.4.6 Example</a></H3> <p> @@ -864,10 +864,10 @@ where almost everything is generated by a typemap: </pre></div> -<H2><a name="Modula3_hints">30.5 More hints to the generator</a></H2> +<H2><a name="Modula3_hints">31.5 More hints to the generator</a></H2> -<H3><a name="Modula3_features">30.5.1 Features</a></H3> +<H3><a name="Modula3_features">31.5.1 Features</a></H3> <table border summary="Modula-3 features"> @@ -904,7 +904,7 @@ where almost everything is generated by a typemap: </tr> </table> -<H3><a name="Modula3_pragmas">30.5.2 Pragmas</a></H3> +<H3><a name="Modula3_pragmas">31.5.2 Pragmas</a></H3> <table border summary="Modula-3 pragmas"> @@ -927,7 +927,7 @@ where almost everything is generated by a typemap: </tr> </table> -<H2><a name="Modula3_remarks">30.6 Remarks</a></H2> +<H2><a name="Modula3_remarks">31.6 Remarks</a></H2> <ul> diff --git a/Doc/Manual/Modules.html b/Doc/Manual/Modules.html index 682e549e0..19b69e5f4 100644 --- a/Doc/Manual/Modules.html +++ b/Doc/Manual/Modules.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Modules">17 Working with Modules</a></H1> +<H1><a name="Modules">18 Working with Modules</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -24,7 +24,7 @@ -<H2><a name="Modules_introduction">17.1 Modules Introduction</a></H2> +<H2><a name="Modules_introduction">18.1 Modules Introduction</a></H2> <p> @@ -78,7 +78,7 @@ where you want to create a collection of modules. Each module in the collection is created via separate invocations of SWIG. </p> -<H2><a name="Modules_nn1">17.2 Basics</a></H2> +<H2><a name="Modules_nn1">18.2 Basics</a></H2> <p> @@ -177,7 +177,7 @@ in parallel from multiple threads as SWIG provides no locking - for more on that issue, read on. </p> -<H2><a name="Modules_nn2">17.3 The SWIG runtime code</a></H2> +<H2><a name="Modules_nn2">18.3 The SWIG runtime code</a></H2> <p> @@ -243,7 +243,7 @@ can peacefully coexist. So the type structures are separated by the is empty. Only modules compiled with the same pair will share type information. </p> -<H2><a name="Modules_external_run_time">17.4 External access to the runtime</a></H2> +<H2><a name="Modules_external_run_time">18.4 External access to the runtime</a></H2> <p>As described in <a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>, @@ -282,7 +282,7 @@ SWIG_TYPE_TABLE to be the same as the module whose types you are trying to access. </p> -<H2><a name="Modules_nn4">17.5 A word of caution about static libraries</a></H2> +<H2><a name="Modules_nn4">18.5 A word of caution about static libraries</a></H2> <p> @@ -293,7 +293,7 @@ into it. This is very often <b>NOT</b> what you want and it can lead to unexpect behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries. </p> -<H2><a name="Modules_nn5">17.6 References</a></H2> +<H2><a name="Modules_nn5">18.6 References</a></H2> <p> @@ -301,7 +301,7 @@ Due to the complexity of working with shared libraries and multiple modules, it an outside reference. John Levine's "Linkers and Loaders" is highly recommended. </p> -<H2><a name="Modules_nn6">17.7 Reducing the wrapper file size</a></H2> +<H2><a name="Modules_nn6">18.7 Reducing the wrapper file size</a></H2> <p> diff --git a/Doc/Manual/Mzscheme.html b/Doc/Manual/Mzscheme.html index 0e85fdbfa..c3af5c49e 100644 --- a/Doc/Manual/Mzscheme.html +++ b/Doc/Manual/Mzscheme.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Mzscheme">31 SWIG and MzScheme/Racket</a></H1> +<H1><a name="Mzscheme">32 SWIG and MzScheme/Racket</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -24,7 +24,7 @@ <p> This section contains information on SWIG's support of Racket, formally known as MzScheme. -<H2><a name="MzScheme_nn2">31.1 Creating native structures</a></H2> +<H2><a name="MzScheme_nn2">32.1 Creating native structures</a></H2> <p> @@ -65,7 +65,7 @@ Then in scheme, you can use regular struct access procedures like </pre> </div> -<H2><a name="MzScheme_simple">31.2 Simple example</a></H2> +<H2><a name="MzScheme_simple">32.2 Simple example</a></H2> <p> @@ -166,7 +166,7 @@ Some points of interest: <li> The above requests mzc to create an extension using the CGC garbage-collector. The alternative -- the 3m collector -- has generally better performance, but work is still required for SWIG to emit code which is compatible with it. </ul> -<H2><a name="MzScheme_external_docs">31.3 External documentation</a></H2> +<H2><a name="MzScheme_external_docs">32.3 External documentation</a></H2> <p> diff --git a/Doc/Manual/Ocaml.html b/Doc/Manual/Ocaml.html index 2466fc5bc..70504cf15 100644 --- a/Doc/Manual/Ocaml.html +++ b/Doc/Manual/Ocaml.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Ocaml">32 SWIG and Ocaml</a></H1> +<H1><a name="Ocaml">33 SWIG and Ocaml</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -84,7 +84,7 @@ If you're not familiar with the Objective Caml language, you can visit <a href="http://ocaml.org/">The Ocaml Website</a>. </p> -<H2><a name="Ocaml_nn2">32.1 Preliminaries</a></H2> +<H2><a name="Ocaml_nn2">33.1 Preliminaries</a></H2> <p> @@ -102,7 +102,7 @@ file Examples/Makefile illustrate how to compile and link SWIG modules that will be loaded dynamically. This has only been tested on Linux so far. </p> -<H3><a name="Ocaml_nn3">32.1.1 Running SWIG</a></H3> +<H3><a name="Ocaml_nn3">33.1.1 Running SWIG</a></H3> <p> @@ -125,7 +125,7 @@ you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or the resulting .ml and .mli files as well, and do the final link with -custom (not needed for native link).</p> -<H3><a name="Ocaml_nn4">32.1.2 Compiling the code</a></H3> +<H3><a name="Ocaml_nn4">33.1.2 Compiling the code</a></H3> <p> @@ -162,7 +162,7 @@ in C++ mode, you must:</p> </pre> </div> -<H3><a name="Ocaml_nn5">32.1.3 The camlp4 module</a></H3> +<H3><a name="Ocaml_nn5">33.1.3 The camlp4 module</a></H3> <p> @@ -238,7 +238,7 @@ let b = C_string (getenv "PATH") </td></tr> </table> -<H3><a name="Ocaml_nn6">32.1.4 Using your module</a></H3> +<H3><a name="Ocaml_nn6">33.1.4 Using your module</a></H3> <p> @@ -252,7 +252,7 @@ option to build your functions into the primitive list. This option is not needed when you build native code. </p> -<H3><a name="Ocaml_nn7">32.1.5 Compilation problems and compiling with C++</a></H3> +<H3><a name="Ocaml_nn7">33.1.5 Compilation problems and compiling with C++</a></H3> <p> @@ -263,7 +263,7 @@ liberal with pointer types may not compile under the C++ compiler. Most code meant to be compiled as C++ will not have problems. </p> -<H2><a name="Ocaml_nn8">32.2 The low-level Ocaml/C interface</a></H2> +<H2><a name="Ocaml_nn8">33.2 The low-level Ocaml/C interface</a></H2> <p> @@ -363,7 +363,7 @@ value items pass through directly, but you must make your own type signature for a function that uses value in this way. </p> -<H3><a name="Ocaml_nn9">32.2.1 The generated module</a></H3> +<H3><a name="Ocaml_nn9">33.2.1 The generated module</a></H3> <p> @@ -397,7 +397,7 @@ it describes the output SWIG will generate for class definitions. </td></tr> </table> -<H3><a name="Ocaml_nn10">32.2.2 Enums</a></H3> +<H3><a name="Ocaml_nn10">33.2.2 Enums</a></H3> <p> @@ -460,7 +460,7 @@ val x : Enum_test.c_obj = C_enum `a </pre> </div> -<H4><a name="Ocaml_nn11">32.2.2.1 Enum typing in Ocaml</a></H4> +<H4><a name="Ocaml_nn11">33.2.2.1 Enum typing in Ocaml</a></H4> <p> @@ -473,10 +473,10 @@ functions imported from different modules. You must convert values to master values using the swig_val function before sharing them with another module. </p> -<H3><a name="Ocaml_nn12">32.2.3 Arrays</a></H3> +<H3><a name="Ocaml_nn12">33.2.3 Arrays</a></H3> -<H4><a name="Ocaml_nn13">32.2.3.1 Simple types of bounded arrays</a></H4> +<H4><a name="Ocaml_nn13">33.2.3.1 Simple types of bounded arrays</a></H4> <p> @@ -497,7 +497,7 @@ arrays of simple types with known bounds in your code, but this only works for arrays whose bounds are completely specified. </p> -<H4><a name="Ocaml_nn14">32.2.3.2 Complex and unbounded arrays</a></H4> +<H4><a name="Ocaml_nn14">33.2.3.2 Complex and unbounded arrays</a></H4> <p> @@ -510,7 +510,7 @@ SWIG can't predict which of these methods will be used in the array, so you have to specify it for yourself in the form of a typemap. </p> -<H4><a name="Ocaml_nn15">32.2.3.3 Using an object</a></H4> +<H4><a name="Ocaml_nn15">33.2.3.3 Using an object</a></H4> <p> @@ -524,7 +524,7 @@ Consider writing an object when the ending condition of your array is complex, such as using a required sentinel, etc. </p> -<H4><a name="Ocaml_nn16">32.2.3.4 Example typemap for a function taking float * and int</a></H4> +<H4><a name="Ocaml_nn16">33.2.3.4 Example typemap for a function taking float * and int</a></H4> <p> @@ -575,7 +575,7 @@ void printfloats( float *tab, int len ); </pre></td></tr></table> -<H3><a name="Ocaml_nn17">32.2.4 C++ Classes</a></H3> +<H3><a name="Ocaml_nn17">33.2.4 C++ Classes</a></H3> <p> @@ -618,7 +618,7 @@ the underlying pointer, so using create_[x]_from_ptr alters the returned value for the same object. </p> -<H4><a name="Ocaml_nn18">32.2.4.1 STL vector and string Example</a></H4> +<H4><a name="Ocaml_nn18">33.2.4.1 STL vector and string Example</a></H4> <p> @@ -698,7 +698,7 @@ baz # </pre></div> -<H4><a name="Ocaml_nn19">32.2.4.2 C++ Class Example</a></H4> +<H4><a name="Ocaml_nn19">33.2.4.2 C++ Class Example</a></H4> <p> @@ -728,7 +728,7 @@ public: }; </pre></td></tr></table> -<H4><a name="Ocaml_nn20">32.2.4.3 Compiling the example</a></H4> +<H4><a name="Ocaml_nn20">33.2.4.3 Compiling the example</a></H4> <div class="code"><pre> @@ -746,7 +746,7 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \ -L$QTPATH/lib -cclib -lqt </pre></div> -<H4><a name="Ocaml_nn21">32.2.4.4 Sample Session</a></H4> +<H4><a name="Ocaml_nn21">33.2.4.4 Sample Session</a></H4> <div class="code"><pre> @@ -773,10 +773,10 @@ Assuming you have a working installation of QT, you will see a window containing the string "hi" in a button. </p> -<H3><a name="Ocaml_nn22">32.2.5 Director Classes</a></H3> +<H3><a name="Ocaml_nn22">33.2.5 Director Classes</a></H3> -<H4><a name="Ocaml_nn23">32.2.5.1 Director Introduction</a></H4> +<H4><a name="Ocaml_nn23">33.2.5.1 Director Introduction</a></H4> <p> @@ -803,7 +803,7 @@ class foo { }; </pre></div> -<H4><a name="Ocaml_nn24">32.2.5.2 Overriding Methods in Ocaml</a></H4> +<H4><a name="Ocaml_nn24">33.2.5.2 Overriding Methods in Ocaml</a></H4> <p> @@ -831,7 +831,7 @@ In this example, I'll examine the objective caml code involved in providing an overloaded class. This example is contained in Examples/ocaml/shapes. </p> -<H4><a name="Ocaml_nn25">32.2.5.3 Director Usage Example</a></H4> +<H4><a name="Ocaml_nn25">33.2.5.3 Director Usage Example</a></H4> <table border="1" bgcolor="#dddddd" summary="Director usage example"> @@ -890,7 +890,7 @@ in a more effortless style in ocaml, while leaving the "engine" part of the program in C++. </p> -<H4><a name="Ocaml_nn26">32.2.5.4 Creating director objects</a></H4> +<H4><a name="Ocaml_nn26">33.2.5.4 Creating director objects</a></H4> <p> @@ -931,7 +931,7 @@ object from causing a core dump, as long as the object is destroyed properly. </p> -<H4><a name="Ocaml_nn27">32.2.5.5 Typemaps for directors, directorin, directorout, directorargout</a></H4> +<H4><a name="Ocaml_nn27">33.2.5.5 Typemaps for directors, directorin, directorout, directorargout</a></H4> <p> @@ -942,7 +942,7 @@ well as a function return value in the same way you provide function arguments, and to receive arguments the same way you normally receive function returns. </p> -<H4><a name="Ocaml_nn28">32.2.5.6 typemap</a></H4> +<H4><a name="Ocaml_nn28">33.2.5.6 typemap</a></H4> <p> @@ -953,7 +953,7 @@ code receives when you are called. In general, a simple <tt>directorin</tt> typ can use the same body as a simple <tt>out</tt> typemap. </p> -<H4><a name="Ocaml_nn29">32.2.5.7 directorout typemap</a></H4> +<H4><a name="Ocaml_nn29">33.2.5.7 directorout typemap</a></H4> <p> @@ -964,7 +964,7 @@ for the same type, except when there are special requirements for object ownership, etc. </p> -<H4><a name="Ocaml_nn30">32.2.5.8 directorargout typemap</a></H4> +<H4><a name="Ocaml_nn30">33.2.5.8 directorargout typemap</a></H4> <p> @@ -981,7 +981,7 @@ In the event that you don't specify all of the necessary values, integral values will read zero, and struct or object returns have undefined results. </p> -<H3><a name="Ocaml_nn31">32.2.6 Exceptions</a></H3> +<H3><a name="Ocaml_nn31">33.2.6 Exceptions</a></H3> <p> diff --git a/Doc/Manual/Octave.html b/Doc/Manual/Octave.html index 606ca820c..1295966bd 100644 --- a/Doc/Manual/Octave.html +++ b/Doc/Manual/Octave.html @@ -9,7 +9,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Octave">33 SWIG and Octave</a></H1> +<H1><a name="Octave">34 SWIG and Octave</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -60,7 +60,7 @@ This chapter is intended to give an introduction to using the module. You should Also, there are a dozen or so examples in the Examples/octave directory, and hundreds in the test suite (Examples/test-suite and Examples/test-suite/octave). </p> -<H2><a name="Octave_nn2">33.1 Preliminaries</a></H2> +<H2><a name="Octave_nn2">34.1 Preliminaries</a></H2> <p> @@ -76,7 +76,7 @@ This cannot be guaranteed however, as in recent times new Octave releases have r The SWIG runtime exports the function <tt>swig_octave_prereq()</tt> for checking the version of Octave. </p> -<H2><a name="Octave_nn3">33.2 Running SWIG</a></H2> +<H2><a name="Octave_nn3">34.2 Running SWIG</a></H2> <p> @@ -108,7 +108,7 @@ The <tt>-c++</tt> option is also required when wrapping C++ code: This creates a C++ source file "example_wrap.cpp". A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module. </p> -<H3><a name="Octave_nn4">33.2.1 Command-line options</a></H3> +<H3><a name="Octave_nn4">34.2.1 Command-line options</a></H3> <p> @@ -131,7 +131,7 @@ The special name "." loads C global variables into the module namespace, i.e. al The <em>-opprefix</em> options sets the prefix of the names of global/friend <a href="#Octave_nn18">operator</a> functions. </p> -<H3><a name="Octave_nn5">33.2.2 Compiling a dynamic module</a></H3> +<H3><a name="Octave_nn5">34.2.2 Compiling a dynamic module</a></H3> <p> @@ -158,7 +158,7 @@ $ mkoctfile example_wrap.cpp example.c <div class="targetlang"><pre>octave:1> swigexample</pre></div> -<H3><a name="Octave_nn6">33.2.3 Using your module</a></H3> +<H3><a name="Octave_nn6">34.2.3 Using your module</a></H3> <p> @@ -176,10 +176,10 @@ octave:4> swigexample.cvar.Foo=4; octave:5> swigexample.cvar.Foo ans = 4 </pre></div> -<H2><a name="Octave_nn7">33.3 A tour of basic C/C++ wrapping</a></H2> +<H2><a name="Octave_nn7">34.3 A tour of basic C/C++ wrapping</a></H2> -<H3><a name="Octave_nn8">33.3.1 Modules</a></H3> +<H3><a name="Octave_nn8">34.3.1 Modules</a></H3> <p> @@ -224,7 +224,7 @@ octave:4> swigexample.gcd(4, 6) ans = 2 </pre></div> -<H3><a name="Octave_nn9">33.3.2 Functions</a></H3> +<H3><a name="Octave_nn9">34.3.2 Functions</a></H3> <p> @@ -241,7 +241,7 @@ int fact(int n); </pre></div> <div class="targetlang"><pre>octave:1> swigexample.fact(4) 24 </pre></div> -<H3><a name="Octave_nn10">33.3.3 Global variables</a></H3> +<H3><a name="Octave_nn10">34.3.3 Global variables</a></H3> <p> @@ -294,7 +294,7 @@ octave:2> swigexample.PI=3.142; octave:3> swigexample.PI ans = 3.1420 </pre></div> -<H3><a name="Octave_nn11">33.3.4 Constants and enums</a></H3> +<H3><a name="Octave_nn11">34.3.4 Constants and enums</a></H3> <p> @@ -316,7 +316,7 @@ swigexample.SCONST="Hello World" swigexample.SUNDAY=0 .... </pre></div> -<H3><a name="Octave_nn12">33.3.5 Pointers</a></H3> +<H3><a name="Octave_nn12">34.3.5 Pointers</a></H3> <p> @@ -363,7 +363,7 @@ octave:2> f=swigexample.fopen("not there", "r"); error: value on right hand side of assignment is undefined error: evaluating assignment expression near line 2, column 2 </pre></div> -<H3><a name="Octave_nn13">33.3.6 Structures and C++ classes</a></H3> +<H3><a name="Octave_nn13">34.3.6 Structures and C++ classes</a></H3> <p> @@ -498,7 +498,7 @@ ans = 1 Depending on the ownership setting of a <tt>swig_ref</tt>, it may call C++ destructors when its reference count goes to zero. See the section on memory management below for details. </p> -<H3><a name="Octave_nn15">33.3.7 C++ inheritance</a></H3> +<H3><a name="Octave_nn15">34.3.7 C++ inheritance</a></H3> <p> @@ -507,7 +507,7 @@ This information contains the full class hierarchy. When an indexing operation ( the tree is walked to find a match in the current class as well as any of its bases. The lookup is then cached in the <tt>swig_ref</tt>. </p> -<H3><a name="Octave_nn17">33.3.8 C++ overloaded functions</a></H3> +<H3><a name="Octave_nn17">34.3.8 C++ overloaded functions</a></H3> <p> @@ -517,7 +517,7 @@ The dispatch function selects which overload to call (if any) based on the passe <tt>typecheck</tt> typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details. </p> -<H3><a name="Octave_nn18">33.3.9 C++ operators</a></H3> +<H3><a name="Octave_nn18">34.3.9 C++ operators</a></H3> <p> @@ -621,7 +621,7 @@ On the C++ side, the default mappings are as follows: Octave can also utilise friend (i.e. non-member) operators with a simple %rename: see the example in the Examples/octave/operator directory. </p> -<H3><a name="Octave_nn19">33.3.10 Class extension with %extend</a></H3> +<H3><a name="Octave_nn19">34.3.10 Class extension with %extend</a></H3> <p> @@ -660,7 +660,7 @@ Similarly, Octave can use the <tt>__float__</tt> method to convert an object to Octave 3.8.0 and later versions will also map unary functions X() to the corresponding <tt>__X__</tt> method, where X includes: abs(), acos(), acosh(), angle(), arg(), asin(), asinh(), atan(), atanh(), cbrt(), ceil(), conj(), cos(), cosh(), dawson(), erf(), erfc(), erfcinv(), erfcx(), erfi(), erfinv(), exp(), expm1(), finite(), fix(), floor(), gamma(), imag(), isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), isinf(), islower(), isna(), isnan(), isprint(), ispunct(), isspace(), isupper(), isxdigit(), lgamma(), log(), log10(), log1p(), log2(), real(), round(), roundb(), signbit(), signum(), sin(), sinh(), sqrt(), tan(), tanh(), toascii(), tolower(), toupper() </p> -<H3><a name="Octave_nn20">33.3.11 C++ templates</a></H3> +<H3><a name="Octave_nn20">34.3.11 C++ templates</a></H3> <p> @@ -737,10 +737,10 @@ ans = </pre></div> -<H3><a name="Octave_nn21">33.3.12 C++ Smart Pointers</a></H3> +<H3><a name="Octave_nn21">34.3.12 C++ Smart Pointers</a></H3> -<H4><a name="Octave_smart_pointers_shared_ptr">33.3.12.1 The shared_ptr Smart Pointer</a></H4> +<H4><a name="Octave_smart_pointers_shared_ptr">34.3.12.1 The shared_ptr Smart Pointer</a></H4> <p> @@ -751,14 +751,14 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a </p> -<H4><a name="Octave_smart_pointers_generic">33.3.12.2 Generic Smart Pointers</a></H4> +<H4><a name="Octave_smart_pointers_generic">34.3.12.2 Generic Smart Pointers</a></H4> <p> C++ smart pointers are fully supported as in other modules. </p> -<H3><a name="Octave_nn22">33.3.13 Directors (calling Octave from C++ code)</a></H3> +<H3><a name="Octave_nn22">34.3.13 Directors (calling Octave from C++ code)</a></H3> <p> @@ -839,14 +839,14 @@ c-side routine called octave-side routine called </pre></div> -<H3><a name="Octave_nn23">33.3.14 Threads</a></H3> +<H3><a name="Octave_nn23">34.3.14 Threads</a></H3> <p> The use of threads in wrapped Director code is not supported; i.e., an Octave-side implementation of a C++ class must be called from the Octave interpreter's thread. Anything fancier (apartment/queue model, whatever) is left to the user. Without anything fancier, this amounts to the limitation that Octave must drive the module... like, for example, an optimization package that calls Octave to evaluate an objective function. </p> -<H3><a name="Octave_nn24">33.3.15 Memory management</a></H3> +<H3><a name="Octave_nn24">34.3.15 Memory management</a></H3> <p> @@ -880,14 +880,14 @@ The %newobject directive may be used to control this behavior for pointers retur In the case where one wishes for the C++ side to own an object that was created in Octave (especially a Director object), one can use the __disown() method to invert this logic. Then letting the Octave reference count go to zero will not destroy the object, but destroying the object will invalidate the Octave-side object if it still exists (and call destructors of other C++ bases in the case of multiple inheritance/<tt>subclass()</tt>'ing). </p> -<H3><a name="Octave_nn25">33.3.16 STL support</a></H3> +<H3><a name="Octave_nn25">34.3.16 STL support</a></H3> <p> Various STL library files are provided for wrapping STL containers. </p> -<H3><a name="Octave_nn26">33.3.17 Matrix typemaps</a></H3> +<H3><a name="Octave_nn26">34.3.17 Matrix typemaps</a></H3> <p> diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html index 61a08a545..8bb65ec66 100644 --- a/Doc/Manual/Perl5.html +++ b/Doc/Manual/Perl5.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Perl5">34 SWIG and Perl5</a></H1> +<H1><a name="Perl5">35 SWIG and Perl5</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -97,7 +97,7 @@ later. We're no longer testing regularly with older versions, but Perl 5.6 seems to mostly work, while older versions don't. </p> -<H2><a name="Perl5_nn2">34.1 Overview</a></H2> +<H2><a name="Perl5_nn2">35.1 Overview</a></H2> <p> @@ -118,7 +118,7 @@ described. Advanced customization features, typemaps, and other options are found near the end of the chapter. </p> -<H2><a name="Perl5_nn3">34.2 Preliminaries</a></H2> +<H2><a name="Perl5_nn3">35.2 Preliminaries</a></H2> <p> @@ -143,7 +143,7 @@ To build the module, you will need to compile the file <tt>example_wrap.c</tt> and link it with the rest of your program. </p> -<H3><a name="Perl5_nn4">34.2.1 Getting the right header files</a></H3> +<H3><a name="Perl5_nn4">35.2.1 Getting the right header files</a></H3> <p> @@ -175,7 +175,7 @@ $ perl -e 'use Config; print "$Config{archlib}\n";' </pre> </div> -<H3><a name="Perl5_nn5">34.2.2 Compiling a dynamic module</a></H3> +<H3><a name="Perl5_nn5">35.2.2 Compiling a dynamic module</a></H3> <p> @@ -208,7 +208,7 @@ the target should be named `<tt>example.so</tt>', `<tt>example.sl</tt>', or the appropriate dynamic module name on your system. </p> -<H3><a name="Perl5_nn6">34.2.3 Building a dynamic module with MakeMaker</a></H3> +<H3><a name="Perl5_nn6">35.2.3 Building a dynamic module with MakeMaker</a></H3> <p> @@ -242,7 +242,7 @@ the preferred approach to compilation. More information about MakeMaker can be found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen, and Randal Schwartz.</p> -<H3><a name="Perl5_nn7">34.2.4 Building a static version of Perl</a></H3> +<H3><a name="Perl5_nn7">35.2.4 Building a static version of Perl</a></H3> <p> @@ -311,7 +311,7 @@ added to it. Depending on your machine, you may need to link with additional libraries such as <tt>-lsocket, -lnsl, -ldl</tt>, etc. </p> -<H3><a name="Perl5_nn8">34.2.5 Using the module</a></H3> +<H3><a name="Perl5_nn8">35.2.5 Using the module</a></H3> <p> @@ -464,7 +464,7 @@ system configuration (this requires root access and you will need to read the man pages). </p> -<H3><a name="Perl5_nn9">34.2.6 Compilation problems and compiling with C++</a></H3> +<H3><a name="Perl5_nn9">35.2.6 Compilation problems and compiling with C++</a></H3> <p> @@ -607,7 +607,7 @@ have to find the macro that conflicts and add an #undef into the .i file. Pleas any conflicting macros you find to <a href="http://www.swig.org/mail.html">swig-user mailing list</a>. </p> -<H3><a name="Perl5_nn10">34.2.7 Compiling for 64-bit platforms</a></H3> +<H3><a name="Perl5_nn10">35.2.7 Compiling for 64-bit platforms</a></H3> <p> @@ -634,7 +634,7 @@ also introduce problems on platforms that support more than one linking standard (e.g., -o32 and -n32 on Irix). </p> -<H2><a name="Perl5_nn11">34.3 Building Perl Extensions under Windows</a></H2> +<H2><a name="Perl5_nn11">35.3 Building Perl Extensions under Windows</a></H2> <p> @@ -645,7 +645,7 @@ section assumes you are using SWIG with Microsoft Visual C++ although the procedure may be similar with other compilers. </p> -<H3><a name="Perl5_nn12">34.3.1 Running SWIG from Developer Studio</a></H3> +<H3><a name="Perl5_nn12">35.3.1 Running SWIG from Developer Studio</a></H3> <p> @@ -708,7 +708,7 @@ print "$a\n"; </pre></div> -<H3><a name="Perl5_nn13">34.3.2 Using other compilers</a></H3> +<H3><a name="Perl5_nn13">35.3.2 Using other compilers</a></H3> <p> @@ -716,7 +716,7 @@ SWIG is known to work with Cygwin and may work with other compilers on Windows. For general hints and suggestions refer to the <a href="Windows.html#Windows">Windows</a> chapter. </p> -<H2><a name="Perl5_nn14">34.4 The low-level interface</a></H2> +<H2><a name="Perl5_nn14">35.4 The low-level interface</a></H2> <p> @@ -726,7 +726,7 @@ can be used to control your application. However, it is also used to construct more user-friendly proxy classes as described in the next section. </p> -<H3><a name="Perl5_nn15">34.4.1 Functions</a></H3> +<H3><a name="Perl5_nn15">35.4.1 Functions</a></H3> <p> @@ -749,7 +749,7 @@ use example; $a = &example::fact(2); </pre></div> -<H3><a name="Perl5_nn16">34.4.2 Global variables</a></H3> +<H3><a name="Perl5_nn16">35.4.2 Global variables</a></H3> <p> @@ -819,7 +819,7 @@ extern char *path; // Declared later in the input </pre> </div> -<H3><a name="Perl5_nn17">34.4.3 Constants</a></H3> +<H3><a name="Perl5_nn17">35.4.3 Constants</a></H3> <p> @@ -859,7 +859,7 @@ print example::FOO, "\n"; </pre> </div> -<H3><a name="Perl5_nn18">34.4.4 Pointers</a></H3> +<H3><a name="Perl5_nn18">35.4.4 Pointers</a></H3> <p> @@ -968,7 +968,7 @@ as XS and <tt>xsubpp</tt>. Given the advancement of the SWIG typesystem and the SWIG and XS, this is no longer supported. </p> -<H3><a name="Perl5_nn19">34.4.5 Structures</a></H3> +<H3><a name="Perl5_nn19">35.4.5 Structures</a></H3> <p> @@ -1102,7 +1102,7 @@ void Bar_f_set(Bar *b, Foo *val) { </div> -<H3><a name="Perl5_nn20">34.4.6 C++ classes</a></H3> +<H3><a name="Perl5_nn20">35.4.6 C++ classes</a></H3> <p> @@ -1167,7 +1167,7 @@ provides direct access to C++ objects. A higher level interface using Perl prox can be built using these low-level accessors. This is described shortly. </p> -<H3><a name="Perl5_nn21">34.4.7 C++ classes and type-checking</a></H3> +<H3><a name="Perl5_nn21">35.4.7 C++ classes and type-checking</a></H3> <p> @@ -1203,7 +1203,7 @@ If necessary, the type-checker also adjusts the value of the pointer (as is nece multiple inheritance is used). </p> -<H3><a name="Perl5_nn22">34.4.8 C++ overloaded functions</a></H3> +<H3><a name="Perl5_nn22">35.4.8 C++ overloaded functions</a></H3> <p> @@ -1247,7 +1247,7 @@ example::Spam_foo_d($s, 3.14); Please refer to the "SWIG Basics" chapter for more information. </p> -<H3><a name="Perl5_nn23">34.4.9 Operators</a></H3> +<H3><a name="Perl5_nn23">35.4.9 Operators</a></H3> <p> @@ -1274,7 +1274,7 @@ The following C++ operators are currently supported by the Perl module: <li>operator or </li> </ul> -<H3><a name="Perl5_nn24">34.4.10 Modules and packages</a></H3> +<H3><a name="Perl5_nn24">35.4.10 Modules and packages</a></H3> <p> @@ -1369,7 +1369,7 @@ print Foo::fact(4), "\n"; # Call a function in package FooBar </pre></div> --> -<H2><a name="Perl5_nn25">34.5 Input and output parameters</a></H2> +<H2><a name="Perl5_nn25">35.5 Input and output parameters</a></H2> <p> @@ -1588,7 +1588,7 @@ print "$c\n"; <b>Note:</b> The <tt>REFERENCE</tt> feature is only currently supported for numeric types (integers and floating point). </p> -<H2><a name="Perl5_nn26">34.6 Exception handling</a></H2> +<H2><a name="Perl5_nn26">35.6 Exception handling</a></H2> <p> @@ -1752,7 +1752,7 @@ This is still supported, but it is deprecated. The newer <tt>%exception</tt> di functionality, but it has additional capabilities that make it more powerful. </p> -<H2><a name="Perl5_nn27">34.7 Remapping datatypes with typemaps</a></H2> +<H2><a name="Perl5_nn27">35.7 Remapping datatypes with typemaps</a></H2> <p> @@ -1769,7 +1769,7 @@ Typemaps are only used if you want to change some aspect of the primitive C-Perl interface. </p> -<H3><a name="Perl5_nn28">34.7.1 A simple typemap example</a></H3> +<H3><a name="Perl5_nn28">35.7.1 A simple typemap example</a></H3> <p> @@ -1873,7 +1873,7 @@ example::count("e", "Hello World"); </div> -<H3><a name="Perl5_nn29">34.7.2 Perl5 typemaps</a></H3> +<H3><a name="Perl5_nn29">35.7.2 Perl5 typemaps</a></H3> <p> @@ -1978,7 +1978,7 @@ Return of C++ member data (all languages). Check value of input parameter. </div> -<H3><a name="Perl5_nn30">34.7.3 Typemap variables</a></H3> +<H3><a name="Perl5_nn30">35.7.3 Typemap variables</a></H3> <p> @@ -2049,7 +2049,7 @@ properly assigned. The Perl name of the wrapper function being created. </div> -<H3><a name="Perl5_nn31">34.7.4 Useful functions</a></H3> +<H3><a name="Perl5_nn31">35.7.4 Useful functions</a></H3> <p> @@ -2118,7 +2118,7 @@ int sv_isa(SV *, char *0; </div> -<H2><a name="Perl5_nn32">34.8 Typemap Examples</a></H2> +<H2><a name="Perl5_nn32">35.8 Typemap Examples</a></H2> <p> @@ -2127,7 +2127,7 @@ might look at the files "<tt>perl5.swg</tt>" and "<tt>typemaps.i</tt>" in the SWIG library. </p> -<H3><a name="Perl5_nn33">34.8.1 Converting a Perl5 array to a char **</a></H3> +<H3><a name="Perl5_nn33">35.8.1 Converting a Perl5 array to a char **</a></H3> <p> @@ -2219,7 +2219,7 @@ print @$b, "\n"; # Print it out </pre></div> -<H3><a name="Perl5_nn34">34.8.2 Return values</a></H3> +<H3><a name="Perl5_nn34">35.8.2 Return values</a></H3> <p> @@ -2248,7 +2248,7 @@ can be done using the <tt>EXTEND()</tt> macro as in: } </pre></div> -<H3><a name="Perl5_nn35">34.8.3 Returning values from arguments</a></H3> +<H3><a name="Perl5_nn35">35.8.3 Returning values from arguments</a></H3> <p> @@ -2302,7 +2302,7 @@ print "multout(7, 13) = @r\n"; ($x, $y) = multout(7, 13); </pre></div> -<H3><a name="Perl5_nn36">34.8.4 Accessing array structure members</a></H3> +<H3><a name="Perl5_nn36">35.8.4 Accessing array structure members</a></H3> <p> @@ -2365,7 +2365,7 @@ the "in" typemap in the previous section would be used to convert an to copy the converted array into a C data structure. </p> -<H3><a name="Perl5_nn37">34.8.5 Turning Perl references into C pointers</a></H3> +<H3><a name="Perl5_nn37">35.8.5 Turning Perl references into C pointers</a></H3> <p> @@ -2430,7 +2430,7 @@ print "$c\n"; </pre></div> -<H3><a name="Perl5_nn38">34.8.6 Pointer handling</a></H3> +<H3><a name="Perl5_nn38">35.8.6 Pointer handling</a></H3> <p> @@ -2515,7 +2515,7 @@ For example: </pre> </div> -<H2><a name="Perl5_nn39">34.9 Proxy classes</a></H2> +<H2><a name="Perl5_nn39">35.9 Proxy classes</a></H2> <p> @@ -2531,7 +2531,7 @@ to the underlying code. This section describes the implementation details of the proxy interface. </p> -<H3><a name="Perl5_nn40">34.9.1 Preliminaries</a></H3> +<H3><a name="Perl5_nn40">35.9.1 Preliminaries</a></H3> <p> @@ -2553,7 +2553,7 @@ SWIG creates a collection of high-level Perl wrappers. In your scripts, you wil high level wrappers. The wrappers, in turn, interact with the low-level procedural module. </p> -<H3><a name="Perl5_nn41">34.9.2 Structure and class wrappers</a></H3> +<H3><a name="Perl5_nn41">35.9.2 Structure and class wrappers</a></H3> <p> @@ -2680,7 +2680,7 @@ $v->DESTROY(); </pre></div> -<H3><a name="Perl5_nn42">34.9.3 Object Ownership</a></H3> +<H3><a name="Perl5_nn42">35.9.3 Object Ownership</a></H3> <p> @@ -2767,7 +2767,7 @@ counting, garbage collection, or advanced features one might find in sophisticated languages. </p> -<H3><a name="Perl5_nn43">34.9.4 Nested Objects</a></H3> +<H3><a name="Perl5_nn43">35.9.4 Nested Objects</a></H3> <p> @@ -2820,7 +2820,7 @@ $p->{f}->{x} = 0.0; %${$p->{v}} = ( x=>0, y=>0, z=>0); </pre></div> -<H3><a name="Perl5_nn44">34.9.5 Proxy Functions</a></H3> +<H3><a name="Perl5_nn44">35.9.5 Proxy Functions</a></H3> <p> @@ -2854,7 +2854,7 @@ This function replaces the original function, but operates in an identical manner. </p> -<H3><a name="Perl5_nn45">34.9.6 Inheritance</a></H3> +<H3><a name="Perl5_nn45">35.9.6 Inheritance</a></H3> <p> @@ -2930,7 +2930,7 @@ particular, inheritance of data members is extremely tricky (and I'm not even sure if it really works). </p> -<H3><a name="Perl5_nn46">34.9.7 Modifying the proxy methods</a></H3> +<H3><a name="Perl5_nn46">35.9.7 Modifying the proxy methods</a></H3> <p> @@ -2958,7 +2958,7 @@ public: }; </pre></div> -<H2><a name="Perl5_nn47">34.10 Adding additional Perl code</a></H2> +<H2><a name="Perl5_nn47">35.10 Adding additional Perl code</a></H2> <p> @@ -3009,7 +3009,7 @@ set_transform($im, $a); </pre> </div> -<H2><a name="Perl5_directors">34.11 Cross language polymorphism</a></H2> +<H2><a name="Perl5_directors">35.11 Cross language polymorphism</a></H2> <p> @@ -3043,7 +3043,7 @@ proxy classes, director classes, and C wrapper functions takes care of all the cross-language method routing transparently. </p> -<H3><a name="Perl5_nn48">34.11.1 Enabling directors</a></H3> +<H3><a name="Perl5_nn48">35.11.1 Enabling directors</a></H3> <p> @@ -3133,7 +3133,7 @@ sub one { </div> -<H3><a name="Perl5_nn49">34.11.2 Director classes</a></H3> +<H3><a name="Perl5_nn49">35.11.2 Director classes</a></H3> @@ -3213,7 +3213,7 @@ so there is no need for the extra overhead involved with routing the calls through Perl. </p> -<H3><a name="Perl5_nn50">34.11.3 Ownership and object destruction</a></H3> +<H3><a name="Perl5_nn50">35.11.3 Ownership and object destruction</a></H3> <p> @@ -3262,7 +3262,7 @@ sub DESTROY { </div> -<H3><a name="Perl5_nn51">34.11.4 Exception unrolling</a></H3> +<H3><a name="Perl5_nn51">35.11.4 Exception unrolling</a></H3> <p> @@ -3318,7 +3318,7 @@ Swig::DirectorMethodException is thrown, Perl will register the exception as soon as the C wrapper function returns. </p> -<H3><a name="Perl5_nn52">34.11.5 Overhead and code bloat</a></H3> +<H3><a name="Perl5_nn52">35.11.5 Overhead and code bloat</a></H3> <p> @@ -3352,7 +3352,7 @@ directive) for only those methods that are likely to be extended in Perl. </p> -<H3><a name="Perl5_nn53">34.11.6 Typemaps</a></H3> +<H3><a name="Perl5_nn53">35.11.6 Typemaps</a></H3> <p> diff --git a/Doc/Manual/Php.html b/Doc/Manual/Php.html index d72bc058e..f224f19fb 100644 --- a/Doc/Manual/Php.html +++ b/Doc/Manual/Php.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Php">35 SWIG and PHP</a></H1> +<H1><a name="Php">36 SWIG and PHP</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -70,7 +70,7 @@ your extension into php directly, you will need the complete PHP source tree available. </p> -<H2><a name="Php_nn1">35.1 Generating PHP Extensions</a></H2> +<H2><a name="Php_nn1">36.1 Generating PHP Extensions</a></H2> <p> @@ -119,7 +119,7 @@ and it doesn't play nicely with package system. We don't recommend this approach, or provide explicit support for it. </p> -<H3><a name="Php_nn1_1">35.1.1 Building a loadable extension</a></H3> +<H3><a name="Php_nn1_1">36.1.1 Building a loadable extension</a></H3> <p> @@ -134,7 +134,7 @@ least work for Linux though): gcc -shared example_wrap.o example.o -o example.so </pre></div> -<H3><a name="Php_nn1_3">35.1.2 Using PHP Extensions</a></H3> +<H3><a name="Php_nn1_3">36.1.2 Using PHP Extensions</a></H3> <p> @@ -182,7 +182,7 @@ This PHP module also defines the PHP classes for the wrapped API, so you'll almost certainly want to include it anyway. </p> -<H2><a name="Php_nn2">35.2 Basic PHP interface</a></H2> +<H2><a name="Php_nn2">36.2 Basic PHP interface</a></H2> <p> @@ -194,7 +194,7 @@ SWIG doesn't have support for generating wrappers which make use of PHP's namespace feature. </p> -<H3><a name="Php_nn2_1">35.2.1 Constants</a></H3> +<H3><a name="Php_nn2_1">36.2.1 Constants</a></H3> <p> @@ -272,7 +272,7 @@ would be treated as false! Modern versions of PHP will at least issue a PHP notice by default when this happens. </p> -<H3><a name="Php_nn2_2">35.2.2 Global Variables</a></H3> +<H3><a name="Php_nn2_2">36.2.2 Global Variables</a></H3> <p> @@ -321,7 +321,7 @@ undefined. At this time SWIG does not support custom accessor methods. </p> -<H3><a name="Php_nn2_3">35.2.3 Functions</a></H3> +<H3><a name="Php_nn2_3">36.2.3 Functions</a></H3> <p> @@ -374,7 +374,7 @@ print $s; # The value of $s was not changed. --> -<H3><a name="Php_nn2_4">35.2.4 Overloading</a></H3> +<H3><a name="Php_nn2_4">36.2.4 Overloading</a></H3> <p> @@ -429,7 +429,7 @@ taking the integer argument. </p> --> -<H3><a name="Php_nn2_5">35.2.5 Pointers and References</a></H3> +<H3><a name="Php_nn2_5">36.2.5 Pointers and References</a></H3> <p> @@ -567,7 +567,7 @@ PHP in a number of ways: by using <tt>unset</tt> on an existing variable, or assigning <tt>NULL</tt> to a variable. </p> -<H3><a name="Php_nn2_6">35.2.6 Structures and C++ classes</a></H3> +<H3><a name="Php_nn2_6">36.2.6 Structures and C++ classes</a></H3> <p> @@ -628,7 +628,7 @@ Would be used in the following way from PHP: Member variables and methods are accessed using the <tt>-></tt> operator. </p> -<H4><a name="Php_nn2_6_1">35.2.6.1 Using -noproxy</a></H4> +<H4><a name="Php_nn2_6_1">36.2.6.1 Using -noproxy</a></H4> <p> @@ -654,7 +654,7 @@ Complex_im_set($obj, $d); Complex_im_get($obj); </pre></div> -<H4><a name="Php_nn2_6_2">35.2.6.2 Constructors and Destructors</a></H4> +<H4><a name="Php_nn2_6_2">36.2.6.2 Constructors and Destructors</a></H4> <p> @@ -695,7 +695,7 @@ the programmer can either reassign the variable or call <tt>unset($v)</tt> </p> -<H4><a name="Php_nn2_6_3">35.2.6.3 Static Member Variables</a></H4> +<H4><a name="Php_nn2_6_3">36.2.6.3 Static Member Variables</a></H4> <p> @@ -738,7 +738,7 @@ Ko::threats(10); echo "There have now been " . Ko::threats() . " threats\n"; </pre></div> -<H4><a name="Php_nn2_6_4">35.2.6.4 Static Member Functions</a></H4> +<H4><a name="Php_nn2_6_4">36.2.6.4 Static Member Functions</a></H4> <p> @@ -760,7 +760,7 @@ Ko::threats(); </pre></div> -<H4><a name="Php_nn2_6_5">35.2.6.5 Specifying Implemented Interfaces</a></H4> +<H4><a name="Php_nn2_6_5">36.2.6.5 Specifying Implemented Interfaces</a></H4> <p> @@ -778,7 +778,7 @@ so: If there are multiple interfaces, just list them separated by commas. </p> -<H3><a name="Php_nn2_7">35.2.7 PHP Pragmas, Startup and Shutdown code</a></H3> +<H3><a name="Php_nn2_7">36.2.7 PHP Pragmas, Startup and Shutdown code</a></H3> <p> @@ -875,7 +875,7 @@ The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements are very similar but inse into the request init (PHP_RINIT_FUNCTION) and request shutdown (PHP_RSHUTDOWN_FUNCTION) code respectively. </p> -<H2><a name="Php_nn3">35.3 Cross language polymorphism</a></H2> +<H2><a name="Php_nn3">36.3 Cross language polymorphism</a></H2> <p> @@ -910,7 +910,7 @@ wrapper functions takes care of all the cross-language method routing transparently. </p> -<H3><a name="Php_nn3_1">35.3.1 Enabling directors</a></H3> +<H3><a name="Php_nn3_1">36.3.1 Enabling directors</a></H3> <p> @@ -999,7 +999,7 @@ class MyFoo extends Foo { </div> -<H3><a name="Php_nn3_2">35.3.2 Director classes</a></H3> +<H3><a name="Php_nn3_2">36.3.2 Director classes</a></H3> @@ -1079,7 +1079,7 @@ so there is no need for the extra overhead involved with routing the calls through PHP. </p> -<H3><a name="Php_nn3_3">35.3.3 Ownership and object destruction</a></H3> +<H3><a name="Php_nn3_3">36.3.3 Ownership and object destruction</a></H3> <p> @@ -1135,7 +1135,7 @@ In this example, we are assuming that FooContainer will take care of deleting all the Foo pointers it contains at some point. </p> -<H3><a name="Php_nn3_4">35.3.4 Exception unrolling</a></H3> +<H3><a name="Php_nn3_4">36.3.4 Exception unrolling</a></H3> <p> @@ -1202,7 +1202,7 @@ Swig::DirectorMethodException is thrown, PHP will register the exception as soon as the C wrapper function returns. </p> -<H3><a name="Php_nn3_5">35.3.5 Overhead and code bloat</a></H3> +<H3><a name="Php_nn3_5">36.3.5 Overhead and code bloat</a></H3> <p> @@ -1235,7 +1235,7 @@ optimized by selectively enabling director methods (using the %feature directive) for only those methods that are likely to be extended in PHP. </p> -<H3><a name="Php_nn3_6">35.3.6 Typemaps</a></H3> +<H3><a name="Php_nn3_6">36.3.6 Typemaps</a></H3> <p> @@ -1249,7 +1249,7 @@ need to be supported. </p> -<H3><a name="Php_nn3_7">35.3.7 Miscellaneous</a></H3> +<H3><a name="Php_nn3_7">36.3.7 Miscellaneous</a></H3> <p> Director typemaps for STL classes are mostly in place, and hence you diff --git a/Doc/Manual/Pike.html b/Doc/Manual/Pike.html index 59af01227..2b8432399 100644 --- a/Doc/Manual/Pike.html +++ b/Doc/Manual/Pike.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Pike">36 SWIG and Pike</a></H1> +<H1><a name="Pike">37 SWIG and Pike</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -47,10 +47,10 @@ least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter.<br> </p> -<H2><a name="Pike_nn2">36.1 Preliminaries</a></H2> +<H2><a name="Pike_nn2">37.1 Preliminaries</a></H2> -<H3><a name="Pike_nn3">36.1.1 Running SWIG</a></H3> +<H3><a name="Pike_nn3">37.1.1 Running SWIG</a></H3> <p> @@ -95,7 +95,7 @@ can use the <tt>-o</tt> option: <div class="code"> <pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre> </div> -<H3><a name="Pike_nn4">36.1.2 Getting the right header files</a></H3> +<H3><a name="Pike_nn4">37.1.2 Getting the right header files</a></H3> <p> @@ -115,7 +115,7 @@ You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt> and so on. </p> -<H3><a name="Pike_nn5">36.1.3 Using your module</a></H3> +<H3><a name="Pike_nn5">37.1.3 Using your module</a></H3> <p> @@ -130,10 +130,10 @@ Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend) (1) Result: 24 </pre></div> -<H2><a name="Pike_nn6">36.2 Basic C/C++ Mapping</a></H2> +<H2><a name="Pike_nn6">37.2 Basic C/C++ Mapping</a></H2> -<H3><a name="Pike_nn7">36.2.1 Modules</a></H3> +<H3><a name="Pike_nn7">37.2.1 Modules</a></H3> <p> @@ -144,7 +144,7 @@ concerned), SWIG's <tt>%module</tt> directive doesn't really have any significance. </p> -<H3><a name="Pike_nn8">36.2.2 Functions</a></H3> +<H3><a name="Pike_nn8">37.2.2 Functions</a></H3> <p> @@ -169,7 +169,7 @@ exactly as you'd expect it to: (1) Result: 24 </pre></div> -<H3><a name="Pike_nn9">36.2.3 Global variables</a></H3> +<H3><a name="Pike_nn9">37.2.3 Global variables</a></H3> <p> @@ -198,7 +198,7 @@ will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>: (3) Result: 3.141590 </pre></div> -<H3><a name="Pike_nn10">36.2.4 Constants and enumerated types</a></H3> +<H3><a name="Pike_nn10">37.2.4 Constants and enumerated types</a></H3> <p> @@ -206,7 +206,7 @@ Enumerated types in C/C++ declarations are wrapped as Pike constants, not as Pike enums. </p> -<H3><a name="Pike_nn11">36.2.5 Constructors and Destructors</a></H3> +<H3><a name="Pike_nn11">37.2.5 Constructors and Destructors</a></H3> <p> @@ -214,7 +214,7 @@ Constructors are wrapped as <tt>create()</tt> methods, and destructors are wrapped as <tt>destroy()</tt> methods, for Pike classes. </p> -<H3><a name="Pike_nn12">36.2.6 Static Members</a></H3> +<H3><a name="Pike_nn12">37.2.6 Static Members</a></H3> <p> diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html index 99d48588d..77ac538b0 100644 --- a/Doc/Manual/Python.html +++ b/Doc/Manual/Python.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Python">37 SWIG and Python</a></H1> +<H1><a name="Python">38 SWIG and Python</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -162,7 +162,7 @@ very least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter. </p> -<H2><a name="Python_nn2">37.1 Overview</a></H2> +<H2><a name="Python_nn2">38.1 Overview</a></H2> <p> @@ -189,10 +189,10 @@ described followed by a discussion of low-level implementation details. </p> -<H2><a name="Python_nn3">37.2 Preliminaries</a></H2> +<H2><a name="Python_nn3">38.2 Preliminaries</a></H2> -<H3><a name="Python_nn4">37.2.1 Running SWIG</a></H3> +<H3><a name="Python_nn4">38.2.1 Running SWIG</a></H3> <p> @@ -289,7 +289,7 @@ The following sections have further practical examples and details on how you might go about compiling and using the generated files. </p> -<H3><a name="Python_nn6">37.2.2 Using distutils</a></H3> +<H3><a name="Python_nn6">38.2.2 Using distutils</a></H3> <p> @@ -381,7 +381,7 @@ This same approach works on all platforms if the appropriate compiler is install can even build extensions to the standard Windows Python using MingGW) </p> -<H3><a name="Python_nn7">37.2.3 Hand compiling a dynamic module</a></H3> +<H3><a name="Python_nn7">38.2.3 Hand compiling a dynamic module</a></H3> <p> @@ -429,7 +429,7 @@ module actually consists of two files; <tt>socket.py</tt> and </p> -<H3><a name="Python_nn8">37.2.4 Static linking</a></H3> +<H3><a name="Python_nn8">38.2.4 Static linking</a></H3> <p> @@ -508,7 +508,7 @@ If using static linking, you might want to rely on a different approach (perhaps using distutils). </p> -<H3><a name="Python_nn9">37.2.5 Using your module</a></H3> +<H3><a name="Python_nn9">38.2.5 Using your module</a></H3> <p> @@ -665,7 +665,7 @@ system configuration (this requires root access and you will need to read the man pages). </p> -<H3><a name="Python_nn10">37.2.6 Compilation of C++ extensions</a></H3> +<H3><a name="Python_nn10">38.2.6 Compilation of C++ extensions</a></H3> <p> @@ -757,7 +757,7 @@ erratic program behavior. If working with lots of software components, you might want to investigate using a more formal standard such as COM. </p> -<H3><a name="Python_nn11">37.2.7 Compiling for 64-bit platforms</a></H3> +<H3><a name="Python_nn11">38.2.7 Compiling for 64-bit platforms</a></H3> <p> @@ -794,7 +794,7 @@ and -m64 allow you to choose the desired binary format for your python extension. </p> -<H3><a name="Python_nn12">37.2.8 Building Python Extensions under Windows</a></H3> +<H3><a name="Python_nn12">38.2.8 Building Python Extensions under Windows</a></H3> <p> @@ -923,7 +923,7 @@ SWIG Wiki</a>. </p> -<H2><a name="Python_nn13">37.3 A tour of basic C/C++ wrapping</a></H2> +<H2><a name="Python_nn13">38.3 A tour of basic C/C++ wrapping</a></H2> <p> @@ -932,7 +932,7 @@ to your C/C++ code. Functions are wrapped as functions, classes are wrapped as This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Python_nn14">37.3.1 Modules</a></H3> +<H3><a name="Python_nn14">38.3.1 Modules</a></H3> <p> @@ -945,7 +945,7 @@ module name, make sure you don't use the same name as a built-in Python command or standard module name. </p> -<H3><a name="Python_nn15">37.3.2 Functions</a></H3> +<H3><a name="Python_nn15">38.3.2 Functions</a></H3> <p> @@ -969,7 +969,7 @@ like you think it does: >>> </pre></div> -<H3><a name="Python_nn16">37.3.3 Global variables</a></H3> +<H3><a name="Python_nn16">38.3.3 Global variables</a></H3> <p> @@ -1107,7 +1107,7 @@ that starts with a leading underscore. SWIG does not create <tt>cvar</tt> if there are no global variables in a module. </p> -<H3><a name="Python_nn17">37.3.4 Constants and enums</a></H3> +<H3><a name="Python_nn17">38.3.4 Constants and enums</a></H3> <p> @@ -1147,7 +1147,7 @@ other object. Unfortunately, there is no easy way for SWIG to generate code that prevents this. You will just have to be careful. </p> -<H3><a name="Python_nn18">37.3.5 Pointers</a></H3> +<H3><a name="Python_nn18">38.3.5 Pointers</a></H3> <p> @@ -1288,7 +1288,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return <tt>None</tt> if the conversion can't be performed. </p> -<H3><a name="Python_nn19">37.3.6 Structures</a></H3> +<H3><a name="Python_nn19">38.3.6 Structures</a></H3> <p> @@ -1477,7 +1477,7 @@ everything works just like you would expect. For example: </pre> </div> -<H3><a name="Python_nn20">37.3.7 C++ classes</a></H3> +<H3><a name="Python_nn20">38.3.7 C++ classes</a></H3> <p> @@ -1565,7 +1565,7 @@ they are accessed through <tt>cvar</tt> like this: </pre> </div> -<H3><a name="Python_nn21">37.3.8 C++ inheritance</a></H3> +<H3><a name="Python_nn21">38.3.8 C++ inheritance</a></H3> <p> @@ -1620,7 +1620,7 @@ then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any cla It is safe to use multiple inheritance with SWIG. </p> -<H3><a name="Python_nn22">37.3.9 Pointers, references, values, and arrays</a></H3> +<H3><a name="Python_nn22">38.3.9 Pointers, references, values, and arrays</a></H3> <p> @@ -1681,7 +1681,7 @@ treated as a returning value, and it will follow the same allocation/deallocation process. </p> -<H3><a name="Python_nn23">37.3.10 C++ overloaded functions</a></H3> +<H3><a name="Python_nn23">38.3.10 C++ overloaded functions</a></H3> <p> @@ -1804,7 +1804,7 @@ first declaration takes precedence. Please refer to the "SWIG and C++" chapter for more information about overloading. </p> -<H3><a name="Python_nn24">37.3.11 C++ operators</a></H3> +<H3><a name="Python_nn24">38.3.11 C++ operators</a></H3> <p> @@ -1901,7 +1901,7 @@ instead of raising an exception when the comparison fails, that is, on any kind This follows the guidelines in <a href="https://www.python.org/dev/peps/pep-0207/">PEP 207 - Rich Comparisons</a> and <a href="https://docs.python.org/3/library/constants.html#NotImplemented">NotImplemented Python constant</a>. </p> -<H3><a name="Python_nn25">37.3.12 C++ namespaces</a></H3> +<H3><a name="Python_nn25">38.3.12 C++ namespaces</a></H3> <p> @@ -1968,7 +1968,7 @@ utilizes thousands of small deeply nested namespaces each with identical symbol names, well, then you get what you deserve. </p> -<H3><a name="Python_nn26">37.3.13 C++ templates</a></H3> +<H3><a name="Python_nn26">38.3.13 C++ templates</a></H3> <p> @@ -2022,10 +2022,10 @@ Some more complicated examples will appear later. </p> -<H3><a name="Python_nn27">37.3.14 C++ Smart Pointers</a></H3> +<H3><a name="Python_nn27">38.3.14 C++ Smart Pointers</a></H3> -<H4><a name="Python_smart_pointers_shared_ptr">37.3.14.1 The shared_ptr Smart Pointer</a></H4> +<H4><a name="Python_smart_pointers_shared_ptr">38.3.14.1 The shared_ptr Smart Pointer</a></H4> <p> @@ -2036,7 +2036,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a </p> -<H4><a name="Python_smart_pointers_generic">37.3.14.2 Generic Smart Pointers</a></H4> +<H4><a name="Python_smart_pointers_generic">38.3.14.2 Generic Smart Pointers</a></H4> <p> @@ -2120,7 +2120,7 @@ simply use the <tt>__deref__()</tt> method. For example: </pre> </div> -<H3><a name="Python_nn27a">37.3.15 C++ reference counted objects</a></H3> +<H3><a name="Python_nn27a">38.3.15 C++ reference counted objects</a></H3> <p> @@ -2129,7 +2129,7 @@ Python examples of memory management using referencing counting. </p> -<H2><a name="Python_nn28">37.4 Further details on the Python class interface</a></H2> +<H2><a name="Python_nn28">38.4 Further details on the Python class interface</a></H2> <p> @@ -2152,7 +2152,7 @@ the <tt>-builtin</tt> option are in the <a href="#Python_builtin_types">Built-in section. </p> -<H3><a name="Python_nn29">37.4.1 Proxy classes</a></H3> +<H3><a name="Python_nn29">38.4.1 Proxy classes</a></H3> <p> @@ -2241,7 +2241,7 @@ you can attach new Python methods to the class and you can even inherit from it by Python built-in types until Python 2.2). </p> -<H3><a name="Python_builtin_types">37.4.2 Built-in Types</a></H3> +<H3><a name="Python_builtin_types">38.4.2 Built-in Types</a></H3> <p> @@ -2285,7 +2285,7 @@ please refer to the python documentation:</p> <p><a href="http://docs.python.org/extending/newtypes.html">http://docs.python.org/extending/newtypes.html</a></p> -<H4><a name="Python_builtin_limitations">37.4.2.1 Limitations</a></H4> +<H4><a name="Python_builtin_limitations">38.4.2.1 Limitations</a></H4> <p>Use of the <tt>-builtin</tt> option implies a couple of limitations: @@ -2453,7 +2453,7 @@ assert(issubclass(B.Derived, A.Base)) </li> </ul> -<H4><a name="Python_builtin_overloads">37.4.2.2 Operator overloads and slots -- use them!</a></H4> +<H4><a name="Python_builtin_overloads">38.4.2.2 Operator overloads and slots -- use them!</a></H4> <p>The entire justification for the <tt>-builtin</tt> option is improved @@ -2613,7 +2613,7 @@ in the file <tt>python/pyopers.swig</tt> in the SWIG library. </p> -<H3><a name="Python_nn30">37.4.3 Memory management</a></H3> +<H3><a name="Python_nn30">38.4.3 Memory management</a></H3> <p>NOTE: Although this section refers to proxy objects, everything here also applies @@ -2808,7 +2808,7 @@ It is also possible to deal with situations like this using typemaps--an advanced topic discussed later. </p> -<H3><a name="Python_nn31">37.4.4 Python 2.2 and classic classes</a></H3> +<H3><a name="Python_nn31">38.4.4 Python 2.2 and classic classes</a></H3> <p> @@ -2845,7 +2845,7 @@ class itself. In Python-2.1 and earlier, they have to be accessed as a global function or through an instance (see the earlier section). </p> -<H2><a name="Python_directors">37.5 Cross language polymorphism</a></H2> +<H2><a name="Python_directors">38.5 Cross language polymorphism</a></H2> <p> @@ -2879,7 +2879,7 @@ proxy classes, director classes, and C wrapper functions takes care of all the cross-language method routing transparently. </p> -<H3><a name="Python_nn33">37.5.1 Enabling directors</a></H3> +<H3><a name="Python_nn33">38.5.1 Enabling directors</a></H3> <p> @@ -2971,7 +2971,7 @@ class MyFoo(mymodule.Foo): </div> -<H3><a name="Python_nn34">37.5.2 Director classes</a></H3> +<H3><a name="Python_nn34">38.5.2 Director classes</a></H3> <p> @@ -3050,7 +3050,7 @@ so there is no need for the extra overhead involved with routing the calls through Python. </p> -<H3><a name="Python_nn35">37.5.3 Ownership and object destruction</a></H3> +<H3><a name="Python_nn35">38.5.3 Ownership and object destruction</a></H3> <p> @@ -3117,7 +3117,7 @@ deleting all the Foo pointers it contains at some point. Note that no hard references to the Foo objects remain in Python. </p> -<H3><a name="Python_nn36">37.5.4 Exception unrolling</a></H3> +<H3><a name="Python_nn36">38.5.4 Exception unrolling</a></H3> <p> @@ -3176,7 +3176,7 @@ Swig::DirectorMethodException is thrown, Python will register the exception as soon as the C wrapper function returns. </p> -<H3><a name="Python_nn37">37.5.5 Overhead and code bloat</a></H3> +<H3><a name="Python_nn37">38.5.5 Overhead and code bloat</a></H3> <p> @@ -3210,7 +3210,7 @@ directive) for only those methods that are likely to be extended in Python. </p> -<H3><a name="Python_nn38">37.5.6 Typemaps</a></H3> +<H3><a name="Python_nn38">38.5.6 Typemaps</a></H3> <p> @@ -3224,7 +3224,7 @@ need to be supported. </p> -<H3><a name="Python_nn39">37.5.7 Miscellaneous</a></H3> +<H3><a name="Python_nn39">38.5.7 Miscellaneous</a></H3> <p> @@ -3271,7 +3271,7 @@ methods that return const references. </p> -<H2><a name="Python_nn40">37.6 Common customization features</a></H2> +<H2><a name="Python_nn40">38.6 Common customization features</a></H2> <p> @@ -3284,7 +3284,7 @@ This section describes some common SWIG features that are used to improve your the interface to an extension module. </p> -<H3><a name="Python_nn41">37.6.1 C/C++ helper functions</a></H3> +<H3><a name="Python_nn41">38.6.1 C/C++ helper functions</a></H3> <p> @@ -3365,7 +3365,7 @@ hard to implement. It is possible to clean this up using Python code, typemaps, customization features as covered in later sections. </p> -<H3><a name="Python_nn42">37.6.2 Adding additional Python code</a></H3> +<H3><a name="Python_nn42">38.6.2 Adding additional Python code</a></H3> <p> @@ -3617,7 +3617,7 @@ The same applies for overloaded constructors. </p> -<H3><a name="Python_nn43">37.6.3 Class extension with %extend</a></H3> +<H3><a name="Python_nn43">38.6.3 Class extension with %extend</a></H3> <p> @@ -3706,7 +3706,7 @@ Vector(12, 14, 16) in any way---the extensions only show up in the Python interface. </p> -<H3><a name="Python_nn44">37.6.4 Exception handling with %exception</a></H3> +<H3><a name="Python_nn44">38.6.4 Exception handling with %exception</a></H3> <p> @@ -3840,7 +3840,7 @@ The language-independent <tt>exception.i</tt> library file can also be used to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> chapter. </p> -<H2><a name="Python_nn45">37.7 Tips and techniques</a></H2> +<H2><a name="Python_nn45">38.7 Tips and techniques</a></H2> <p> @@ -3850,7 +3850,7 @@ strings, binary data, and arrays. This chapter discusses the common techniques solving these problems. </p> -<H3><a name="Python_nn46">37.7.1 Input and output parameters</a></H3> +<H3><a name="Python_nn46">38.7.1 Input and output parameters</a></H3> <p> @@ -4063,7 +4063,7 @@ void foo(Bar *OUTPUT); may not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>. </p> -<H3><a name="Python_nn47">37.7.2 Simple pointers</a></H3> +<H3><a name="Python_nn47">38.7.2 Simple pointers</a></H3> <p> @@ -4132,7 +4132,7 @@ If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type, name)</ See the <a href="Library.html#Library">SWIG Library</a> chapter for further details. </p> -<H3><a name="Python_nn48">37.7.3 Unbounded C Arrays</a></H3> +<H3><a name="Python_nn48">38.7.3 Unbounded C Arrays</a></H3> <p> @@ -4194,7 +4194,7 @@ well suited for applications in which you need to create buffers, package binary data, etc. </p> -<H3><a name="Python_nn49">37.7.4 String handling</a></H3> +<H3><a name="Python_nn49">38.7.4 String handling</a></H3> <p> @@ -4264,7 +4264,7 @@ also be used to extra binary data from arbitrary pointers. </p> -<H3><a name="Python_default_args">37.7.5 Default arguments</a></H3> +<H3><a name="Python_default_args">38.7.5 Default arguments</a></H3> <p> @@ -4363,7 +4363,7 @@ Versions of SWIG prior to this varied in their ability to convert C++ default va equivalent Python default argument values. </p> -<H2><a name="Python_nn53">37.8 Typemaps</a></H2> +<H2><a name="Python_nn53">38.8 Typemaps</a></H2> <p> @@ -4380,7 +4380,7 @@ Typemaps are only used if you want to change some aspect of the primitive C-Python interface or if you want to elevate your guru status. </p> -<H3><a name="Python_nn54">37.8.1 What is a typemap?</a></H3> +<H3><a name="Python_nn54">38.8.1 What is a typemap?</a></H3> <p> @@ -4496,7 +4496,7 @@ parameter is omitted): </pre> </div> -<H3><a name="Python_nn55">37.8.2 Python typemaps</a></H3> +<H3><a name="Python_nn55">38.8.2 Python typemaps</a></H3> <p> @@ -4537,7 +4537,7 @@ a look at the SWIG library version 1.3.20 or so. </p> -<H3><a name="Python_nn56">37.8.3 Typemap variables</a></H3> +<H3><a name="Python_nn56">38.8.3 Typemap variables</a></H3> <p> @@ -4608,7 +4608,7 @@ properly assigned. The Python name of the wrapper function being created. </div> -<H3><a name="Python_nn57">37.8.4 Useful Python Functions</a></H3> +<H3><a name="Python_nn57">38.8.4 Useful Python Functions</a></H3> <p> @@ -4736,7 +4736,7 @@ write me </pre> </div> -<H2><a name="Python_nn58">37.9 Typemap Examples</a></H2> +<H2><a name="Python_nn58">38.9 Typemap Examples</a></H2> <p> @@ -4745,7 +4745,7 @@ might look at the files "<tt>python.swg</tt>" and "<tt>typemaps.i</tt>" in the SWIG library. </p> -<H3><a name="Python_nn59">37.9.1 Converting Python list to a char ** </a></H3> +<H3><a name="Python_nn59">38.9.1 Converting Python list to a char ** </a></H3> <p> @@ -4825,7 +4825,7 @@ memory allocation is used to allocate memory for the array, the the C function. </p> -<H3><a name="Python_nn60">37.9.2 Expanding a Python object into multiple arguments</a></H3> +<H3><a name="Python_nn60">38.9.2 Expanding a Python object into multiple arguments</a></H3> <p> @@ -4944,7 +4944,7 @@ NotImplementedError: Wrong number or type of arguments for overloaded function ' </pre> </div> -<H3><a name="Python_nn61">37.9.3 Using typemaps to return arguments</a></H3> +<H3><a name="Python_nn61">38.9.3 Using typemaps to return arguments</a></H3> <p> @@ -5032,7 +5032,7 @@ function can now be used as follows: >>> </pre></div> -<H3><a name="Python_nn62">37.9.4 Mapping Python tuples into small arrays</a></H3> +<H3><a name="Python_nn62">38.9.4 Mapping Python tuples into small arrays</a></H3> <p> @@ -5081,7 +5081,7 @@ array, such an approach would not be recommended for huge arrays, but for small structures, this approach works fine. </p> -<H3><a name="Python_nn63">37.9.5 Mapping sequences to C arrays</a></H3> +<H3><a name="Python_nn63">38.9.5 Mapping sequences to C arrays</a></H3> <p> @@ -5170,7 +5170,7 @@ static int convert_darray(PyObject *input, double *ptr, int size) { </pre> </div> -<H3><a name="Python_nn64">37.9.6 Pointer handling</a></H3> +<H3><a name="Python_nn64">38.9.6 Pointer handling</a></H3> <p> @@ -5269,7 +5269,7 @@ class object (if applicable). -<H2><a name="Python_nn65">37.10 Docstring Features</a></H2> +<H2><a name="Python_nn65">38.10 Docstring Features</a></H2> <p> @@ -5297,7 +5297,7 @@ of your users much simpler. </p> -<H3><a name="Python_nn66">37.10.1 Module docstring</a></H3> +<H3><a name="Python_nn66">38.10.1 Module docstring</a></H3> <p> @@ -5331,7 +5331,7 @@ layout of controls on a panel, etc. to be loaded from an XML file." </div> -<H3><a name="Python_nn67">37.10.2 %feature("autodoc")</a></H3> +<H3><a name="Python_nn67">38.10.2 %feature("autodoc")</a></H3> <p> @@ -5359,7 +5359,7 @@ four levels for autodoc controlled by the value given to the feature, <tt>%feature("autodoc", "<i>level</i>")</tt>. The four values for <i>level</i> are covered in the following sub-sections. -<H4><a name="Python_nn68">37.10.2.1 %feature("autodoc", "0")</a></H4> +<H4><a name="Python_nn68">38.10.2.1 %feature("autodoc", "0")</a></H4> <p> @@ -5388,7 +5388,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_nn69">37.10.2.2 %feature("autodoc", "1")</a></H4> +<H4><a name="Python_nn69">38.10.2.2 %feature("autodoc", "1")</a></H4> <p> @@ -5413,7 +5413,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_autodoc2">37.10.2.3 %feature("autodoc", "2")</a></H4> +<H4><a name="Python_autodoc2">38.10.2.3 %feature("autodoc", "2")</a></H4> <p> @@ -5475,7 +5475,7 @@ def function_name(*args, **kwargs): </pre> </div> -<H4><a name="Python_autodoc3">37.10.2.4 %feature("autodoc", "3")</a></H4> +<H4><a name="Python_autodoc3">38.10.2.4 %feature("autodoc", "3")</a></H4> <p> @@ -5501,7 +5501,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_nn70">37.10.2.5 %feature("autodoc", "docstring")</a></H4> +<H4><a name="Python_nn70">38.10.2.5 %feature("autodoc", "docstring")</a></H4> <p> @@ -5520,7 +5520,7 @@ void GetPosition(int* OUTPUT, int* OUTPUT); </div> -<H3><a name="Python_nn71">37.10.3 %feature("docstring")</a></H3> +<H3><a name="Python_nn71">38.10.3 %feature("docstring")</a></H3> <p> @@ -5552,7 +5552,7 @@ with more than one line. </pre> </div> -<H2><a name="Python_nn72">37.11 Python Packages</a></H2> +<H2><a name="Python_nn72">38.11 Python Packages</a></H2> <p>Python has concepts of modules and packages. Modules are separate units of @@ -5627,7 +5627,7 @@ users may need to use special features such as the <tt>package</tt> option in th <tt>%module</tt> directive or import related command line options. These are explained in the following sections.</p> -<H3><a name="Python_modulepackage">37.11.1 Setting the Python package</a></H3> +<H3><a name="Python_modulepackage">38.11.1 Setting the Python package</a></H3> <p> @@ -5681,7 +5681,7 @@ pkg1/pkg2/_foo.so # (shared library built from C/C++ code generated by SWI </pre> </div> -<H3><a name="Python_absrelimports">37.11.2 Absolute and relative imports</a></H3> +<H3><a name="Python_absrelimports">38.11.2 Absolute and relative imports</a></H3> <p>Suppose, we have the following hierarchy of files:</p> @@ -5816,7 +5816,7 @@ uses relative imports. Second case is, when one puts import directives in <tt>__init__.py</tt> to import symbols from submodules or subpackages and the submodule depends on other submodules (discussed later).</p> -<H3><a name="Python_absimport">37.11.3 Enforcing absolute import semantics</a></H3> +<H3><a name="Python_absimport">38.11.3 Enforcing absolute import semantics</a></H3> <p>As you may know, there is an incompatibility in import semantics (for the @@ -5853,7 +5853,7 @@ from __future__ import absolute_import </pre> </div> -<H3><a name="Python_importfrominit">37.11.4 Importing from __init__.py</a></H3> +<H3><a name="Python_importfrominit">38.11.4 Importing from __init__.py</a></H3> <p>Imports in <tt>__init__.py</tt> are handy when you want to populate a @@ -5963,7 +5963,7 @@ class Bar(pkg3.foo.Foo): pass effect (note, that the Python 2 case also needs the <tt>-relativeimport</tt> workaround).</p> -<H3><a name="Python_implicit_namespace_packages">37.11.5 Implicit Namespace Packages</a></H3> +<H3><a name="Python_implicit_namespace_packages">38.11.5 Implicit Namespace Packages</a></H3> <p> Python 3.3 introduced @@ -6041,7 +6041,7 @@ zipimporter requires python-3.5.1 or newer to work with subpackages. </p> -<H3><a name="Python_package_search">37.11.6 Searching for the wrapper module</a></H3> +<H3><a name="Python_package_search">38.11.6 Searching for the wrapper module</a></H3> <p> @@ -6116,7 +6116,7 @@ following ways: </p> -<H4><a name="Python_package_search_both_package_modules">37.11.6.1 Both modules in the same package</a></H4> +<H4><a name="Python_package_search_both_package_modules">38.11.6.1 Both modules in the same package</a></H4> <p>Both modules are in one package:</p> @@ -6135,7 +6135,7 @@ from package import foo </div> -<H4><a name="Python_package_search_wrapper_split">37.11.6.2 Split modules</a></H4> +<H4><a name="Python_package_search_wrapper_split">38.11.6.2 Split modules</a></H4> <p>The pure python module is in a package and the C/C++ module is global:</p> @@ -6154,7 +6154,7 @@ from package import foo </div> -<H4><a name="Python_package_search_both_global_modules">37.11.6.3 Both modules are global</a></H4> +<H4><a name="Python_package_search_both_global_modules">38.11.6.3 Both modules are global</a></H4> <p>Both modules are global:</p> @@ -6179,7 +6179,7 @@ loaded modules. So, one may place the module either globally or in a package as desired. </p> -<H4><a name="Python_package_search_static">37.11.6.4 Statically linked C modules</a></H4> +<H4><a name="Python_package_search_static">38.11.6.4 Statically linked C modules</a></H4> <p>It is strongly recommended to use dynamically linked modules for the C @@ -6251,7 +6251,7 @@ module then you will either need to refer to the Python documentation on how to do this (remember you are now the Python importer) or use dynamic linking. </p> -<H2><a name="Python_python3support">37.12 Python 3 Support</a></H2> +<H2><a name="Python_python3support">38.12 Python 3 Support</a></H2> <p> @@ -6278,7 +6278,7 @@ The following are Python 3.0 new features that are currently supported by SWIG. </p> -<H3><a name="Python_nn74">37.12.1 Function annotation</a></H3> +<H3><a name="Python_nn74">38.12.1 Function annotation</a></H3> <p> @@ -6311,7 +6311,7 @@ For detailed usage of function annotation, see <a href="https://www.python.org/dev/peps/pep-3107/">PEP 3107</a>. </p> -<H3><a name="Python_nn75">37.12.2 Buffer interface</a></H3> +<H3><a name="Python_nn75">38.12.2 Buffer interface</a></H3> <p> @@ -6463,7 +6463,7 @@ modify the buffer. </div> -<H3><a name="Python_nn76">37.12.3 Abstract base classes</a></H3> +<H3><a name="Python_nn76">38.12.3 Abstract base classes</a></H3> <p> @@ -6504,7 +6504,7 @@ For details of abstract base class, please see <a href="https://www.python.org/dev/peps/pep-3119/">PEP 3119</a>. </p> -<H3><a name="Python_nn77">37.12.4 Byte string output conversion</a></H3> +<H3><a name="Python_nn77">38.12.4 Byte string output conversion</a></H3> <p> @@ -6684,7 +6684,7 @@ overloads taking both std::string (as Python bytes) and std::wstring (as Python unicode). </p> -<H3><a name="Python_2_unicode">37.12.5 Python 2 Unicode</a></H3> +<H3><a name="Python_2_unicode">38.12.5 Python 2 Unicode</a></H3> <p> @@ -6756,7 +6756,7 @@ the first is allowing unicode conversion and the second is explicitly prohibiting it. </p> -<H2><a name="Python_multithreaded">37.13 Support for Multithreaded Applications</a></H2> +<H2><a name="Python_multithreaded">38.13 Support for Multithreaded Applications</a></H2> <p>By default, SWIG does not enable support for multithreaded Python applications. More @@ -6771,7 +6771,7 @@ will not be able to run any other threads, even if the wrapped C/C++ code is wai interface for this is described in the next section. </p> -<H3><a name="Python_thread_UI">37.13.1 UI for Enabling Multithreading Support</a></H3> +<H3><a name="Python_thread_UI">38.13.1 UI for Enabling Multithreading Support</a></H3> <p>The user interface is as follows:</p> @@ -6814,7 +6814,7 @@ will not be able to run any other threads, even if the wrapped C/C++ code is wai </li> </ol> -<H3><a name="Python_thread_performance">37.13.2 Multithread Performance</a></H3> +<H3><a name="Python_thread_performance">38.13.2 Multithread Performance</a></H3> <p> diff --git a/Doc/Manual/R.html b/Doc/Manual/R.html index b6cf2d879..3a6aaeb3c 100644 --- a/Doc/Manual/R.html +++ b/Doc/Manual/R.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="R">38 SWIG and R</a></H1> +<H1><a name="R">39 SWIG and R</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -34,7 +34,7 @@ compile and run an R interface to QuantLib running on Mandriva Linux with gcc. The R bindings also work on Microsoft Windows using Visual C++. </p> -<H2><a name="R_nn2">38.1 Bugs</a></H2> +<H2><a name="R_nn2">39.1 Bugs</a></H2> <p> @@ -46,7 +46,7 @@ Currently the following features are not implemented or broken: <li>C Array wrappings </ul> -<H2><a name="R_nn3">38.2 Using R and SWIG</a></H2> +<H2><a name="R_nn3">39.2 Using R and SWIG</a></H2> <p> @@ -137,7 +137,7 @@ Error in .Call("R_swig_fact", s_arg1, as.logical(.copy), PACKAGE = "example") : <li>Make sure the architecture of the shared library(x64 for instance), matches the architecture of the R program you want to load your shared library into </ul> -<H2><a name="R_nn4">38.3 Precompiling large R files</a></H2> +<H2><a name="R_nn4">39.3 Precompiling large R files</a></H2> In cases where the R file is large, one make save a lot of loading @@ -155,7 +155,7 @@ will save a large amount of loading time. -<H2><a name="R_nn5">38.4 General policy</a></H2> +<H2><a name="R_nn5">39.4 General policy</a></H2> <p> @@ -164,7 +164,7 @@ wrapping over the underlying functions and rely on the R type system to provide R syntax. </p> -<H2><a name="R_language_conventions">38.5 Language conventions</a></H2> +<H2><a name="R_language_conventions">39.5 Language conventions</a></H2> <p> @@ -173,7 +173,7 @@ and [ are overloaded to allow for R syntax (one based indices and slices) </p> -<H2><a name="R_nn6">38.6 C++ classes</a></H2> +<H2><a name="R_nn6">39.6 C++ classes</a></H2> <p> @@ -185,7 +185,7 @@ keep track of the pointer object which removes the necessity for a lot of the proxy class baggage you see in other languages. </p> -<H2><a name="R_nn7">38.7 Enumerations</a></H2> +<H2><a name="R_nn7">39.7 Enumerations</a></H2> <p> diff --git a/Doc/Manual/Ruby.html b/Doc/Manual/Ruby.html index 051a40518..9b9b49d07 100644 --- a/Doc/Manual/Ruby.html +++ b/Doc/Manual/Ruby.html @@ -8,7 +8,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Ruby">39 SWIG and Ruby</a></H1> +<H1><a name="Ruby">40 SWIG and Ruby</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -149,7 +149,7 @@ <p>This chapter describes SWIG's support of Ruby.</p> -<H2><a name="Ruby_nn2">39.1 Preliminaries</a></H2> +<H2><a name="Ruby_nn2">40.1 Preliminaries</a></H2> <p> SWIG 3.0 is known to work with Ruby versions 1.8 and later. @@ -164,7 +164,7 @@ read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter. It is also assumed that the reader has a basic understanding of Ruby. </p> -<H3><a name="Ruby_nn3">39.1.1 Running SWIG</a></H3> +<H3><a name="Ruby_nn3">40.1.1 Running SWIG</a></H3> <p> To build a Ruby module, run SWIG using the <tt>-ruby</tt> @@ -188,7 +188,7 @@ if compiling a C++ extension) that contains all of the code needed to build a Ruby extension module. To finish building the module, you need to compile this file and link it with the rest of your program. </p> -<H3><a name="Ruby_nn4">39.1.2 Getting the right header files</a></H3> +<H3><a name="Ruby_nn4">40.1.2 Getting the right header files</a></H3> <p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt> @@ -202,7 +202,7 @@ the compiler options needed to compile the code is to ask Ruby itself:</p> </pre> </div> -<H3><a name="Ruby_nn5">39.1.3 Compiling a dynamic module</a></H3> +<H3><a name="Ruby_nn5">40.1.3 Compiling a dynamic module</a></H3> <p> Ruby extension modules are typically compiled into shared @@ -275,7 +275,7 @@ manual pages for your compiler and linker to determine the correct set of options. You might also check the <a href="https://github.com/swig/swig/wiki">SWIG Wiki</a> for additional information. </p> -<H3><a name="Ruby_nn6">39.1.4 Using your module</a></H3> +<H3><a name="Ruby_nn6">40.1.4 Using your module</a></H3> <p> Ruby <i>module</i> names must be capitalized, @@ -305,7 +305,7 @@ begins with: </p> <p> will result in an extension module using the feature name "example" and Ruby module name "Example". </p> -<H3><a name="Ruby_nn7">39.1.5 Static linking</a></H3> +<H3><a name="Ruby_nn7">40.1.5 Static linking</a></H3> <p> An alternative approach to dynamic linking is to rebuild the @@ -320,7 +320,7 @@ finding the Ruby source, adding an entry to the <tt>ext/Setup</tt> file, adding your directory to the list of extensions in the file, and finally rebuilding Ruby. </p> -<H3><a name="Ruby_nn8">39.1.6 Compilation of C++ extensions</a></H3> +<H3><a name="Ruby_nn8">40.1.6 Compilation of C++ extensions</a></H3> <p> On most machines, C++ extension modules should be linked @@ -352,7 +352,7 @@ $libs = append_library($libs, "supc++") create_makefile('example')</pre> </div> -<H2><a name="Ruby_nn9">39.2 Building Ruby Extensions under Windows 95/NT</a></H2> +<H2><a name="Ruby_nn9">40.2 Building Ruby Extensions under Windows 95/NT</a></H2> <p> Building a SWIG extension to Ruby under Windows 95/NT is @@ -377,7 +377,7 @@ order to build extensions, you may need to download the source distribution to the Ruby package, as you will need the Ruby header files. </p> -<H3><a name="Ruby_nn10">39.2.1 Running SWIG from Developer Studio</a></H3> +<H3><a name="Ruby_nn10">40.2.1 Running SWIG from Developer Studio</a></H3> <p> If you are developing your application within Microsoft @@ -441,13 +441,13 @@ Foo = 3.0 </pre> </div> -<H2><a name="Ruby_nn11">39.3 The Ruby-to-C/C++ Mapping</a></H2> +<H2><a name="Ruby_nn11">40.3 The Ruby-to-C/C++ Mapping</a></H2> <p> This section describes the basics of how SWIG maps C or C++ declarations in your SWIG interface files to Ruby constructs. </p> -<H3><a name="Ruby_nn12">39.3.1 Modules</a></H3> +<H3><a name="Ruby_nn12">40.3.1 Modules</a></H3> <p> The SWIG <tt>%module</tt> directive specifies @@ -519,7 +519,7 @@ option to wrap everything into the global module, take care that the names of your constants, classes and methods don't conflict with any of Ruby's built-in names. </p> -<H3><a name="Ruby_nn13">39.3.2 Functions</a></H3> +<H3><a name="Ruby_nn13">40.3.2 Functions</a></H3> <p> Global functions are wrapped as Ruby module methods. For @@ -553,7 +553,7 @@ irb(main):002:0> <b>Example.fact(4)</b> 24</pre> </div> -<H3><a name="Ruby_nn14">39.3.3 Variable Linking</a></H3> +<H3><a name="Ruby_nn14">40.3.3 Variable Linking</a></H3> <p> C/C++ global variables are wrapped as a pair of singleton @@ -615,7 +615,7 @@ directive. For example: </p> effect until it is explicitly disabled using <tt>%mutable</tt>. </p> -<H3><a name="Ruby_nn15">39.3.4 Constants</a></H3> +<H3><a name="Ruby_nn15">40.3.4 Constants</a></H3> <p> C/C++ constants are wrapped as module constants initialized @@ -643,7 +643,7 @@ irb(main):002:0> <b>Example::PI</b> 3.14159</pre> </div> -<H3><a name="Ruby_nn16">39.3.5 Pointers</a></H3> +<H3><a name="Ruby_nn16">40.3.5 Pointers</a></H3> <p> "Opaque" pointers to arbitrary C/C++ types (i.e. types that @@ -667,7 +667,7 @@ returns an instance of an internally generated Ruby class: </p> <p> A <tt>NULL</tt> pointer is always represented by the Ruby <tt>nil</tt> object. </p> -<H3><a name="Ruby_nn17">39.3.6 Structures</a></H3> +<H3><a name="Ruby_nn17">40.3.6 Structures</a></H3> <p> C/C++ structs are wrapped as Ruby classes, with accessor @@ -772,7 +772,7 @@ void Bar_f_set(Bar *b, Foo *val) { }</pre> </div> -<H3><a name="Ruby_nn18">39.3.7 C++ classes</a></H3> +<H3><a name="Ruby_nn18">40.3.7 C++ classes</a></H3> <p> Like structs, C++ classes are wrapped by creating a new Ruby @@ -827,7 +827,7 @@ Ale 3</pre> </div> -<H3><a name="Ruby_nn19">39.3.8 C++ Inheritance</a></H3> +<H3><a name="Ruby_nn19">40.3.8 C++ Inheritance</a></H3> <p> The SWIG type-checker is fully aware of C++ inheritance. @@ -980,7 +980,7 @@ inherit from both <tt>Base1</tt> and <tt>Base2</tt> (i.e. they exhibit <a href="http://c2.com/cgi/wiki?DuckTyping">"Duck Typing"</a>). </p> -<H3><a name="Ruby_nn20">39.3.9 C++ Overloaded Functions</a></H3> +<H3><a name="Ruby_nn20">40.3.9 C++ Overloaded Functions</a></H3> <p> C++ overloaded functions, methods, and constructors are @@ -1070,7 +1070,7 @@ arises--in this case, the first declaration takes precedence. </p> <p>Please refer to the <a href="SWIGPlus.html#SWIGPlus">"SWIG and C++"</a> chapter for more information about overloading. </p> -<H3><a name="Ruby_nn21">39.3.10 C++ Operators</a></H3> +<H3><a name="Ruby_nn21">40.3.10 C++ Operators</a></H3> <p> For the most part, overloaded operators are handled @@ -1112,7 +1112,7 @@ c = Example.add_complex(a, b)</pre> is discussed in the <a href="#Ruby_operator_overloading">section on operator overloading</a>. </p> -<H3><a name="Ruby_nn22">39.3.11 C++ namespaces</a></H3> +<H3><a name="Ruby_nn22">40.3.11 C++ namespaces</a></H3> <p> SWIG is aware of C++ namespaces, but namespace names do not @@ -1169,7 +1169,7 @@ and create extension modules for each namespace separately. If your program utilizes thousands of small deeply nested namespaces each with identical symbol names, well, then you get what you deserve. </p> -<H3><a name="Ruby_nn23">39.3.12 C++ templates</a></H3> +<H3><a name="Ruby_nn23">40.3.12 C++ templates</a></H3> <p> C++ templates don't present a huge problem for SWIG. However, @@ -1211,7 +1211,7 @@ irb(main):004:0> <b>p.second</b> 4</pre> </div> -<H3><a name="Ruby_nn23_1">39.3.13 C++ Standard Template Library (STL)</a></H3> +<H3><a name="Ruby_nn23_1">40.3.13 C++ Standard Template Library (STL)</a></H3> <p> On a related note, the standard SWIG library contains a @@ -1304,7 +1304,7 @@ puts v shown in these examples. More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter.</p> -<H3><a name="Ruby_C_STL_Functors">39.3.14 C++ STL Functors</a></H3> +<H3><a name="Ruby_C_STL_Functors">40.3.14 C++ STL Functors</a></H3> <p>Some containers in the STL allow you to modify their default @@ -1365,7 +1365,7 @@ b </pre> </div> -<H3><a name="Ruby_C_Iterators">39.3.15 C++ STL Iterators</a></H3> +<H3><a name="Ruby_C_Iterators">40.3.15 C++ STL Iterators</a></H3> <p>The STL is well known for the use of iterators. There @@ -1448,10 +1448,10 @@ i <p>If you'd rather have STL classes without any iterators, you should define <tt>-DSWIG_NO_EXPORT_ITERATOR_METHODS</tt> when running swig.</p> -<H3><a name="Ruby_nn24">39.3.16 C++ Smart Pointers</a></H3> +<H3><a name="Ruby_nn24">40.3.16 C++ Smart Pointers</a></H3> -<H4><a name="Ruby_smart_pointers_shared_ptr">39.3.16.1 The shared_ptr Smart Pointer</a></H4> +<H4><a name="Ruby_smart_pointers_shared_ptr">40.3.16.1 The shared_ptr Smart Pointer</a></H4> <p> @@ -1462,7 +1462,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a </p> -<H4><a name="Ruby_smart_pointers_generic">39.3.16.2 Generic Smart Pointers</a></H4> +<H4><a name="Ruby_smart_pointers_generic">40.3.16.2 Generic Smart Pointers</a></H4> <p> In certain C++ programs, it is common to use classes that @@ -1527,7 +1527,7 @@ method. For example: </p> <pre>irb(main):004:0> <b>f = p.__deref__()</b> # Returns underlying Foo *</pre> </div> -<H3><a name="Ruby_nn25">39.3.17 Cross-Language Polymorphism</a></H3> +<H3><a name="Ruby_nn25">40.3.17 Cross-Language Polymorphism</a></H3> <p> SWIG's Ruby module supports cross-language polymorphism @@ -1536,7 +1536,7 @@ module. Rather than duplicate the information presented in the <a href="Python.h section just notes the differences that you need to be aware of when using this feature with Ruby. </p> -<H4><a name="Ruby_nn26">39.3.17.1 Exception Unrolling</a></H4> +<H4><a name="Ruby_nn26">40.3.17.1 Exception Unrolling</a></H4> <p> Whenever a C++ director class routes one of its virtual @@ -1559,7 +1559,7 @@ method is "wrapped" using the <tt>rb_rescue2()</tt> function from Ruby's C API. If any Ruby exception is raised, it will be caught here and a C++ exception is raised in its place. </p> -<H2><a name="Ruby_nn27">39.4 Naming</a></H2> +<H2><a name="Ruby_nn27">40.4 Naming</a></H2> <p>Ruby has several common naming conventions. Constants are @@ -1597,7 +1597,7 @@ generated by SWIG, it is turned off by default in SWIG 1.3.28. However, it is planned to become the default option in future releases.</p> -<H3><a name="Ruby_nn28">39.4.1 Defining Aliases</a></H3> +<H3><a name="Ruby_nn28">40.4.1 Defining Aliases</a></H3> <p> It's a fairly common practice in the Ruby built-ins and @@ -1667,7 +1667,7 @@ matching rules used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization Features"</a>) for more details).</p> -<H3><a name="Ruby_nn29">39.4.2 Predicate Methods</a></H3> +<H3><a name="Ruby_nn29">40.4.2 Predicate Methods</a></H3> <p> Ruby methods that return a boolean value and end in a @@ -1716,7 +1716,7 @@ using SWIG's "features" mechanism and so the same name matching rules used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization Features"</a>) for more details). </p> -<H3><a name="Ruby_nn30">39.4.3 Bang Methods</a></H3> +<H3><a name="Ruby_nn30">40.4.3 Bang Methods</a></H3> <p> Ruby methods that modify an object in-place and end in an @@ -1748,7 +1748,7 @@ using SWIG's "features" mechanism and so the same name matching rules used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization Features"</a>) for more details). </p> -<H3><a name="Ruby_nn31">39.4.4 Getters and Setters</a></H3> +<H3><a name="Ruby_nn31">40.4.4 Getters and Setters</a></H3> <p> Often times a C++ library will expose properties through @@ -1783,7 +1783,7 @@ irb(main):003:0> <b>puts foo.value</b></pre> %rename("value=") Foo::setValue(int value);</pre> </div> -<H2><a name="Ruby_nn32">39.5 Input and output parameters</a></H2> +<H2><a name="Ruby_nn32">40.5 Input and output parameters</a></H2> <p> A common problem in some C programs is handling parameters @@ -1922,10 +1922,10 @@ void get_dimensions(Matrix *m, int *rows, int*columns);</pre> <pre>r, c = Example.get_dimensions(m)</pre> </div> -<H2><a name="Ruby_nn33">39.6 Exception handling </a></H2> +<H2><a name="Ruby_nn33">40.6 Exception handling </a></H2> -<H3><a name="Ruby_nn34">39.6.1 Using the %exception directive </a></H3> +<H3><a name="Ruby_nn34">40.6.1 Using the %exception directive </a></H3> <p>The SWIG <tt>%exception</tt> directive can be @@ -2034,7 +2034,7 @@ methods and functions named <tt>getitem</tt> and <tt>setitem</tt>. limited to C++ exception handling. See the chapter on <a href="Customization.html#Customization">Customization Features</a> for more examples.</p> -<H3><a name="Ruby_nn34_2">39.6.2 Handling Ruby Blocks </a></H3> +<H3><a name="Ruby_nn34_2">40.6.2 Handling Ruby Blocks </a></H3> <p>One of the highlights of Ruby and most of its standard library @@ -2101,7 +2101,7 @@ a special in typemap, like:</p> <p>For more information on typemaps, see <a href="#Ruby_nn37">Typemaps</a>.</p> -<H3><a name="Ruby_nn35">39.6.3 Raising exceptions </a></H3> +<H3><a name="Ruby_nn35">40.6.3 Raising exceptions </a></H3> <p>There are three ways to raise exceptions from C++ code to @@ -2258,7 +2258,7 @@ function. The first argument passed to <tt>rb_raise()</tt> is the exception type. You can raise a custom exception type or one of the built-in Ruby exception types.</p> -<H3><a name="Ruby_nn36">39.6.4 Exception classes </a></H3> +<H3><a name="Ruby_nn36">40.6.4 Exception classes </a></H3> <p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt> @@ -2295,7 +2295,7 @@ end </pre> <p>For another example look at swig/Examples/ruby/exception_class. </p> -<H2><a name="Ruby_nn37">39.7 Typemaps</a></H2> +<H2><a name="Ruby_nn37">40.7 Typemaps</a></H2> <p> This section describes how you can modify SWIG's default @@ -2310,7 +2310,7 @@ a required part of using SWIG---the default wrapping behavior is enough in most cases. Typemaps are only used if you want to change some aspect of the primitive C-Ruby interface.</p> -<H3><a name="Ruby_nn38">39.7.1 What is a typemap?</a></H3> +<H3><a name="Ruby_nn38">40.7.1 What is a typemap?</a></H3> <p> A typemap is nothing more than a code generation rule that is @@ -2467,7 +2467,7 @@ to be used as follows (notice how the length parameter is omitted): </p> 2</pre> </div> -<H3><a name="Ruby_Typemap_scope">39.7.2 Typemap scope</a></H3> +<H3><a name="Ruby_Typemap_scope">40.7.2 Typemap scope</a></H3> <p> Once defined, a typemap remains in effect for all of the @@ -2513,7 +2513,7 @@ where the class itself is defined. For example:</p> };</pre> </div> -<H3><a name="Ruby_Copying_a_typemap">39.7.3 Copying a typemap</a></H3> +<H3><a name="Ruby_Copying_a_typemap">40.7.3 Copying a typemap</a></H3> <p> A typemap is copied by using assignment. For example:</p> @@ -2555,7 +2555,7 @@ rules as for <tt> %apply (char *buf, int len) { (char *buffer, int size) }; // Multiple arguments</pre> </div> -<H3><a name="Ruby_Deleting_a_typemap">39.7.4 Deleting a typemap</a></H3> +<H3><a name="Ruby_Deleting_a_typemap">40.7.4 Deleting a typemap</a></H3> <p> A typemap can be deleted by simply defining no code. For @@ -2580,7 +2580,7 @@ defined by typemaps, clearing a fundamental type like <tt>int</tt> will make that type unusable unless you also define a new set of typemaps immediately after the clear operation.</p> -<H3><a name="Ruby_Placement_of_typemaps">39.7.5 Placement of typemaps</a></H3> +<H3><a name="Ruby_Placement_of_typemaps">40.7.5 Placement of typemaps</a></H3> <p> Typemap declarations can be declared in the global scope, @@ -2651,13 +2651,13 @@ In this example, this is done using the class declaration <tt>class string</tt> .</p> -<H3><a name="Ruby_nn39">39.7.6 Ruby typemaps</a></H3> +<H3><a name="Ruby_nn39">40.7.6 Ruby typemaps</a></H3> <p>The following list details all of the typemap methods that can be used by the Ruby module: </p> -<H4><a name="Ruby_in_typemap">39.7.6.1 "in" typemap</a></H4> +<H4><a name="Ruby_in_typemap">40.7.6.1 "in" typemap</a></H4> <p>Converts Ruby objects to input @@ -2724,7 +2724,7 @@ arguments to be specified. For example:</p> <p> At this time, only zero or one arguments may be converted.</p> -<H4><a name="Ruby_typecheck_typemap">39.7.6.2 "typecheck" typemap</a></H4> +<H4><a name="Ruby_typecheck_typemap">40.7.6.2 "typecheck" typemap</a></H4> <p> The "typecheck" typemap is used to support overloaded @@ -2746,7 +2746,7 @@ program uses overloaded methods, you should also define a collection of "typecheck" typemaps. More details about this follow in a later section on "Typemaps and Overloading."</p> -<H4><a name="Ruby_out_typemap">39.7.6.3 "out" typemap</a></H4> +<H4><a name="Ruby_out_typemap">40.7.6.3 "out" typemap</a></H4> <p>Converts return value of a C function @@ -2797,7 +2797,7 @@ version of the C datatype matched by the typemap.</td> </table> </div> -<H4><a name="Ruby_arginit_typemap">39.7.6.4 "arginit" typemap</a></H4> +<H4><a name="Ruby_arginit_typemap">40.7.6.4 "arginit" typemap</a></H4> <p> The "arginit" typemap is used to set the initial value of a @@ -2812,7 +2812,7 @@ applications. For example:</p> }</pre> </div> -<H4><a name="Ruby_default_typemap">39.7.6.5 "default" typemap</a></H4> +<H4><a name="Ruby_default_typemap">40.7.6.5 "default" typemap</a></H4> <p> The "default" typemap is used to turn an argument into a @@ -2837,7 +2837,7 @@ arguments that follow must have default values. See the <a href="SWIG.html#SWIG_ Default/optional arguments</a> section for further information on default argument wrapping.</p> -<H4><a name="Ruby_check_typemap">39.7.6.6 "check" typemap</a></H4> +<H4><a name="Ruby_check_typemap">40.7.6.6 "check" typemap</a></H4> <p> The "check" typemap is used to supply value checking code @@ -2852,7 +2852,7 @@ arguments have been converted. For example:</p> }</pre> </div> -<H4><a name="Ruby_argout_typemap_">39.7.6.7 "argout" typemap</a></H4> +<H4><a name="Ruby_argout_typemap_">40.7.6.7 "argout" typemap</a></H4> <p> The "argout" typemap is used to return values from arguments. @@ -2906,7 +2906,7 @@ some function like SWIG_Ruby_AppendOutput.</p> <p> See the <tt>typemaps.i</tt> library for examples.</p> -<H4><a name="Ruby_freearg_typemap_">39.7.6.8 "freearg" typemap</a></H4> +<H4><a name="Ruby_freearg_typemap_">40.7.6.8 "freearg" typemap</a></H4> <p> The "freearg" typemap is used to cleanup argument data. It is @@ -2933,7 +2933,7 @@ This code is also placed into a special variable <tt>$cleanup</tt> that may be used in other typemaps whenever a wrapper function needs to abort prematurely.</p> -<H4><a name="Ruby_newfree_typemap">39.7.6.9 "newfree" typemap</a></H4> +<H4><a name="Ruby_newfree_typemap">40.7.6.9 "newfree" typemap</a></H4> <p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt> @@ -2957,7 +2957,7 @@ string *foo();</pre> <p> See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for further details.</p> -<H4><a name="Ruby_memberin_typemap">39.7.6.10 "memberin" typemap</a></H4> +<H4><a name="Ruby_memberin_typemap">40.7.6.10 "memberin" typemap</a></H4> <p> The "memberin" typemap is used to copy data from<em> an @@ -2975,21 +2975,21 @@ example:</p> already provides a default implementation for arrays, strings, and other objects.</p> -<H4><a name="Ruby_varin_typemap">39.7.6.11 "varin" typemap</a></H4> +<H4><a name="Ruby_varin_typemap">40.7.6.11 "varin" typemap</a></H4> <p> The "varin" typemap is used to convert objects in the target language to C for the purposes of assigning to a C/C++ global variable. This is implementation specific.</p> -<H4><a name="Ruby_varout_typemap_">39.7.6.12 "varout" typemap</a></H4> +<H4><a name="Ruby_varout_typemap_">40.7.6.12 "varout" typemap</a></H4> <p> The "varout" typemap is used to convert a C/C++ object to an object in the target language when reading a C/C++ global variable. This is implementation specific.</p> -<H4><a name="Ruby_throws_typemap">39.7.6.13 "throws" typemap</a></H4> +<H4><a name="Ruby_throws_typemap">40.7.6.13 "throws" typemap</a></H4> <p> The "throws" typemap is only used when SWIG parses a C++ @@ -3030,7 +3030,7 @@ specification yet they do throw exceptions, SWIG cannot know how to deal with them. For a neat way to handle these, see the <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section.</p> -<H4><a name="Ruby_directorin_typemap">39.7.6.14 directorin typemap</a></H4> +<H4><a name="Ruby_directorin_typemap">40.7.6.14 directorin typemap</a></H4> <p>Converts C++ objects in director @@ -3089,7 +3089,7 @@ referring to the class itself.</td> </table> </div> -<H4><a name="Ruby_directorout_typemap">39.7.6.15 directorout typemap</a></H4> +<H4><a name="Ruby_directorout_typemap">40.7.6.15 directorout typemap</a></H4> <p>Converts Ruby objects in director @@ -3162,7 +3162,7 @@ exception. </p> -<H4><a name="Ruby_directorargout_typemap">39.7.6.16 directorargout typemap</a></H4> +<H4><a name="Ruby_directorargout_typemap">40.7.6.16 directorargout typemap</a></H4> <p>Output argument processing in director @@ -3220,19 +3220,19 @@ referring to the instance of the class itself</td> </table> </div> -<H4><a name="Ruby_ret_typemap">39.7.6.17 ret typemap</a></H4> +<H4><a name="Ruby_ret_typemap">40.7.6.17 ret typemap</a></H4> <p>Cleanup of function return values </p> -<H4><a name="Ruby_globalin_typemap">39.7.6.18 globalin typemap</a></H4> +<H4><a name="Ruby_globalin_typemap">40.7.6.18 globalin typemap</a></H4> <p>Setting of C global variables </p> -<H3><a name="Ruby_nn40">39.7.7 Typemap variables</a></H3> +<H3><a name="Ruby_nn40">40.7.7 Typemap variables</a></H3> <p> @@ -3282,7 +3282,7 @@ so that their values can be properly assigned. </div> <div class="indent">The Ruby name of the wrapper function being created. </div> -<H3><a name="Ruby_nn41">39.7.8 Useful Functions</a></H3> +<H3><a name="Ruby_nn41">40.7.8 Useful Functions</a></H3> <p> When you write a typemap, you usually have to work directly @@ -3297,7 +3297,7 @@ stick to the swig functions instead of the native Ruby functions. That should help you avoid having to rewrite a lot of typemaps across multiple languages.</p> -<H4><a name="Ruby_nn42">39.7.8.1 C Datatypes to Ruby Objects</a></H4> +<H4><a name="Ruby_nn42">40.7.8.1 C Datatypes to Ruby Objects</a></H4> <div class="diagram"> @@ -3339,7 +3339,7 @@ SWIG_From_float(float)</td> </table> </div> -<H4><a name="Ruby_nn43">39.7.8.2 Ruby Objects to C Datatypes</a></H4> +<H4><a name="Ruby_nn43">40.7.8.2 Ruby Objects to C Datatypes</a></H4> <p>Here, while the Ruby versions return the value directly, the SWIG @@ -3407,7 +3407,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt> </table> </div> -<H4><a name="Ruby_nn44">39.7.8.3 Macros for VALUE</a></H4> +<H4><a name="Ruby_nn44">40.7.8.3 Macros for VALUE</a></H4> <p> <tt>RSTRING_LEN(str)</tt> </p> @@ -3430,7 +3430,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt> <div class="indent">pointer to array storage</div> -<H4><a name="Ruby_nn45">39.7.8.4 Exceptions</a></H4> +<H4><a name="Ruby_nn45">40.7.8.4 Exceptions</a></H4> <p> <tt>void rb_raise(VALUE exception, const char *fmt, @@ -3509,7 +3509,7 @@ message to standard error if Ruby was invoked with the <tt>-w</tt> flag. The given format string <i>fmt</i> and remaining arguments are interpreted as with <tt>printf()</tt>. </div> -<H4><a name="Ruby_nn46">39.7.8.5 Iterators</a></H4> +<H4><a name="Ruby_nn46">40.7.8.5 Iterators</a></H4> <p> <tt>void rb_iter_break()</tt> </p> @@ -3555,14 +3555,14 @@ VALUE), VALUE value)</tt></p> <div class="indent"> Equivalent to Ruby's <tt>throw</tt>. </div> -<H3><a name="Ruby_nn47">39.7.9 Typemap Examples</a></H3> +<H3><a name="Ruby_nn47">40.7.9 Typemap Examples</a></H3> <p> This section includes a few examples of typemaps. For more examples, you might look at the examples in the <tt>Example/ruby</tt> directory. </p> -<H3><a name="Ruby_nn48">39.7.10 Converting a Ruby array to a char **</a></H3> +<H3><a name="Ruby_nn48">40.7.10 Converting a Ruby array to a char **</a></H3> <p> A common problem in many C programs is the processing of @@ -3627,7 +3627,7 @@ array. Since dynamic memory allocation is used to allocate memory for the array, the "freearg" typemap is used to later release this memory after the execution of the C function. </p> -<H3><a name="Ruby_nn49">39.7.11 Collecting arguments in a hash</a></H3> +<H3><a name="Ruby_nn49">40.7.11 Collecting arguments in a hash</a></H3> <p> Ruby's solution to the "keyword arguments" capability of some @@ -3841,7 +3841,7 @@ memory leak. Fortunately, this typemap is a lot easier to write: </p> program that uses the extension, can be found in the <tt>Examples/ruby/hashargs</tt> directory of the SWIG distribution. </p> -<H3><a name="Ruby_nn50">39.7.12 Pointer handling</a></H3> +<H3><a name="Ruby_nn50">40.7.12 Pointer handling</a></H3> <p> Occasionally, it might be necessary to convert pointer values @@ -3900,7 +3900,7 @@ For example: </p> }</pre> </div> -<H4><a name="Ruby_nn51">39.7.12.1 Ruby Datatype Wrapping</a></H4> +<H4><a name="Ruby_nn51">40.7.12.1 Ruby Datatype Wrapping</a></H4> <p> <tt>VALUE Data_Wrap_Struct(VALUE class, void @@ -3927,7 +3927,7 @@ as above. </div> type <i>c-type</i> from the data object <i>obj</i> and assigns that pointer to <i>ptr</i>. </div> -<H3><a name="Ruby_nn52">39.7.13 Example: STL Vector to Ruby Array</a></H3> +<H3><a name="Ruby_nn52">40.7.13 Example: STL Vector to Ruby Array</a></H3> <p>Another use for macros and type maps is to create a Ruby array @@ -4019,7 +4019,7 @@ STL with ruby, you are advised to use the standard swig STL library, which does much more than this. Refer to the section called the<a href="#Ruby_nn23_1"> C++ Standard Template Library</a>. -<H2><a name="Ruby_nn65">39.8 Docstring Features</a></H2> +<H2><a name="Ruby_nn65">40.8 Docstring Features</a></H2> <p> @@ -4053,7 +4053,7 @@ generate ri documentation from a c wrap file, you could do:</p> $ rdoc -r file_wrap.c </pre></div> -<H3><a name="Ruby_nn66">39.8.1 Module docstring</a></H3> +<H3><a name="Ruby_nn66">40.8.1 Module docstring</a></H3> <p> @@ -4083,7 +4083,7 @@ layout of controls on a panel, etc. to be loaded from an XML file." %module(docstring=DOCSTRING) xrc</pre> </div> -<H3><a name="Ruby_nn67">39.8.2 %feature("autodoc")</a></H3> +<H3><a name="Ruby_nn67">40.8.2 %feature("autodoc")</a></H3> <p>Since SWIG does know everything about the function it wraps, @@ -4104,7 +4104,7 @@ several options for autodoc controlled by the value given to the feature, described below. </p> -<H4><a name="Ruby_nn68">39.8.2.1 %feature("autodoc", "0")</a></H4> +<H4><a name="Ruby_nn68">40.8.2.1 %feature("autodoc", "0")</a></H4> <p> @@ -4128,7 +4128,7 @@ Then Ruby code like this will be generated: ...</pre> </div> -<H4><a name="Ruby_autodoc1">39.8.2.2 %feature("autodoc", "1")</a></H4> +<H4><a name="Ruby_autodoc1">40.8.2.2 %feature("autodoc", "1")</a></H4> <p> @@ -4148,7 +4148,7 @@ this: ...</pre> </div> -<H4><a name="Ruby_autodoc2">39.8.2.3 %feature("autodoc", "2")</a></H4> +<H4><a name="Ruby_autodoc2">40.8.2.3 %feature("autodoc", "2")</a></H4> <p> @@ -4160,7 +4160,7 @@ parameter types with the "2" option will result in Ruby code like this: </p> -<H4><a name="Ruby_feature_autodoc3">39.8.2.4 %feature("autodoc", "3")</a></H4> +<H4><a name="Ruby_feature_autodoc3">40.8.2.4 %feature("autodoc", "3")</a></H4> <p> @@ -4181,7 +4181,7 @@ Parameters: bar - Bar</pre> </div> -<H4><a name="Ruby_nn70">39.8.2.5 %feature("autodoc", "docstring")</a></H4> +<H4><a name="Ruby_nn70">40.8.2.5 %feature("autodoc", "docstring")</a></H4> <p> @@ -4197,7 +4197,7 @@ generated string. For example: void GetPosition(int* OUTPUT, int* OUTPUT);</pre> </div> -<H3><a name="Ruby_nn71">39.8.3 %feature("docstring")</a></H3> +<H3><a name="Ruby_nn71">40.8.3 %feature("docstring")</a></H3> <p> @@ -4208,10 +4208,10 @@ docstring associated with classes, function or methods are output. If an item already has an autodoc string then it is combined with the docstring and they are output together. </p> -<H2><a name="Ruby_nn53">39.9 Advanced Topics</a></H2> +<H2><a name="Ruby_nn53">40.9 Advanced Topics</a></H2> -<H3><a name="Ruby_operator_overloading">39.9.1 Operator overloading</a></H3> +<H3><a name="Ruby_operator_overloading">40.9.1 Operator overloading</a></H3> <p> SWIG allows operator overloading with, by using the <tt>%extend</tt> @@ -4392,7 +4392,7 @@ separate method for handling <i>inequality</i> since Ruby parses the expression <i>a != b</i> as <i>!(a == b)</i>. </p> -<H3><a name="Ruby_nn55">39.9.2 Creating Multi-Module Packages</a></H3> +<H3><a name="Ruby_nn55">40.9.2 Creating Multi-Module Packages</a></H3> <p> The chapter on <a href="Modules.html#Modules">Working @@ -4518,7 +4518,7 @@ irb(main):005:0> <b>c.getX()</b> 5.0</pre> </div> -<H3><a name="Ruby_nn56">39.9.3 Specifying Mixin Modules</a></H3> +<H3><a name="Ruby_nn56">40.9.3 Specifying Mixin Modules</a></H3> <p> The Ruby language doesn't support multiple inheritance, but @@ -4585,7 +4585,7 @@ matching rules used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization Features"</a>) for more details). </p> -<H2><a name="Ruby_nn57">39.10 Memory Management</a></H2> +<H2><a name="Ruby_nn57">40.10 Memory Management</a></H2> <p>One of the most common issues in generating SWIG bindings for @@ -4608,7 +4608,7 @@ to C++ (or vice versa) depending on what function or methods are invoked. Clearly, developing a SWIG wrapper requires a thorough understanding of how the underlying library manages memory.</p> -<H3><a name="Ruby_nn58">39.10.1 Mark and Sweep Garbage Collector </a></H3> +<H3><a name="Ruby_nn58">40.10.1 Mark and Sweep Garbage Collector </a></H3> <p>Ruby uses a mark and sweep garbage collector. When the garbage @@ -4639,7 +4639,7 @@ any memory has been allocated in creating the underlying C struct or C++ struct, then a "free" function must be defined that deallocates this memory. </p> -<H3><a name="Ruby_nn59">39.10.2 Object Ownership</a></H3> +<H3><a name="Ruby_nn59">40.10.2 Object Ownership</a></H3> <p>As described above, memory management depends on clearly @@ -4784,7 +4784,7 @@ public: <p> This code can be seen in swig/examples/ruby/tracking.</p> -<H3><a name="Ruby_nn60">39.10.3 Object Tracking</a></H3> +<H3><a name="Ruby_nn60">40.10.3 Object Tracking</a></H3> <p>The remaining parts of this section will use the class library @@ -5010,7 +5010,7 @@ However, if you implement your own free functions (see below) you may also have to call the <tt>SWIG_RubyRemoveTracking</tt> and <tt>RubyUnlinkObjects</tt> methods.</p> -<H3><a name="Ruby_nn61">39.10.4 Mark Functions</a></H3> +<H3><a name="Ruby_nn61">40.10.4 Mark Functions</a></H3> <p>With a bit more testing, we see that our class library still @@ -5139,7 +5139,7 @@ irb(main):016:0></pre> <p>This code can be seen in swig/examples/ruby/mark_function.</p> -<H3><a name="Ruby_nn62">39.10.5 Free Functions</a></H3> +<H3><a name="Ruby_nn62">40.10.5 Free Functions</a></H3> <p>By default, SWIG creates a "free" function that is called when @@ -5307,7 +5307,7 @@ been freed, and thus raises a runtime exception.</p> <p>This code can be seen in swig/examples/ruby/free_function.</p> -<H3><a name="Ruby_nn63">39.10.6 Embedded Ruby and the C++ Stack</a></H3> +<H3><a name="Ruby_nn63">40.10.6 Embedded Ruby and the C++ Stack</a></H3> <p>As has been said, the Ruby GC runs and marks objects before diff --git a/Doc/Manual/Scilab.html b/Doc/Manual/Scilab.html index f1cc742a9..19c196541 100644 --- a/Doc/Manual/Scilab.html +++ b/Doc/Manual/Scilab.html @@ -9,7 +9,7 @@ <body bgcolor="#ffffff"> -<H1><a name="Scilab">40 SWIG and Scilab</a></H1> +<H1><a name="Scilab">41 SWIG and Scilab</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -88,7 +88,7 @@ This chapter explains how to use SWIG for Scilab. After this introduction, you s </p> -<H2><a name="Scilab_preliminaries">40.1 Preliminaries</a></H2> +<H2><a name="Scilab_preliminaries">41.1 Preliminaries</a></H2> <p> @@ -105,7 +105,7 @@ SWIG for Scilab supports C language. C++ is partially supported. See <a href="#S </p> -<H2><a name="Scilab_running_swig">40.2 Running SWIG</a></H2> +<H2><a name="Scilab_running_swig">41.2 Running SWIG</a></H2> <p> @@ -139,7 +139,7 @@ Note: a code in an <tt>%inline</tt> section is both parsed and wrapped by SWIG, </p> -<H3><a name="Scilab_running_swig_generating_module">40.2.1 Generating the module</a></H3> +<H3><a name="Scilab_running_swig_generating_module">41.2.1 Generating the module</a></H3> <p> @@ -182,7 +182,7 @@ The <tt>swig</tt> executable has several other command line options you can use. </p> -<H3><a name="Scilab_running_swig_building_module">40.2.2 Building the module</a></H3> +<H3><a name="Scilab_running_swig_building_module">41.2.2 Building the module</a></H3> <p> @@ -202,7 +202,7 @@ $ gcc -shared example_wrap.o -o libexample.so Note: we supposed in this example that the path to the Scilab include directory is <tt>/usr/local/include/scilab</tt> (which is the case in a Debian environment), this should be changed for another environment. </p> -<H3><a name="Scilab_running_swig_loading_module">40.2.3 Loading the module</a></H3> +<H3><a name="Scilab_running_swig_loading_module">41.2.3 Loading the module</a></H3> <p> @@ -226,7 +226,7 @@ Link done. which means that Scilab has successfully loaded the shared library. The module functions and other symbols are now available in Scilab. </p> -<H3><a name="Scilab_running_swig_using_module">40.2.4 Using the module</a></H3> +<H3><a name="Scilab_running_swig_using_module">41.2.4 Using the module</a></H3> <p> @@ -260,7 +260,7 @@ ans = Note: for conciseness, we assume in the subsequent Scilab code examples that the modules have been beforehand built and loaded in Scilab. </p> -<H3><a name="Scilab_running_swig_options">40.2.5 Scilab command line options</a></H3> +<H3><a name="Scilab_running_swig_options">41.2.5 Scilab command line options</a></H3> <p> @@ -320,10 +320,10 @@ $ swig -scilab -help </pre></div> -<H2><a name="Scilab_wrapping">40.3 A basic tour of C/C++ wrapping</a></H2> +<H2><a name="Scilab_wrapping">41.3 A basic tour of C/C++ wrapping</a></H2> -<H3><a name="Scilab_wrapping_overview">40.3.1 Overview</a></H3> +<H3><a name="Scilab_wrapping_overview">41.3.1 Overview</a></H3> <p> @@ -332,7 +332,7 @@ This means that functions, structs, classes, variables, etc... are interfaced th There are a few exceptions, such as constants and enumerations, which can be wrapped directly as Scilab variables. </p> -<H3><a name="Scilab_wrapping_identifiers">40.3.2 Identifiers</a></H3> +<H3><a name="Scilab_wrapping_identifiers">41.3.2 Identifiers</a></H3> <p> @@ -347,7 +347,7 @@ In these cases, the <a href="SWIG.html#SWIG_rename_ignore">%rename directive</a> Note: truncations can be disabled by specifying the target version 6 of Scilab in the <tt>targetversion</tt> argument (i.e. <tt>-targetversion 6</tt>). </p> -<H3><a name="Scilab_wrapping_functions">40.3.3 Functions</a></H3> +<H3><a name="Scilab_wrapping_functions">41.3.3 Functions</a></H3> <p> @@ -378,7 +378,7 @@ ans = 24. </pre></div> -<H4><a name="Scilab_nn13">40.3.3.1 Argument passing</a></H4> +<H4><a name="Scilab_nn13">41.3.3.1 Argument passing</a></H4> <p> @@ -431,7 +431,7 @@ In Scilab, parameters are passed by value. The output (and inout) parameters are 7. </pre></div> -<H4><a name="Scilab_nn14">40.3.3.2 Multiple output arguments</a></H4> +<H4><a name="Scilab_nn14">41.3.3.2 Multiple output arguments</a></H4> <p> @@ -480,7 +480,7 @@ int divide(int n, int d, int *OUTPUT, int *OUTPUT); </pre></div> -<H3><a name="Scilab_wrapping_global_variables">40.3.4 Global variables</a></H3> +<H3><a name="Scilab_wrapping_global_variables">41.3.4 Global variables</a></H3> <p> @@ -549,10 +549,10 @@ It works the same:</p> </pre></div> -<H3><a name="Scilab_wrapping_constants_and_enums">40.3.5 Constants and enumerations</a></H3> +<H3><a name="Scilab_wrapping_constants_and_enums">41.3.5 Constants and enumerations</a></H3> -<H4><a name="Scilab_wrapping_constants">40.3.5.1 Constants</a></H4> +<H4><a name="Scilab_wrapping_constants">41.3.5.1 Constants</a></H4> <p> @@ -693,7 +693,7 @@ are mapped to Scilab variables, with the same name: 3.14 </pre></div> -<H4><a name="Scilab_wrapping_enums">40.3.5.2 Enumerations</a></H4> +<H4><a name="Scilab_wrapping_enums">41.3.5.2 Enumerations</a></H4> <p> @@ -758,7 +758,7 @@ typedef enum { RED, BLUE, GREEN } color; </pre></div> -<H3><a name="Scilab_wrapping_pointers">40.3.6 Pointers</a></H3> +<H3><a name="Scilab_wrapping_pointers">41.3.6 Pointers</a></H3> <p> @@ -820,7 +820,7 @@ Note: the type name <tt>_p_FILE</tt> which means "pointer to FILE". The user of a pointer is responsible for freeing it or, like in the example, closing any resources associated with it (just as is required in a C program). </p> -<H4><a name="Scilab_wrapping_pointers_utility_functions">40.3.6.1 Utility functions</a></H4> +<H4><a name="Scilab_wrapping_pointers_utility_functions">41.3.6.1 Utility functions</a></H4> <p> @@ -861,7 +861,7 @@ ans = </pre></div> -<H4><a name="Scilab_wrapping_pointers_null_pointers">40.3.6.2 Null pointers:</a></H4> +<H4><a name="Scilab_wrapping_pointers_null_pointers">41.3.6.2 Null pointers:</a></H4> <p> @@ -877,7 +877,7 @@ Using the previous <tt>SWIG_this()</tt> and <tt>SWIG_ptr()</tt>, it is possible </pre></div> -<H3><a name="Scilab_wrapping_structs">40.3.7 Structures</a></H3> +<H3><a name="Scilab_wrapping_structs">41.3.7 Structures</a></H3> <p> @@ -986,7 +986,7 @@ Note: the pointer to the struct works as described in <a href="Scilab_wrapping_p --> delete_Bar(b); </pre></div> -<H3><a name="Scilab_wrapping_cpp_classes">40.3.8 C++ classes</a></H3> +<H3><a name="Scilab_wrapping_cpp_classes">41.3.8 C++ classes</a></H3> <p> @@ -1054,7 +1054,7 @@ Note: like structs, class pointers are mapped as described in <a href="Scilab_wr --> delete_Point(p); </pre></div> -<H3><a name="Scilab_wrapping_cpp_inheritance">40.3.9 C++ inheritance</a></H3> +<H3><a name="Scilab_wrapping_cpp_inheritance">41.3.9 C++ inheritance</a></H3> <p> @@ -1129,7 +1129,7 @@ But we can use either use the <tt>get_perimeter()</tt> function of the parent cl 18.84 </pre></div> -<H3><a name="Scilab_wrapping_cpp_overloading">40.3.10 C++ overloading</a></H3> +<H3><a name="Scilab_wrapping_cpp_overloading">41.3.10 C++ overloading</a></H3> <p> @@ -1169,7 +1169,7 @@ void magnify(Circle *circle, double factor) { </pre></div> -<H3><a name="Scilab_wrapping_pointers_references_values_arrays">40.3.11 Pointers, references, values, and arrays</a></H3> +<H3><a name="Scilab_wrapping_pointers_references_values_arrays">41.3.11 Pointers, references, values, and arrays</a></H3> <p> @@ -1227,7 +1227,7 @@ All these functions will return a pointer to an instance of <tt>Foo</tt>. As the function <tt>spam7</tt> returns a value, new instance of <tt>Foo</tt> has to be allocated, and a pointer on this instance is returned. </p> -<H3><a name="Scilab_wrapping_cpp_templates">40.3.12 C++ templates</a></H3> +<H3><a name="Scilab_wrapping_cpp_templates">41.3.12 C++ templates</a></H3> <p> @@ -1286,7 +1286,7 @@ Then in Scilab: More details on template support can be found in the <a href="SWIGPlus.html#SWIGPlus_nn30">templates</a> documentation. </p> -<H3><a name="Scilab_wrapping_cpp_operators">40.3.13 C++ operators</a></H3> +<H3><a name="Scilab_wrapping_cpp_operators">41.3.13 C++ operators</a></H3> <p> @@ -1339,7 +1339,7 @@ private: </pre></div> -<H3><a name="Scilab_wrapping_cpp_namespaces">40.3.14 C++ namespaces</a></H3> +<H3><a name="Scilab_wrapping_cpp_namespaces">41.3.14 C++ namespaces</a></H3> <p> @@ -1417,7 +1417,7 @@ Note: the <a href="SWIGPlus.html#SWIGPlus_nspace">nspace</a> feature is not supp </p> -<H3><a name="Scilab_wrapping_cpp_exceptions">40.3.15 C++ exceptions</a></H3> +<H3><a name="Scilab_wrapping_cpp_exceptions">41.3.15 C++ exceptions</a></H3> <p> @@ -1500,17 +1500,17 @@ More complex or custom exception types require specific exception typemaps to be See the <a href="SWIGPlus.html#SWIGPlus">SWIG C++ documentation</a> for more details. </p> -<H3><a name="Scilab_wrapping_cpp_stl">40.3.16 C++ STL</a></H3> +<H3><a name="Scilab_wrapping_cpp_stl">41.3.16 C++ STL</a></H3> <p> The Standard Template Library (STL) is partially supported. See <a href="#Scilab_typemaps_stl">STL</a> for more details. </p> -<H2><a name="Scilab_typemaps">40.4 Type mappings and libraries</a></H2> +<H2><a name="Scilab_typemaps">41.4 Type mappings and libraries</a></H2> -<H3><a name="Scilab_typemaps_primitive_types">40.4.1 Default primitive type mappings</a></H3> +<H3><a name="Scilab_typemaps_primitive_types">41.4.1 Default primitive type mappings</a></H3> <p> @@ -1561,7 +1561,7 @@ The default behaviour is for SWIG to generate code that will give a runtime erro -<H3><a name="Scilab_typemaps_arrays">40.4.2 Arrays</a></H3> +<H3><a name="Scilab_typemaps_arrays">41.4.2 Arrays</a></H3> <p> @@ -1616,7 +1616,7 @@ void printArray(int values[], int len) { [ 0 1 2 3 ] </pre></div> -<H3><a name="Scilab_typemaps_pointer-to-pointers">40.4.3 Pointer-to-pointers</a></H3> +<H3><a name="Scilab_typemaps_pointer-to-pointers">41.4.3 Pointer-to-pointers</a></H3> <p> @@ -1689,7 +1689,7 @@ void print_matrix(double **M, int nbRows, int nbCols) { </pre></div> -<H3><a name="Scilab_typemaps_matrices">40.4.4 Matrices</a></H3> +<H3><a name="Scilab_typemaps_matrices">41.4.4 Matrices</a></H3> <p> @@ -1782,7 +1782,7 @@ The remarks made earlier for arrays also apply here: <li>There is no control while converting <tt>double</tt> values to integers, <tt>double</tt> values are truncated without any checking or warning.</li> </ul> -<H3><a name="Scilab_typemaps_stl">40.4.5 STL</a></H3> +<H3><a name="Scilab_typemaps_stl">41.4.5 STL</a></H3> <p> @@ -1982,7 +1982,7 @@ ans = --> delete_PersonPtrSet(p); </pre></div> -<H2><a name="Scilab_module_initialization">40.5 Module initialization</a></H2> +<H2><a name="Scilab_module_initialization">41.5 Module initialization</a></H2> <p> @@ -2006,7 +2006,7 @@ For example, to initialize the module <tt>example</tt>: --> example_Init(); </pre></div> -<H2><a name="Scilab_building_modes">40.6 Building modes</a></H2> +<H2><a name="Scilab_building_modes">41.6 Building modes</a></H2> <p> @@ -2021,7 +2021,7 @@ To produce a dynamic module, when generating the wrapper, there are two possibil <li>the <tt>builder</tt> mode. In this mode, Scilab is responsible of building. </ul> -<H3><a name="Scilab_building_modes_nobuilder_mode">40.6.1 No-builder mode</a></H3> +<H3><a name="Scilab_building_modes_nobuilder_mode">41.6.1 No-builder mode</a></H3> <p> @@ -2034,7 +2034,7 @@ This mode is the best option to use when you have to integrate the module build </p> -<H3><a name="Scilab_building_modes_builder_mode">40.6.2 Builder mode</a></H3> +<H3><a name="Scilab_building_modes_builder_mode">41.6.2 Builder mode</a></H3> <p> @@ -2074,14 +2074,14 @@ The command is: $ swig -scilab -builder -buildercflags -I/opt/foo/include -builderldflags "-L/opt/foo/lib -lfoo" -buildersources baa1.cxx, baa2.cxx example.i </pre></div> -<H2><a name="Scilab_generated_scripts">40.7 Generated scripts</a></H2> +<H2><a name="Scilab_generated_scripts">41.7 Generated scripts</a></H2> <p> In this part we give some details about the generated Scilab scripts. </p> -<H3><a name="Scilab_generated_scripts_builder_script">40.7.1 Builder script</a></H3> +<H3><a name="Scilab_generated_scripts_builder_script">41.7.1 Builder script</a></H3> <p> @@ -2106,7 +2106,7 @@ ilib_build(ilib_name, table, files, libs); <li><tt><b>table</b></tt>: two column string matrix containing a table of pairs of 'scilab function name', 'C function name'.</li> </ul> -<H3><a name="Scilab_generated_scripts_loader_script">40.7.2 Loader script</a></H3> +<H3><a name="Scilab_generated_scripts_loader_script">41.7.2 Loader script</a></H3> <p> @@ -2145,7 +2145,7 @@ clear get_file_path; </ul> -<H2><a name="Scilab_other_resources">40.8 Other resources</a></H2> +<H2><a name="Scilab_other_resources">41.8 Other resources</a></H2> <ul> diff --git a/Doc/Manual/Sections.html b/Doc/Manual/Sections.html index b75706de5..547faf0cf 100644 --- a/Doc/Manual/Sections.html +++ b/Doc/Manual/Sections.html @@ -30,6 +30,7 @@ Last update : SWIG-4.0.0 (in progress) <li><a href="Customization.html#Customization">Customization features</a></li> <li><a href="Contract.html#Contract">Contracts</a></li> <li><a href="Varargs.html#Varargs">Variable length arguments</a></li> +<li><a href="Doxygen.html#Doxygen">Doxygen documentation comments</a></li> <li><a href="Warnings.html#Warnings">Warning messages</a></li> <li><a href="Modules.html#Modules">Working with Modules</a></li> <li><a href="CCache.html#CCache">Using SWIG with ccache</a></li> diff --git a/Doc/Manual/Tcl.html b/Doc/Manual/Tcl.html index b6a7edcd4..7e7cd5f87 100644 --- a/Doc/Manual/Tcl.html +++ b/Doc/Manual/Tcl.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Tcl">41 SWIG and Tcl</a></H1> +<H1><a name="Tcl">42 SWIG and Tcl</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -84,7 +84,7 @@ Tcl 8.0 or a later release. Earlier releases of SWIG supported Tcl 7.x, but this is no longer supported. </p> -<H2><a name="Tcl_nn2">41.1 Preliminaries</a></H2> +<H2><a name="Tcl_nn2">42.1 Preliminaries</a></H2> <p> @@ -110,7 +110,7 @@ build a Tcl extension module. To finish building the module, you need to compile this file and link it with the rest of your program. </p> -<H3><a name="Tcl_nn3">41.1.1 Getting the right header files</a></H3> +<H3><a name="Tcl_nn3">42.1.1 Getting the right header files</a></H3> <p> @@ -128,7 +128,7 @@ this is the case, you should probably make a symbolic link so that <tt>tcl.h</tt header file. </p> -<H3><a name="Tcl_nn4">41.1.2 Compiling a dynamic module</a></H3> +<H3><a name="Tcl_nn4">42.1.2 Compiling a dynamic module</a></H3> <p> @@ -164,7 +164,7 @@ The name of the module is specified using the <tt>%module</tt> directive or the <tt>-module</tt> command line option. </p> -<H3><a name="Tcl_nn5">41.1.3 Static linking</a></H3> +<H3><a name="Tcl_nn5">42.1.3 Static linking</a></H3> <p> @@ -230,7 +230,7 @@ minimal in most situations (and quite frankly not worth the extra hassle in the opinion of this author). </p> -<H3><a name="Tcl_nn6">41.1.4 Using your module</a></H3> +<H3><a name="Tcl_nn6">42.1.4 Using your module</a></H3> <p> @@ -358,7 +358,7 @@ to the default system configuration (this requires root access and you will need the man pages). </p> -<H3><a name="Tcl_nn7">41.1.5 Compilation of C++ extensions</a></H3> +<H3><a name="Tcl_nn7">42.1.5 Compilation of C++ extensions</a></H3> <p> @@ -441,7 +441,7 @@ erratic program behavior. If working with lots of software components, you might want to investigate using a more formal standard such as COM. </p> -<H3><a name="Tcl_nn8">41.1.6 Compiling for 64-bit platforms</a></H3> +<H3><a name="Tcl_nn8">42.1.6 Compiling for 64-bit platforms</a></H3> <p> @@ -468,7 +468,7 @@ also introduce problems on platforms that support more than one linking standard (e.g., -o32 and -n32 on Irix). </p> -<H3><a name="Tcl_nn9">41.1.7 Setting a package prefix</a></H3> +<H3><a name="Tcl_nn9">42.1.7 Setting a package prefix</a></H3> <p> @@ -487,7 +487,7 @@ option will append the prefix to the name when creating a command and call it "<tt>Foo_bar</tt>". </p> -<H3><a name="Tcl_nn10">41.1.8 Using namespaces</a></H3> +<H3><a name="Tcl_nn10">42.1.8 Using namespaces</a></H3> <p> @@ -509,7 +509,7 @@ When the <tt>-namespace</tt> option is used, objects in the module are always accessed with the namespace name such as <tt>Foo::bar</tt>. </p> -<H2><a name="Tcl_nn11">41.2 Building Tcl/Tk Extensions under Windows 95/NT</a></H2> +<H2><a name="Tcl_nn11">42.2 Building Tcl/Tk Extensions under Windows 95/NT</a></H2> <p> @@ -520,7 +520,7 @@ covers the process of using SWIG with Microsoft Visual C++. although the procedure may be similar with other compilers. </p> -<H3><a name="Tcl_nn12">41.2.1 Running SWIG from Developer Studio</a></H3> +<H3><a name="Tcl_nn12">42.2.1 Running SWIG from Developer Studio</a></H3> <p> @@ -578,7 +578,7 @@ MSDOS > tclsh80 % </pre></div> -<H3><a name="Tcl_nn13">41.2.2 Using NMAKE</a></H3> +<H3><a name="Tcl_nn13">42.2.2 Using NMAKE</a></H3> <p> @@ -641,7 +641,7 @@ to get you started. With a little practice, you'll be making lots of Tcl extensions. </p> -<H2><a name="Tcl_nn14">41.3 A tour of basic C/C++ wrapping</a></H2> +<H2><a name="Tcl_nn14">42.3 A tour of basic C/C++ wrapping</a></H2> <p> @@ -652,7 +652,7 @@ classes. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Tcl_nn15">41.3.1 Modules</a></H3> +<H3><a name="Tcl_nn15">42.3.1 Modules</a></H3> <p> @@ -686,7 +686,7 @@ To fix this, supply an extra argument to <tt>load</tt> like this: </pre> </div> -<H3><a name="Tcl_nn16">41.3.2 Functions</a></H3> +<H3><a name="Tcl_nn16">42.3.2 Functions</a></H3> <p> @@ -711,7 +711,7 @@ like you think it does: % </pre></div> -<H3><a name="Tcl_nn17">41.3.3 Global variables</a></H3> +<H3><a name="Tcl_nn17">42.3.3 Global variables</a></H3> <p> @@ -791,7 +791,7 @@ extern char *path; // Read-only (due to %immutable) </pre> </div> -<H3><a name="Tcl_nn18">41.3.4 Constants and enums</a></H3> +<H3><a name="Tcl_nn18">42.3.4 Constants and enums</a></H3> <p> @@ -875,7 +875,7 @@ When an identifier name is given, it is used to perform an implicit hash-table l conversion. This allows the <tt>global</tt> statement to be omitted. </p> -<H3><a name="Tcl_nn19">41.3.5 Pointers</a></H3> +<H3><a name="Tcl_nn19">42.3.5 Pointers</a></H3> <p> @@ -971,7 +971,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return <tt>None</tt> if the conversion can't be performed. </p> -<H3><a name="Tcl_nn20">41.3.6 Structures</a></H3> +<H3><a name="Tcl_nn20">42.3.6 Structures</a></H3> <p> @@ -1253,7 +1253,7 @@ Note: Tcl only destroys the underlying object if it has ownership. See the memory management section that appears shortly. </p> -<H3><a name="Tcl_nn21">41.3.7 C++ classes</a></H3> +<H3><a name="Tcl_nn21">42.3.7 C++ classes</a></H3> <p> @@ -1319,7 +1319,7 @@ In Tcl, the static member is accessed as follows: </pre> </div> -<H3><a name="Tcl_nn22">41.3.8 C++ inheritance</a></H3> +<H3><a name="Tcl_nn22">42.3.8 C++ inheritance</a></H3> <p> @@ -1368,7 +1368,7 @@ For instance: It is safe to use multiple inheritance with SWIG. </p> -<H3><a name="Tcl_nn23">41.3.9 Pointers, references, values, and arrays</a></H3> +<H3><a name="Tcl_nn23">42.3.9 Pointers, references, values, and arrays</a></H3> <p> @@ -1422,7 +1422,7 @@ to hold the result and a pointer is returned (Tcl will release this memory when the return value is garbage collected). </p> -<H3><a name="Tcl_nn24">41.3.10 C++ overloaded functions</a></H3> +<H3><a name="Tcl_nn24">42.3.10 C++ overloaded functions</a></H3> <p> @@ -1545,7 +1545,7 @@ first declaration takes precedence. Please refer to the "SWIG and C++" chapter for more information about overloading. </p> -<H3><a name="Tcl_nn25">41.3.11 C++ operators</a></H3> +<H3><a name="Tcl_nn25">42.3.11 C++ operators</a></H3> <p> @@ -1647,7 +1647,7 @@ There are ways to make this operator appear as part of the class using the <tt>% Keep reading. </p> -<H3><a name="Tcl_nn26">41.3.12 C++ namespaces</a></H3> +<H3><a name="Tcl_nn26">42.3.12 C++ namespaces</a></H3> <p> @@ -1711,7 +1711,7 @@ utilizes thousands of small deeply nested namespaces each with identical symbol names, well, then you get what you deserve. </p> -<H3><a name="Tcl_nn27">41.3.13 C++ templates</a></H3> +<H3><a name="Tcl_nn27">42.3.13 C++ templates</a></H3> <p> @@ -1763,7 +1763,7 @@ More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</ examples will appear later. </p> -<H3><a name="Tcl_nn28">41.3.14 C++ Smart Pointers</a></H3> +<H3><a name="Tcl_nn28">42.3.14 C++ Smart Pointers</a></H3> <p> @@ -1847,7 +1847,7 @@ simply use the <tt>__deref__()</tt> method. For example: </pre> </div> -<H2><a name="Tcl_nn29">41.4 Further details on the Tcl class interface</a></H2> +<H2><a name="Tcl_nn29">42.4 Further details on the Tcl class interface</a></H2> <p> @@ -1860,7 +1860,7 @@ of low-level details were omitted. This section provides a brief overview of how the proxy classes work. </p> -<H3><a name="Tcl_nn30">41.4.1 Proxy classes</a></H3> +<H3><a name="Tcl_nn30">42.4.1 Proxy classes</a></H3> <p> @@ -1925,7 +1925,7 @@ function. This allows objects to be encapsulated objects that look a lot like as shown in the last section. </p> -<H3><a name="Tcl_nn31">41.4.2 Memory management</a></H3> +<H3><a name="Tcl_nn31">42.4.2 Memory management</a></H3> <p> @@ -2113,7 +2113,7 @@ typemaps--an advanced topic discussed later. </p> -<H2><a name="Tcl_nn32">41.5 Input and output parameters</a></H2> +<H2><a name="Tcl_nn32">42.5 Input and output parameters</a></H2> <p> @@ -2301,7 +2301,7 @@ set c [lindex $dim 1] </pre> </div> -<H2><a name="Tcl_nn33">41.6 Exception handling </a></H2> +<H2><a name="Tcl_nn33">42.6 Exception handling </a></H2> <p> @@ -2435,7 +2435,7 @@ Since SWIG's exception handling is user-definable, you are not limited to C++ ex See the chapter on "<a href="Customization.html#Customization">Customization Features</a>" for more examples. </p> -<H2><a name="Tcl_nn34">41.7 Typemaps</a></H2> +<H2><a name="Tcl_nn34">42.7 Typemaps</a></H2> <p> @@ -2452,7 +2452,7 @@ Typemaps are only used if you want to change some aspect of the primitive C-Tcl interface. </p> -<H3><a name="Tcl_nn35">41.7.1 What is a typemap?</a></H3> +<H3><a name="Tcl_nn35">42.7.1 What is a typemap?</a></H3> <p> @@ -2572,7 +2572,7 @@ parameter is omitted): </pre> </div> -<H3><a name="Tcl_nn36">41.7.2 Tcl typemaps</a></H3> +<H3><a name="Tcl_nn36">42.7.2 Tcl typemaps</a></H3> <p> @@ -2710,7 +2710,7 @@ Initialize an argument to a value before any conversions occur. Examples of these methods will appear shortly. </p> -<H3><a name="Tcl_nn37">41.7.3 Typemap variables</a></H3> +<H3><a name="Tcl_nn37">42.7.3 Typemap variables</a></H3> <p> @@ -2781,7 +2781,7 @@ properly assigned. The Tcl name of the wrapper function being created. </div> -<H3><a name="Tcl_nn38">41.7.4 Converting a Tcl list to a char ** </a></H3> +<H3><a name="Tcl_nn38">42.7.4 Converting a Tcl list to a char ** </a></H3> <p> @@ -2843,7 +2843,7 @@ argv[2] = Larry 3 </pre></div> -<H3><a name="Tcl_nn39">41.7.5 Returning values in arguments</a></H3> +<H3><a name="Tcl_nn39">42.7.5 Returning values in arguments</a></H3> <p> @@ -2885,7 +2885,7 @@ result, a Tcl function using these typemaps will work like this : % </pre></div> -<H3><a name="Tcl_nn40">41.7.6 Useful functions</a></H3> +<H3><a name="Tcl_nn40">42.7.6 Useful functions</a></H3> <p> @@ -2961,7 +2961,7 @@ int Tcl_IsShared(Tcl_Obj *obj); </pre> </div> -<H3><a name="Tcl_nn41">41.7.7 Standard typemaps</a></H3> +<H3><a name="Tcl_nn41">42.7.7 Standard typemaps</a></H3> <p> @@ -3045,7 +3045,7 @@ work) </pre> </div> -<H3><a name="Tcl_nn42">41.7.8 Pointer handling</a></H3> +<H3><a name="Tcl_nn42">42.7.8 Pointer handling</a></H3> <p> @@ -3127,7 +3127,7 @@ For example: </pre> </div> -<H2><a name="Tcl_nn43">41.8 Turning a SWIG module into a Tcl Package.</a></H2> +<H2><a name="Tcl_nn43">42.8 Turning a SWIG module into a Tcl Package.</a></H2> <p> @@ -3199,7 +3199,7 @@ As a final note, most SWIG examples do not yet use the to use the <tt>load</tt> command instead. </p> -<H2><a name="Tcl_nn44">41.9 Building new kinds of Tcl interfaces (in Tcl)</a></H2> +<H2><a name="Tcl_nn44">42.9 Building new kinds of Tcl interfaces (in Tcl)</a></H2> <p> @@ -3298,7 +3298,7 @@ danger of blowing something up (although it is easily accomplished with an out of bounds array access). </p> -<H3><a name="Tcl_nn45">41.9.1 Proxy classes</a></H3> +<H3><a name="Tcl_nn45">42.9.1 Proxy classes</a></H3> <p> @@ -3419,7 +3419,7 @@ short, but clever Tcl script can be combined with SWIG to do many interesting things. </p> -<H2><a name="Tcl_nn46">41.10 Tcl/Tk Stubs</a></H2> +<H2><a name="Tcl_nn46">42.10 Tcl/Tk Stubs</a></H2> <p> diff --git a/Doc/Manual/Warnings.html b/Doc/Manual/Warnings.html index 75ca11561..853ab691e 100644 --- a/Doc/Manual/Warnings.html +++ b/Doc/Manual/Warnings.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Warnings">16 Warning Messages</a></H1> +<H1><a name="Warnings">17 Warning Messages</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -36,7 +36,7 @@ -<H2><a name="Warnings_nn2">16.1 Introduction</a></H2> +<H2><a name="Warnings_nn2">17.1 Introduction</a></H2> <p> @@ -56,7 +56,7 @@ where the generated wrapper code will probably compile, but it may not work like you expect. </p> -<H2><a name="Warnings_suppression">16.2 Warning message suppression</a></H2> +<H2><a name="Warnings_suppression">17.2 Warning message suppression</a></H2> <p> @@ -148,7 +148,7 @@ your interface. Ignore the warning messages at your own peril. </p> -<H2><a name="Warnings_nn4">16.3 Enabling extra warnings</a></H2> +<H2><a name="Warnings_nn4">17.3 Enabling extra warnings</a></H2> <p> @@ -221,7 +221,7 @@ that is, any warnings suppressed or added in <tt>%warnfilter</tt>, <tt>#pragma S or the <tt>-w</tt> option. </p> -<H2><a name="Warnings_nn5">16.4 Issuing a warning message</a></H2> +<H2><a name="Warnings_nn5">17.4 Issuing a warning message</a></H2> <p> @@ -275,7 +275,7 @@ example.i:24: Warning 901: You are really going to regret this usage of blah * s </pre> </div> -<H2><a name="Warnings_symbolic_symbols">16.5 Symbolic symbols</a></H2> +<H2><a name="Warnings_symbolic_symbols">17.5 Symbolic symbols</a></H2> <p> @@ -310,7 +310,7 @@ or </pre> </div> -<H2><a name="Warnings_nn6">16.6 Commentary</a></H2> +<H2><a name="Warnings_nn6">17.6 Commentary</a></H2> <p> @@ -327,7 +327,7 @@ no obvious recovery. There is no mechanism for suppressing error messages. </p> -<H2><a name="Warnings_nn7">16.7 Warnings as errors</a></H2> +<H2><a name="Warnings_nn7">17.7 Warnings as errors</a></H2> <p> @@ -336,7 +336,7 @@ option. This will cause SWIG to exit with a non successful exit code if a warning is encountered. </p> -<H2><a name="Warnings_nn8">16.8 Message output format</a></H2> +<H2><a name="Warnings_nn8">17.8 Message output format</a></H2> <p> @@ -355,10 +355,10 @@ $ swig -python -Fmicrosoft example.i example.i(4) : Syntax error in input(1). </pre></div> -<H2><a name="Warnings_nn9">16.9 Warning number reference</a></H2> +<H2><a name="Warnings_nn9">17.9 Warning number reference</a></H2> -<H3><a name="Warnings_nn10">16.9.1 Deprecated features (100-199)</a></H3> +<H3><a name="Warnings_nn10">17.9.1 Deprecated features (100-199)</a></H3> <ul> @@ -386,7 +386,7 @@ example.i(4) : Syntax error in input(1). <li>126. The 'nestedworkaround' feature is deprecated. </ul> -<H3><a name="Warnings_nn11">16.9.2 Preprocessor (200-299)</a></H3> +<H3><a name="Warnings_nn11">17.9.2 Preprocessor (200-299)</a></H3> <ul> @@ -398,7 +398,7 @@ example.i(4) : Syntax error in input(1). <li>206. Unexpected tokens after #<em>directive</em> directive. </ul> -<H3><a name="Warnings_nn12">16.9.3 C/C++ Parser (300-399)</a></H3> +<H3><a name="Warnings_nn12">17.9.3 C/C++ Parser (300-399)</a></H3> <ul> @@ -475,7 +475,7 @@ example.i(4) : Syntax error in input(1). <li>395. operator delete[] ignored. </ul> -<H3><a name="Warnings_nn13">16.9.4 Types and typemaps (400-499) </a></H3> +<H3><a name="Warnings_nn13">17.9.4 Types and typemaps (400-499) </a></H3> <ul> @@ -506,7 +506,7 @@ example.i(4) : Syntax error in input(1). -<H3><a name="Warnings_nn14">16.9.5 Code generation (500-599)</a></H3> +<H3><a name="Warnings_nn14">17.9.5 Code generation (500-559)</a></H3> <ul> @@ -535,7 +535,17 @@ example.i(4) : Syntax error in input(1). <li>523. Use of an illegal destructor name '<em>name</em>' in %extend is deprecated, the destructor name should be '<em>name</em>'. </ul> -<H3><a name="Warnings_nn15">16.9.6 Language module specific (700-899) </a></H3> +<H3><a name="Warnings_doxygen">Doxygen comments (560-599)</a></H3> + +<ul> + <li>560: Unknown Doxygen command: <em>command</em>.</li> + <li>561: Unexpected end of Doxygen comment encountered.</li> + <li>562: Expected Doxygen command: <em>command</em></li> + <li>563: Doxygen HTML error for tag <em>tag</em>: <em>error text</em>.</li> + <li>564: Error parsing Doxygen command <em>command</em>: <em>error text</em>. Command ignored."</li> +</ul> + +<H3><a name="Warnings_nn15">17.9.6 Language module specific (700-899) </a></H3> <ul> @@ -586,14 +596,14 @@ example.i(4) : Syntax error in input(1). <li>871. Unrecognized pragma <em>pragma</em>. (Php). </ul> -<H3><a name="Warnings_nn16">16.9.7 User defined (900-999)</a></H3> +<H3><a name="Warnings_nn16">17.9.7 User defined (900-999)</a></H3> <p> These numbers can be used by your own application. </p> -<H2><a name="Warnings_nn17">16.10 History</a></H2> +<H2><a name="Warnings_nn17">17.10 History</a></H2> <p> diff --git a/Doc/Manual/chapters b/Doc/Manual/chapters index 41ecc9c57..056f6136c 100644 --- a/Doc/Manual/chapters +++ b/Doc/Manual/chapters @@ -13,6 +13,7 @@ Typemaps.html Customization.html Contract.html Varargs.html +Doxygen.html Warnings.html Modules.html CCache.html diff --git a/Doc/Manual/makechap.py b/Doc/Manual/makechap.py index 61994e2a0..e30d14e0f 100644 --- a/Doc/Manual/makechap.py +++ b/Doc/Manual/makechap.py @@ -44,6 +44,8 @@ def getheadingname(m): def getheadingtext(m, s): prevheadingtext_newstyle = m.group(2) prevheadingtext_oldstyle = m.group(3) + if prevheadingtext_oldstyle is None or prevheadingtext_newstyle is None: + raise RuntimeError("Ill-formed heading in line:\n%s" % s) if len(prevheadingtext_oldstyle) == 0 and len(prevheadingtext_newstyle) == 0: raise RuntimeError("No heading text in line:\n%s" % s) if len(prevheadingtext_oldstyle) > 0 and len(prevheadingtext_newstyle) > 0: @@ -72,7 +74,7 @@ name = "" # Regexs for <h1>,... <h5> sections -h1 = re.compile(r".*?<H1>(<a.*?>\s*[\d\s]*(.*?)</a>)*[\d\s]*(.*?)</H1>", re.IGNORECASE) +h1 = re.compile(r".*?<H1>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H1>", re.IGNORECASE) h2 = re.compile(r".*?<H2>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H2>", re.IGNORECASE) h3 = re.compile(r".*?<H3>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H3>", re.IGNORECASE) h4 = re.compile(r".*?<H4>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H4>", re.IGNORECASE) diff --git a/Examples/Makefile.in b/Examples/Makefile.in index 3f07aed29..ab4941252 100644 --- a/Examples/Makefile.in +++ b/Examples/Makefile.in @@ -630,6 +630,7 @@ java_run: java_version: $(JAVA) -version $(JAVAC) -version || echo "Unknown javac version" + echo "JAVA_HOME=\"$(JAVA_HOME)\"" # ----------------------------------------------------------------- # Cleaning the java examples diff --git a/Examples/java/check.list b/Examples/java/check.list index 825d04a6d..c30550a1c 100644 --- a/Examples/java/check.list +++ b/Examples/java/check.list @@ -2,6 +2,7 @@ callback class constants +doxygen enum extend funcptr diff --git a/Examples/java/doxygen/Makefile b/Examples/java/doxygen/Makefile new file mode 100644 index 000000000..9f471746e --- /dev/null +++ b/Examples/java/doxygen/Makefile @@ -0,0 +1,21 @@ +TOP = ../.. +SWIGEXE = $(TOP)/../swig +SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib +CXXSRCS = example.cxx +TARGET = example +INTERFACE = example.i +SWIGOPT = -doxygen +JAVASRCS = *.java + +check: build + $(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' java_run + +build: + $(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(CXXSRCS)' \ + SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \ + SWIGOPT='$(SWIGOPT)' TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' java_cpp + $(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' JAVASRCS='$(JAVASRCS)' JAVAFLAGS='$(JAVAFLAGS)' java_compile + +clean: + $(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' java_clean + rm -rf javadocs diff --git a/Examples/java/doxygen/example.cxx b/Examples/java/doxygen/example.cxx new file mode 100644 index 000000000..ccdb87dfe --- /dev/null +++ b/Examples/java/doxygen/example.cxx @@ -0,0 +1,48 @@ +/* File : example.cxx */ + +#include "example.h" +#define M_PI 3.14159265358979323846 + +/* Move the shape to a new location */ +void Shape::move(double dx, double dy) { + x += dx; + y += dy; +} + +int Shape::nshapes = 0; + +Circle::Circle(double r) : radius(r) { + NumCircles++; +} + +double Circle::area() { + return M_PI*radius*radius; +} + +double Circle::perimeter() { + return 2*M_PI*radius; +} + +Square::Square(double w) : width(w) { + NumSquares++; +} + +double Square::area() { + return width*width; +} + +double Square::perimeter() { + return 4*width; +} + +int NumSquares = 0; +int NumCircles = 0; + +Square MakeSquare(double r) { + return Square(r); +} + +Circle MakeCircle(double w) { + return Circle(w); +} + diff --git a/Examples/java/doxygen/example.dsp b/Examples/java/doxygen/example.dsp new file mode 100644 index 000000000..f52544b95 --- /dev/null +++ b/Examples/java/doxygen/example.dsp @@ -0,0 +1,162 @@ +# Microsoft Developer Studio Project File - Name="example" - Package Owner=<4>
+# Microsoft Developer Studio Generated Build File, Format Version 6.00
+# ** DO NOT EDIT **
+
+# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102
+
+CFG=example - Win32 Release
+!MESSAGE This is not a valid makefile. To build this project using NMAKE,
+!MESSAGE use the Export Makefile command and run
+!MESSAGE
+!MESSAGE NMAKE /f "example.mak".
+!MESSAGE
+!MESSAGE You can specify a configuration when running NMAKE
+!MESSAGE by defining the macro CFG on the command line. For example:
+!MESSAGE
+!MESSAGE NMAKE /f "example.mak" CFG="example - Win32 Release"
+!MESSAGE
+!MESSAGE Possible choices for configuration are:
+!MESSAGE
+!MESSAGE "example - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE "example - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE
+
+# Begin Project
+# PROP AllowPerConfigDependencies 0
+# PROP Scc_ProjName ""
+# PROP Scc_LocalPath ""
+CPP=cl.exe
+MTL=midl.exe
+RSC=rc.exe
+
+!IF "$(CFG)" == "example - Win32 Debug"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 1
+# PROP BASE Output_Dir "Debug"
+# PROP BASE Intermediate_Dir "Debug"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 1
+# PROP Output_Dir "Debug"
+# PROP Intermediate_Dir "Debug"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /I "$(JAVA_INCLUDE)" /I "$(JAVA_INCLUDE)\win32" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "_DEBUG"
+# ADD RSC /l 0x809 /d "_DEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /pdbtype:sept
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /out:"example.dll" /pdbtype:sept
+# Begin Special Build Tool
+SOURCE="$(InputPath)"
+PostBuild_Desc=Java compile post-build step
+PostBuild_Cmds=echo on "%JAVA_BIN%\javac" *.java
+# End Special Build Tool
+
+!ELSEIF "$(CFG)" == "example - Win32 Release"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 0
+# PROP BASE Output_Dir "Release"
+# PROP BASE Intermediate_Dir "Release"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 0
+# PROP Output_Dir "Release"
+# PROP Intermediate_Dir "Release"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD CPP /nologo /MT /W3 /GX /O2 /I "$(JAVA_INCLUDE)" /I "$(JAVA_INCLUDE)\win32" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "NDEBUG"
+# ADD RSC /l 0x809 /d "NDEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386 /out:"example.dll"
+# Begin Special Build Tool
+SOURCE="$(InputPath)"
+PostBuild_Desc=Java compile post-build step
+PostBuild_Cmds=echo on "%JAVA_BIN%\javac" *.java
+# End Special Build Tool
+
+!ENDIF
+
+# Begin Target
+
+# Name "example - Win32 Debug"
+# Name "example - Win32 Release"
+# Begin Group "Source Files"
+
+# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
+# Begin Source File
+
+SOURCE=.\example.cxx
+# End Source File
+# Begin Source File
+
+SOURCE=.\example_wrap.cxx
+# End Source File
+# End Group
+# Begin Group "Header Files"
+
+# PROP Default_Filter "h;hpp;hxx;hm;inl"
+# Begin Source File
+
+SOURCE=.\example.h
+# End Source File
+# End Group
+# Begin Group "Resource Files"
+
+# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe"
+# End Group
+# Begin Source File
+
+SOURCE=.\example.i
+
+!IF "$(CFG)" == "example - Win32 Debug"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+ echo In order to function correctly, please ensure the following environment variables are correctly set:
+ echo JAVA_INCLUDE: %JAVA_INCLUDE%
+ echo JAVA_BIN: %JAVA_BIN%
+ echo on
+ ..\..\..\swig.exe -c++ -java "$(InputPath)"
+
+# End Custom Build
+
+!ELSEIF "$(CFG)" == "example - Win32 Release"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+ echo In order to function correctly, please ensure the following environment variables are correctly set:
+ echo JAVA_INCLUDE: %JAVA_INCLUDE%
+ echo JAVA_BIN: %JAVA_BIN%
+ echo on
+ ..\..\..\swig.exe -c++ -java "$(InputPath)"
+
+# End Custom Build
+
+!ENDIF
+
+# End Source File
+# End Target
+# End Project
diff --git a/Examples/java/doxygen/example.h b/Examples/java/doxygen/example.h new file mode 100644 index 000000000..203348ae4 --- /dev/null +++ b/Examples/java/doxygen/example.h @@ -0,0 +1,107 @@ +/*! \file example.h +This file provides a simple set of Shape classes. */ + +/*! Base class for all shapes. + \author Bob + */ +class Shape { +public: + /*! Default constructor for creating a Shape */ + Shape() { + nshapes++; + } + /*! Destructor for destroying a Shape */ + virtual ~Shape() { + nshapes--; + } + double x; /*!< x co-ordinate */ + double y; /*!< y co-ordinate */ + void move(double dx, double dy); /*!< Move a shape to a new co-ordinate + \param dx x co-ordinate + \param dy y co-ordinate */ + virtual double area() = 0; /*!< \return the area */ + virtual double perimeter() = 0; /*!< \return the perimeter */ + static int nshapes; /*!< Number of shapes currently in existence */ +}; + +/*! A class for representing a circle. + \author Jack + */ +class Circle : public Shape { +private: + double radius; +public: + /*! Construct a circle + * \param r radius of the circle */ + Circle(double r); + /*! Calculate the area of the circle + * \return calculated area */ + virtual double area(); + /*! Calculate the perimeter of the circle + * \return calculated perimeter of the circle */ + virtual double perimeter(); +}; + +/// A class for representing a square. +class Square : public Shape { +private: + double width; +public: + /** Construct a square + * \param w width of the square */ + Square(double w); + /** Calculate the area of the square + * \return calculated area */ + virtual double area(); + /** Calculate the perimeter of the square + * \return calculated perimeter of the square */ + virtual double perimeter(); +}; + +/// A class for representing a rectangle, templated on the type for the rectangle dimensions +template<typename T> +class Rectangle : public Shape { +private: + T height; + T width; +public: + /** Construct a rectangle + * \param h height of the rectangle + * \param w width of the rectangle */ + Rectangle(T h, T w) : height(h), width(w) {} + /** Calculate the area of the rectangle + * \return calculated area */ + virtual double area() { return width*height; } + /** Calculate the perimeter of the rectangle + * \return calculated perimeter of the rectangle */ + virtual double perimeter() { return 2*height + 2*width; } +}; + + +/*! Factory function for creating a square + * \param r width of the square + * \return a fully constructed square */ +Square MakeSquare(double r); + +/*! Factory function for creating a circle + * \param w radius of the circle + * \return a fully constructed circle */ +Circle MakeCircle(double w); + +/*! Factory function for creating a rectangle + * \param h height of the rectangle + * \param w width of the rectangle + * \return a fully constructed rectangle */ +template<typename T> +Rectangle<T> MakeRectangle(T h, T w) { + return Rectangle<T>(h, w); +} + + + +/*! Total number of circles ever created */ +extern int NumCircles; + +/// Total number of squares ever created +extern int NumSquares; + diff --git a/Examples/java/doxygen/example.i b/Examples/java/doxygen/example.i new file mode 100644 index 000000000..803563dd9 --- /dev/null +++ b/Examples/java/doxygen/example.i @@ -0,0 +1,17 @@ +%module example + +%{ +#include "example.h" +%} + +%immutable NumSquares; +%immutable NumCircles; + +%include "example.h" + +/*! - this instantiation uses type int */ +%template(RectangleInt) Rectangle<int>; + +/*! - this instantiation uses type int */ +%template(MakeRectangleInt) MakeRectangle<int>; + diff --git a/Examples/java/doxygen/runme.java b/Examples/java/doxygen/runme.java new file mode 100644 index 000000000..6b7bb3d01 --- /dev/null +++ b/Examples/java/doxygen/runme.java @@ -0,0 +1,63 @@ +// This example shows simple usage of the wrapped Shape classes. +// The main purpose of this example is to show the doxygen comments translation to JavaDoc comments. +// Users should look at the generated .java files and if javadoc is installed and working on your system, +// the generated Java docs can be viewed in a browser by opening the javadocs/index.html file. + +import java.io.*; + +public class runme { + static { + try { + System.loadLibrary("example"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) throws InterruptedException, IOException + { + System.out.println("Creating some objects:"); + Circle c = example.MakeCircle(10); + System.out.println(" Created circle " + c); + Square s = example.MakeSquare(10); + System.out.println(" Created square " + s); + RectangleInt r = example.MakeRectangleInt(10, 20); + System.out.println(" Created rectangle " + r); + + System.out.println("\nHere are some properties of the shapes:"); + Shape[] shapes = {c, s, r}; + for (int i=0; i<shapes.length; i++) { + System.out.println(" " + shapes[i].toString()); + System.out.println(" area = " + shapes[i].area()); + System.out.println(" perimeter = " + shapes[i].perimeter()); + } + + String command = "javadoc -quiet -public -d javadocs example.java Shape.java Circle.java Square.java RectangleInt.java"; + System.out.println("\nRunning: " + command); + Process p = Runtime.getRuntime().exec(command); + int exitCode = p.waitFor(); + System.out.println("javadoc exited with code " + exitCode); + + BufferedReader stdout = new BufferedReader(new InputStreamReader(p.getInputStream())); + BufferedReader stderr = new BufferedReader(new InputStreamReader(p.getErrorStream())); + + String line = null; + + System.out.println("stdout from javadoc:\n"); + while ((line = stdout.readLine()) != null) { + System.out.println(line); + } + + System.out.println("\nstderr from javadoc:\n"); + while ((line = stderr.readLine()) != null) { + System.out.println(line); + } + + if (exitCode != 0) { + System.out.println("No java docs were generated!\n"); + } else { + System.out.println("javadoc ran successfully, open javadocs/index.html in your browser to view the generated java docs."); + } + } +} diff --git a/Examples/python/check.list b/Examples/python/check.list index 73182025d..0798b5f7e 100644 --- a/Examples/python/check.list +++ b/Examples/python/check.list @@ -4,6 +4,7 @@ class constants contract docstrings +doxygen enum exception exceptproxy diff --git a/Examples/python/doxygen/Makefile b/Examples/python/doxygen/Makefile new file mode 100644 index 000000000..1a0e3d7c5 --- /dev/null +++ b/Examples/python/doxygen/Makefile @@ -0,0 +1,27 @@ +TOP = ../.. +SWIGEXE = $(TOP)/../swig +SWIG_LIB_DIR = $(TOP)/../$(TOP_BUILDDIR_TO_TOP_SRCDIR)Lib +CXXSRCS = example.cxx +TARGET = example +INTERFACE = example.i +LIBS = -lm +SWIGOPT = -doxygen + +check: build + $(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' python_run + +build: + $(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(CXXSRCS)' \ + SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \ + SWIGOPT='$(SWIGOPT)' \ + TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' python_cpp + +static: + $(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' CXXSRCS='$(CXXSRCS)' \ + SWIG_LIB_DIR='$(SWIG_LIB_DIR)' SWIGEXE='$(SWIGEXE)' \ + SWIGOPT='$(SWIGOPT)' \ + TARGET='mypython' INTERFACE='$(INTERFACE)' python_cpp_static + +clean: + $(MAKE) -f $(TOP)/Makefile SRCDIR='$(SRCDIR)' TARGET='$(TARGET)' python_clean + rm -f example.html diff --git a/Examples/python/doxygen/example.cxx b/Examples/python/doxygen/example.cxx new file mode 100644 index 000000000..ccdb87dfe --- /dev/null +++ b/Examples/python/doxygen/example.cxx @@ -0,0 +1,48 @@ +/* File : example.cxx */ + +#include "example.h" +#define M_PI 3.14159265358979323846 + +/* Move the shape to a new location */ +void Shape::move(double dx, double dy) { + x += dx; + y += dy; +} + +int Shape::nshapes = 0; + +Circle::Circle(double r) : radius(r) { + NumCircles++; +} + +double Circle::area() { + return M_PI*radius*radius; +} + +double Circle::perimeter() { + return 2*M_PI*radius; +} + +Square::Square(double w) : width(w) { + NumSquares++; +} + +double Square::area() { + return width*width; +} + +double Square::perimeter() { + return 4*width; +} + +int NumSquares = 0; +int NumCircles = 0; + +Square MakeSquare(double r) { + return Square(r); +} + +Circle MakeCircle(double w) { + return Circle(w); +} + diff --git a/Examples/python/doxygen/example.dsp b/Examples/python/doxygen/example.dsp new file mode 100644 index 000000000..95ad8f173 --- /dev/null +++ b/Examples/python/doxygen/example.dsp @@ -0,0 +1,152 @@ +# Microsoft Developer Studio Project File - Name="example" - Package Owner=<4>
+# Microsoft Developer Studio Generated Build File, Format Version 6.00
+# ** DO NOT EDIT **
+
+# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102
+
+CFG=example - Win32 Release
+!MESSAGE This is not a valid makefile. To build this project using NMAKE,
+!MESSAGE use the Export Makefile command and run
+!MESSAGE
+!MESSAGE NMAKE /f "example.mak".
+!MESSAGE
+!MESSAGE You can specify a configuration when running NMAKE
+!MESSAGE by defining the macro CFG on the command line. For example:
+!MESSAGE
+!MESSAGE NMAKE /f "example.mak" CFG="example - Win32 Release"
+!MESSAGE
+!MESSAGE Possible choices for configuration are:
+!MESSAGE
+!MESSAGE "example - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE "example - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library")
+!MESSAGE
+
+# Begin Project
+# PROP AllowPerConfigDependencies 0
+# PROP Scc_ProjName ""
+# PROP Scc_LocalPath ""
+CPP=cl.exe
+MTL=midl.exe
+RSC=rc.exe
+
+!IF "$(CFG)" == "example - Win32 Debug"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 1
+# PROP BASE Output_Dir "Debug"
+# PROP BASE Intermediate_Dir "Debug"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 1
+# PROP Output_Dir "Debug"
+# PROP Intermediate_Dir "Debug"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /I "$(PYTHON_INCLUDE)" /D "SWIG_PYTHON_INTERPRETER_NO_DEBUG" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /GZ /c
+# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "_DEBUG"
+# ADD RSC /l 0x809 /d "_DEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /debug /machine:I386 /pdbtype:sept
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib "$(PYTHON_LIB)" /nologo /dll /debug /machine:I386 /out:"_example.pyd" /pdbtype:sept
+
+!ELSEIF "$(CFG)" == "example - Win32 Release"
+
+# PROP BASE Use_MFC 0
+# PROP BASE Use_Debug_Libraries 0
+# PROP BASE Output_Dir "Release"
+# PROP BASE Intermediate_Dir "Release"
+# PROP BASE Target_Dir ""
+# PROP Use_MFC 0
+# PROP Use_Debug_Libraries 0
+# PROP Output_Dir "Release"
+# PROP Intermediate_Dir "Release"
+# PROP Ignore_Export_Lib 0
+# PROP Target_Dir ""
+# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD CPP /nologo /MT /W3 /GX /O2 /I "$(PYTHON_INCLUDE)" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "EXAMPLE_EXPORTS" /YX /FD /c
+# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32
+# ADD BASE RSC /l 0x809 /d "NDEBUG"
+# ADD RSC /l 0x809 /d "NDEBUG"
+BSC32=bscmake.exe
+# ADD BASE BSC32 /nologo
+# ADD BSC32 /nologo
+LINK32=link.exe
+# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib /nologo /dll /machine:I386
+# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib "$(PYTHON_LIB)" /nologo /dll /machine:I386 /out:"_example.pyd"
+
+!ENDIF
+
+# Begin Target
+
+# Name "example - Win32 Debug"
+# Name "example - Win32 Release"
+# Begin Group "Source Files"
+
+# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
+# Begin Source File
+
+SOURCE=.\example.cxx
+# End Source File
+# Begin Source File
+
+SOURCE=.\example_wrap.cxx
+# End Source File
+# End Group
+# Begin Group "Header Files"
+
+# PROP Default_Filter "h;hpp;hxx;hm;inl"
+# Begin Source File
+
+SOURCE=.\example.h
+# End Source File
+# End Group
+# Begin Group "Resource Files"
+
+# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe"
+# End Group
+# Begin Source File
+
+SOURCE=.\example.i
+
+!IF "$(CFG)" == "example - Win32 Debug"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+ echo In order to function correctly, please ensure the following environment variables are correctly set:
+ echo PYTHON_INCLUDE: %PYTHON_INCLUDE%
+ echo PYTHON_LIB: %PYTHON_LIB%
+ echo on
+ ..\..\..\swig.exe -c++ -python "$(InputPath)"
+
+# End Custom Build
+
+!ELSEIF "$(CFG)" == "example - Win32 Release"
+
+# Begin Custom Build
+InputPath=.\example.i
+InputName=example
+
+"$(InputName)_wrap.cxx" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
+ echo In order to function correctly, please ensure the following environment variables are correctly set:
+ echo PYTHON_INCLUDE: %PYTHON_INCLUDE%
+ echo PYTHON_LIB: %PYTHON_LIB%
+ echo on
+ ..\..\..\swig.exe -c++ -python "$(InputPath)"
+
+# End Custom Build
+
+!ENDIF
+
+# End Source File
+# End Target
+# End Project
diff --git a/Examples/python/doxygen/example.h b/Examples/python/doxygen/example.h new file mode 100644 index 000000000..203348ae4 --- /dev/null +++ b/Examples/python/doxygen/example.h @@ -0,0 +1,107 @@ +/*! \file example.h +This file provides a simple set of Shape classes. */ + +/*! Base class for all shapes. + \author Bob + */ +class Shape { +public: + /*! Default constructor for creating a Shape */ + Shape() { + nshapes++; + } + /*! Destructor for destroying a Shape */ + virtual ~Shape() { + nshapes--; + } + double x; /*!< x co-ordinate */ + double y; /*!< y co-ordinate */ + void move(double dx, double dy); /*!< Move a shape to a new co-ordinate + \param dx x co-ordinate + \param dy y co-ordinate */ + virtual double area() = 0; /*!< \return the area */ + virtual double perimeter() = 0; /*!< \return the perimeter */ + static int nshapes; /*!< Number of shapes currently in existence */ +}; + +/*! A class for representing a circle. + \author Jack + */ +class Circle : public Shape { +private: + double radius; +public: + /*! Construct a circle + * \param r radius of the circle */ + Circle(double r); + /*! Calculate the area of the circle + * \return calculated area */ + virtual double area(); + /*! Calculate the perimeter of the circle + * \return calculated perimeter of the circle */ + virtual double perimeter(); +}; + +/// A class for representing a square. +class Square : public Shape { +private: + double width; +public: + /** Construct a square + * \param w width of the square */ + Square(double w); + /** Calculate the area of the square + * \return calculated area */ + virtual double area(); + /** Calculate the perimeter of the square + * \return calculated perimeter of the square */ + virtual double perimeter(); +}; + +/// A class for representing a rectangle, templated on the type for the rectangle dimensions +template<typename T> +class Rectangle : public Shape { +private: + T height; + T width; +public: + /** Construct a rectangle + * \param h height of the rectangle + * \param w width of the rectangle */ + Rectangle(T h, T w) : height(h), width(w) {} + /** Calculate the area of the rectangle + * \return calculated area */ + virtual double area() { return width*height; } + /** Calculate the perimeter of the rectangle + * \return calculated perimeter of the rectangle */ + virtual double perimeter() { return 2*height + 2*width; } +}; + + +/*! Factory function for creating a square + * \param r width of the square + * \return a fully constructed square */ +Square MakeSquare(double r); + +/*! Factory function for creating a circle + * \param w radius of the circle + * \return a fully constructed circle */ +Circle MakeCircle(double w); + +/*! Factory function for creating a rectangle + * \param h height of the rectangle + * \param w width of the rectangle + * \return a fully constructed rectangle */ +template<typename T> +Rectangle<T> MakeRectangle(T h, T w) { + return Rectangle<T>(h, w); +} + + + +/*! Total number of circles ever created */ +extern int NumCircles; + +/// Total number of squares ever created +extern int NumSquares; + diff --git a/Examples/python/doxygen/example.i b/Examples/python/doxygen/example.i new file mode 100644 index 000000000..803563dd9 --- /dev/null +++ b/Examples/python/doxygen/example.i @@ -0,0 +1,17 @@ +%module example + +%{ +#include "example.h" +%} + +%immutable NumSquares; +%immutable NumCircles; + +%include "example.h" + +/*! - this instantiation uses type int */ +%template(RectangleInt) Rectangle<int>; + +/*! - this instantiation uses type int */ +%template(MakeRectangleInt) MakeRectangle<int>; + diff --git a/Examples/python/doxygen/runme.py b/Examples/python/doxygen/runme.py new file mode 100644 index 000000000..e23528874 --- /dev/null +++ b/Examples/python/doxygen/runme.py @@ -0,0 +1,28 @@ +# This example shows simple usage of the wrapped Shape classes. +# The main purpose of this example is to show the doxygen comments translation to PyDoc comments. +# Users should look at the generated example.py file. +# The generated PyDoc can be viewed in a browser by opening the example.html file. + +import example + +print "Creating some objects:" +c = example.MakeCircle(10) +print " Created circle", c +s = example.MakeSquare(10) +print " Created square", s +r = example.MakeRectangleInt(10, 20) +print " Created rectangle", r + +print "\nHere are some properties of the shapes:" +for o in [c, s, r]: + print " ", o + print " area = ", o.area() + print " perimeter = ", o.perimeter() + +print "\nRunning pydoc, this is the equivalent to executing: pydoc -w ./example.py" + +import pydoc + +pydoc.writedoc("example") + +print "Open example.html in your browser to view the generated python docs" diff --git a/Examples/test-suite/common.mk b/Examples/test-suite/common.mk index 644355958..520c1bbfe 100644 --- a/Examples/test-suite/common.mk +++ b/Examples/test-suite/common.mk @@ -598,6 +598,30 @@ CPP11_TEST_BROKEN = \ # cpp11_variadic_templates \ # Broken for some languages (such as Java) # cpp11_reference_wrapper \ # No typemaps +# Doxygen support test cases: can only be used with languages supporting +# Doxygen comment translation, currently only Python and Java. +python_HAS_DOXYGEN := 1 +java_HAS_DOXYGEN := 1 + +$(eval HAS_DOXYGEN := $($(LANGUAGE)_HAS_DOXYGEN)) + +ifdef HAS_DOXYGEN +DOXYGEN_TEST_CASES += \ + doxygen_alias \ + doxygen_basic_notranslate \ + doxygen_basic_translate \ + doxygen_ignore \ + doxygen_misc_constructs \ + doxygen_parsing \ + doxygen_parsing_enums \ + doxygen_translate \ + doxygen_translate_all_tags \ + doxygen_translate_links \ + +$(DOXYGEN_TEST_CASES:=.cpptest): SWIGOPT += -doxygen + +CPP_TEST_CASES += $(DOXYGEN_TEST_CASES) +endif # # Put all the heavy STD/STL cases here, where they can be skipped if needed @@ -747,6 +771,10 @@ check-cpp: $(CPP_TEST_CASES:=.cpptest) check-cpp11: $(CPP11_TEST_CASES:=.cpptest) +ifdef HAS_DOXYGEN +check-doxygen: $(DOXYGEN_TEST_CASES:=.cpptest) +endif + check-failing-test = \ $(MAKE) -s $1.$2 >/dev/null 2>/dev/null && echo "Failing test $1 passed." diff --git a/Examples/test-suite/doxygen_alias.i b/Examples/test-suite/doxygen_alias.i new file mode 100644 index 000000000..79cb7964b --- /dev/null +++ b/Examples/test-suite/doxygen_alias.i @@ -0,0 +1,22 @@ +%module doxygen_alias + +#ifdef SWIGJAVA +%feature("doxygen:alias:nullptr") "null" +#elif defined(SWIGPYTHON) +%feature("doxygen:alias:nullptr") "None" +#else +%feature("doxygen:alias:nullptr") "NULL" +#endif + +%inline %{ + +class Something {}; + +/** + A function returning something. + + @returns A new object which may be @nullptr. + */ +Something* make_something() { return 0; } + +%} diff --git a/Examples/test-suite/doxygen_basic_notranslate.i b/Examples/test-suite/doxygen_basic_notranslate.i new file mode 100644 index 000000000..45e36c6e3 --- /dev/null +++ b/Examples/test-suite/doxygen_basic_notranslate.i @@ -0,0 +1,104 @@ +%module doxygen_basic_notranslate + +%include "doxygen_basic_translate.h" +%feature("doxygen:notranslate") function; +%feature("doxygen:notranslate") function2; +%feature("doxygen:notranslate") function3; +%feature("doxygen:notranslate") function4; +%feature("doxygen:notranslate") function5; +%feature("doxygen:notranslate") function6; +%feature("doxygen:notranslate") function7; + +%inline %{ + +/** + * \brief + * Brief description. + * + * The comment text + * \author Some author + * \return Some number + * \sa function2 + */ +int function() +{ + return 0; +} + +/** + * A test of a very very very very very very very very very very very very very very very very + * very very very very very long comment string. + */ +void function2() +{ +} + +/** + * A test for overloaded functions + * This is function \b one + */ +void function3(int a) +{ +} + +/** + * A test for overloaded functions + * This is function \b two + */ +void function3(int a, int b) +{ +} + +/** + * A test of some mixed tag usage + * \if CONDITION + * This \a code fragment shows us something \. + * \par Minuses: + * \arg it's senseless + * \arg it's stupid + * \arg it's null + * + * \warning This may not work as expected + * + * \code + * int main() { while(true); } + * \endcode + * \endif + */ +void function4() +{ +} + + +void function5(int a) +{ +} +/**< This is a post comment. */ + +/** + * Test for default args + * @param a Some parameter, default is 42 + */ +void function6(int a=42) +{ +} + +class Shape +{ +public: + typedef Shape* superType; +}; + +/** + * Test for a parameter with difficult type + * (mostly for python) + * @param a Very strange param + */ +void function7(Shape::superType *a[10]) +{ +} + +/** + * Comment at the end of file should be ignored. + */ +%} diff --git a/Examples/test-suite/doxygen_basic_translate.h b/Examples/test-suite/doxygen_basic_translate.h new file mode 100644 index 000000000..7b2b3f58a --- /dev/null +++ b/Examples/test-suite/doxygen_basic_translate.h @@ -0,0 +1,5 @@ + +/** + * This file contains only doxygen comment without a declaration - + * it should be ignored by SWIG and must not trigger syntax error. + */ diff --git a/Examples/test-suite/doxygen_basic_translate.i b/Examples/test-suite/doxygen_basic_translate.i new file mode 100644 index 000000000..0a8b0474f --- /dev/null +++ b/Examples/test-suite/doxygen_basic_translate.i @@ -0,0 +1,111 @@ +%module doxygen_basic_translate + +%include "doxygen_basic_translate.h" + +%inline %{ + +/** + * \brief + * Brief description. + * + * The comment text. + * + * \author Some author + * + * \return Some number + * + * \sa function2 + */ +int function() +{ + return 0; +} + +/** + * A test of a very very very very very very very very very very very very very very very very + * very very very very very long comment string. + */ +void function2() +{ +} + +/** + * A test for overloaded functions + * This is function \b one + */ +void function3(int a) +{ +} + +/** + * A test for overloaded functions + * This is function \b two + */ +void function3(int a, int b) +{ +} + +/** + * A test of some mixed tag usage + * \if CONDITION + * This \a code fragment shows us something \. + * \par Minuses: + * \arg it's senseless + * \arg it's stupid + * \arg it's null + * + * \warning This may not work as expected + * \code + * int main() { while(true); } + * \endcode + * \endif + */ +void function4() +{ +} + + +void function5(int a) +{ +} +/**< This is a post comment. */ + +/** + * Test for default args + * @param a Some parameter, default is 42 + */ +void function6(int a=42) +{ +} + +class Shape +{ +public: + typedef Shape* superType; +}; + +/** + * Test for a parameter with difficult type + * (mostly for python) + * @param a Very strange param + */ +void function7(Shape::superType *a[10]) +{ +} + +/** + Multiple parameters test. + + @param y Vertical coordinate. + @param x Horizontal coordinate. + @return Arc tangent of @c y/x. + */ +double Atan2(double y, double x) +{ + return 0; +} + +/** + * Comment at the end of file should be ignored. + */ +%} diff --git a/Examples/test-suite/doxygen_ignore.i b/Examples/test-suite/doxygen_ignore.i new file mode 100644 index 000000000..ce83470b6 --- /dev/null +++ b/Examples/test-suite/doxygen_ignore.i @@ -0,0 +1,41 @@ +%module doxygen_ignore + +%feature("doxygen:ignore:transferfull"); +%feature("doxygen:ignore:compileroptions", range="line"); +%feature("doxygen:ignore:forcpponly", range="end"); + +#ifdef SWIGJAVA +%feature("doxygen:ignore:beginJavaOnly", range="end:endJavaOnly", contents="parse"); +%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly"); +#elif defined(SWIGPYTHON) +%feature("doxygen:ignore:beginJavaOnly", range="end:endJavaOnly"); +%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse"); +#else +%feature("doxygen:ignore:beginJavaOnly", range="end:endJavaOnly"); +%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly"); +#endif + +%inline %{ + +/** + A contrived example of ignoring too many commands in one comment. + + @forcpponly + This is C++-specific. + @endforcpponly + + @beginJavaOnly + This is specific to @e Java. + @endJavaOnly + + @beginPythonOnly + This is specific to @b Python. + @endPythonOnly + + @transferfull Command ignored, but anything here is still included. + + @compileroptions This function must be compiled with /EHa when using MSVC. + */ +int * func() { } + +%} diff --git a/Examples/test-suite/doxygen_misc_constructs.h b/Examples/test-suite/doxygen_misc_constructs.h new file mode 100644 index 000000000..d677dc3d3 --- /dev/null +++ b/Examples/test-suite/doxygen_misc_constructs.h @@ -0,0 +1,94 @@ +/* + * This file contains comments which demonstrate details about Doxygen processing, + * so they can be emulated in SWIG doxy comment translation + */ + + + +/**This comment without space after '*' is valid in Doxygen. + * + */ +void isNoSpaceValidA() +{} + +/**.This comment without space after '*' is valid in Doxygen. + * + */ +void isNoSpaceValidB() +{} + + +/***This is not Doxygen comment. + * + */ +void isNoSpaceValidC() +{} + + +/** + * Backslash following\c word is a valid doxygen command. Output contains + * 'followingword' with 'word' in code font. + */ +void backslashA() +{} + +// Output of escaped symbols below in doxygen generated HTML: +// Rendered: Escaped symbols: $ @ \ & < > # % " \. :: @text ::text +// HTML source: Escaped symbols: $ @ \ & < > # % " \. :: @text ::text + + +/** + * Doxy command without trailing \cspace space is ignored - nothing appears + * on output. Standalone \ and '\' get to output. + * Standalone @ and '@' get to output. + * Commands "in quoted \b strings are treated as plain text". + * Commands not recognized by Doxygen \blah @blah are ignored. + * Backslashes in DOS paths d:\xyz\qwe\myfile and words + * following them do not appear on output, we must quote them with + * double quotes: "d:\xyz\qwe\myfile", "@something". Single quotes do not help: + * 'd:\xyz\qwe\myfile'. Escaping works: d:\\xyz\\qwe\\myfile. Unix + * paths of course have no such problems: /xyz/qwe/myfile + * Commands for escaped symbols: + * \$ \@ \\ \& \~ \< \> \# \% \" \. \:: \@text \::text + */ +void backslashB() +{} + +/** + * Backslash e at end of \e line froze SWIG \e + * with old comment parser. + * + * @see MyClass::fun(char, + * float) + */ +void backslashC() +{} + +/** + * The next line contains expression: + * <pre> + * ['retVal < 10', 'g_counter == 23 && g_mode & 3'] + *</pre> + * + * Both words should be emphasized \b isystem.connect. + * But not the last period. For \b example, comma should not be emphasized. + * Similar \b for: double colon. + * + * Spaces at the start of line should be taken into account: + * @param id used as prefix in log + * statements. The default value is empty string, which is OK if + * there is only one app. instance. Example: + * <pre> + * ctrl.setBP("func1"); + * </pre> + * If we set the id to \c main_, we get: + * <pre> + * main_ctrl.setBP("func1"); + * </pre> + * + * @param fileName name of the log file + */ +void cycle(int id, char *fileName) +{} + + diff --git a/Examples/test-suite/doxygen_misc_constructs.i b/Examples/test-suite/doxygen_misc_constructs.i new file mode 100644 index 000000000..461415316 --- /dev/null +++ b/Examples/test-suite/doxygen_misc_constructs.i @@ -0,0 +1,124 @@ +// This file contains tests for situations, which do not normally +// appear in the code, but must nevertheless be handled correctly. + +%module doxygen_misc_constructs + +%warnfilter(SWIGWARN_DOXYGEN_UNKNOWN_COMMAND) backslashB; + +%inline %{ + + // Tag '@endink' must be recognized even if it is not + // followed by whitespace. + + /** Tag endlink must be recognized also when followed by nonspace charater. + * + * @link Connection::getId() @endlink<br> */ + + char g_counter; + + + /** + Tag endlink must be recognized also when it is the last token + in the commment. + + @link Connection::getId() @endlink<br> + @link debugIdeTraceProfilerCoverageSample.py Python example. @endlink + */ + int g_zipCode; + + + // Paramter 'isReportSize' must appear in comment of the overload, which + // has it. Empty line before link must be preserved. + /** + * Returns address of file line. + * + * @param fileName name of the file, where the source line is located + * @param line line number + * @param isGetSize if set, for every object location both address and size are returned + * + * @link Connection::getId() @endlink <br> + */ + void getAddress(int &fileName, + int line, + bool isGetSize = false) {} + + // The first comment must be ignored. + /** + * \defgroup icFacade isystem.connect Facade + * + * This page shows the core classes, which can be used to control + * all aspects of winIDEA, for example: debugging, analyzers, IO module, ... + */ + + /** + * This class contains information for connection to winIDEA. Its methods + * return reference to self, so we can use it like this: + * <pre> + * CConnectionConfig config = new CConnectionConfig(); + * config.discoveryPort(5534).dllPath("C:\\myWinIDEA\\connect.dll").id("main"); + * </pre> + * + * All parameters are optional. Set only what is required, default values are + * used for unspecified parameters. + * <p> + * + * @link advancedWinIDEALaunching.py Python example.@endlink <br> + */ + class CConnectionConfig + { + }; + + // Text after '\c' must be kept unchanged in Python. + /** + * Determines how long the \c isystem.connect should wait for running + * instances to respond. Only one of \c lfWaitXXX flags from IConnect::ELaunchFlags + * may be specified. + */ + int waitTime(long waitTime) {return 33;} + + + // Line with tag \ingroup must not appear in translated comment: + /** \ingroup icFacade + * + * This function returns connection id. + */ + int getConnection() {return 3;} + + // the follwing must produce no comment in wrapper + /*******************************************************************/ + char getFirstLetter() {return 'a';} + + + /** + * Class description. + */ + class ClassWithNestedEnum { + public: + /** + * Enum description. + */ + typedef enum {ONE, ///< desc of one + TWO, ///< desc of two + THREE ///< desc of three + } ENested; + + }; + + /** + An example of a list in a documentation comment. + + - The first item of the list. + - The second list item, on + several indented lines, + showing that the indentation + is preserved. + - And the final list item after it. + + And this is not a list item any more. + */ + void showList() { } + + #include "doxygen_misc_constructs.h" + +%} + %include "doxygen_misc_constructs.h" diff --git a/Examples/test-suite/doxygen_parsing.i b/Examples/test-suite/doxygen_parsing.i new file mode 100644 index 000000000..670d8699b --- /dev/null +++ b/Examples/test-suite/doxygen_parsing.i @@ -0,0 +1,129 @@ +%module doxygen_parsing + +%inline %{ + +/** + * The class comment + */ +class SomeClass +{ +}; + +/** + * The function comment + */ +void someFunction() +{ +} + +/** + * The enum comment + */ +enum SomeEnum +{ + SOME_ENUM_ITEM +}; + +/** + * The struct comment + */ +struct SomeStruct +{ +}; + +/** + * The var comment + */ +int someVar=42; + +class SomeAnotherClass +{ +public: + /// First overloaded constructor. + SomeAnotherClass(int) { } + + /// Second overloaded constructor. + SomeAnotherClass(const char*) { } + + + /** + * The class attribute comment + */ + int classAttr; + + int classAttr2; ///< The class attribute post-comment + + int classAttr3; ///< The class attribute post-comment + //!< with details + + /** + * The class method comment. + * + * \link SomeAnotherClass#classMethodExtended(int, int) a link text \endlink + */ + void classMethod() + { + } + + /** + * The class method with parameter + */ + void classMethodExtended( + int a, ///< Parameter a + int b ///< Parameter b + ) + { + } + + /** + * The class method with parameter + * + * @param a Parameter a + * @param b Parameter b + */ + void classMethodExtended2(int a, int b) + { + } +}; + +struct SomeAnotherStruct +{ + /** + * The struct attribute comment + */ + int structAttr; + + int structAttr2; ///< The struct attribute post-comment + + int structAttr3; ///< The struct attribute post-comment + //!< with details + + /** + * The struct method comment + */ + void structMethod() + { + } + + /** + * The struct method with parameter + */ + void structMethodExtended( + int a, ///< Parameter a + int b ///< Parameter b + ) + { + } + + /** + * The struct method with parameter + * + * @param a Parameter a + * @param b Parameter b + */ + void structMethodExtended2(int a, int b) + { + } +}; + +%} diff --git a/Examples/test-suite/doxygen_parsing_enums.i b/Examples/test-suite/doxygen_parsing_enums.i new file mode 100644 index 000000000..5c48f4801 --- /dev/null +++ b/Examples/test-suite/doxygen_parsing_enums.i @@ -0,0 +1,35 @@ +%module doxygen_parsing_enums + +%inline %{ + + + /** + * Testing comments before enum items + */ + enum SomeAnotherEnum + { + /** + * The comment for the first item + */ + SOME_ITEM_1, + /** + * The comment for the second item + */ + SOME_ITEM_2, + /** + * The comment for the third item + */ + SOME_ITEM_3 + }; + + /** + * Testing comments after enum items + */ + enum SomeAnotherEnum2 + { + SOME_ITEM_10, ///< Post comment for the first item + SOME_ITEM_20, ///< Post comment for the second item + SOME_ITEM_30 ///< Post comment for the third item + }; + +%} diff --git a/Examples/test-suite/doxygen_parsing_enums_proper.i b/Examples/test-suite/doxygen_parsing_enums_proper.i new file mode 100644 index 000000000..1a69a84f1 --- /dev/null +++ b/Examples/test-suite/doxygen_parsing_enums_proper.i @@ -0,0 +1,7 @@ +%module "doxygen_parsing_enums_proper" + +// Test enum commenting using the proper enums in the target language +%include "enums.swg" + +%include "doxygen_parsing_enums.i" + diff --git a/Examples/test-suite/doxygen_parsing_enums_simple.i b/Examples/test-suite/doxygen_parsing_enums_simple.i new file mode 100644 index 000000000..823a27584 --- /dev/null +++ b/Examples/test-suite/doxygen_parsing_enums_simple.i @@ -0,0 +1,6 @@ +%module "doxygen_parsing_enums_simple" + +// Test enum commenting using simple constants (SWIG-1.3.21 and earlier default enum wrapping for C# and Java) +%include "enumsimple.swg" + +%include "doxygen_parsing_enums.i"
\ No newline at end of file diff --git a/Examples/test-suite/doxygen_parsing_enums_typesafe.i b/Examples/test-suite/doxygen_parsing_enums_typesafe.i new file mode 100644 index 000000000..25e355ee2 --- /dev/null +++ b/Examples/test-suite/doxygen_parsing_enums_typesafe.i @@ -0,0 +1,8 @@ +%module "doxygen_parsing_enums_typesafe" + +// Test enum commenting using the typesafe enum pattern in the target language +%include "enumtypesafe.swg" + +#define SWIG_TEST_NOCSCONST // For C# typesafe enums + +%include "doxygen_parsing_enums.i"
\ No newline at end of file diff --git a/Examples/test-suite/doxygen_parsing_enums_typeunsafe.i b/Examples/test-suite/doxygen_parsing_enums_typeunsafe.i new file mode 100644 index 000000000..e001035df --- /dev/null +++ b/Examples/test-suite/doxygen_parsing_enums_typeunsafe.i @@ -0,0 +1,6 @@ +%module "doxygen_parsing_enums_typeunsafe" + +// Test enum commenting using a type unsafe enum pattern (constant integers in a class for the enum type) +%include "enumtypeunsafe.swg" + +%include "doxygen_parsing_enums.i"
\ No newline at end of file diff --git a/Examples/test-suite/doxygen_translate.i b/Examples/test-suite/doxygen_translate.i new file mode 100644 index 000000000..348b2e9a8 --- /dev/null +++ b/Examples/test-suite/doxygen_translate.i @@ -0,0 +1,262 @@ +%module doxygen_translate + +%inline %{ + +/** + * \a Hello + * + * \arg some list item + * + * \authors lots of them + * + * \author Zubr + * + * \b boldword + * + * \c codeword + * + * \cite citationword + * + * \code some test code \endcode + * + * \cond SOMECONDITION + * Some conditional comment + * \endcond + * + * \copyright some copyright + * + * \deprecated Now use another function + * + * \e italicword + * + * \example someFile.txt + * Some details on using the example + * + * \exception SuperError + * + * \if ANOTHERCONDITION + * First part of comment + * \if SECONDCONDITION + * Nested condition text + * \elseif THIRDCONDITION + * The third condition text + * \else + * The last text block + * \endif + * \else + * Second part of comment + * \if CONDITION + * Second part extended + * \endif + * \endif + * + * \ifnot SOMECONDITION + * This is printed if not + * \endif + * + * \image html testImage.bmp "Hello, world!" width=10cm + * + * <ul> + * + * \li Some unordered list + * \li With lots of items + * \li lots of lots of items + * + * </ul> + * + * \link someMember Some description follows \endlink + * + * \n \n \n + * + * \note Here + * is the note! + * + * \overload + * + * \p someword + * + * \package superPackage + * + * \par The paragraph title + * The paragraph text. + * Maybe even multiline + * + * \param a the first param + * + * \remark Some remark text + * + * \remarks Another remarks section + * + * \result Whatever + * + * \return it + * + * \returns may return + * + * \sa someOtherMethod + * + * \see function + * + * \since version 0.0.0.1 + * + * \throw superException + * + * \throws RuntimeError + * + * \todo Some very important task + * + * \tparam b B is mentioned again... + * + * \verbatim + * very long + * text with tags <sometag> + * \endverbatim + * + * \version 0.0.0.2 + * + * \warning This is senseless! + * + * Here goes test of symbols: + * \$ \@ \\ \& \~ \< \> \# \% \" \. \:: + * + * And here goes simple text + */ +int function(int a, float b) +{ + return 0; +} + +/** + * Test for html tags. See Doxygen doc for list of tags recognized by Doxygen. + * + * <a href="http://acme.com/index.html">This is link</a> + * <b>bold</b> + * <BLOCKQUOTE cite="http://www.worldwildlife.org/who/index.html"> + * Quotation block. + * </BLOCKQUOTE> + * <br> + * <center>center</center> + * <code>this is code</code> + * + * <DL> + * <DT>Starts an item title.</DT> + * <DD>Starts an item description.</dd> + * </dl> + * + * <DFN>Starts a piece of text displayed in a typewriter font. + * </DFN> + * <DIV>Starts a section with a specific style (HTML only) + * </DIV> + * <EM>Starts a piece of text displayed in an italic font.</EM> + * + * <FORM>'Form' does not generate any output. + * </FORM> + * <HR> + * <H1>Heading 1 + * </H1> + * <H2>Heading 2 + * </H2> + * <H3>Heading 3 + * </H3> + * <I>Starts a piece of text displayed in an italic font.</I> + * <INPUT>Input tag. + * <IMG src="slika.png"> + * <META>Meta tag. + * <MULTICOL>Multicol is ignored by doxygen. + * </MULTICOL> + * + * <OL> + * <LI>List item 1.</LI> + * <LI>List item 2.</LI> + * </OL> + * + * <P>Starts a new paragraph. + * </P> + * <PRE>Starts a preformatted fragment. + * </PRE> + * <SMALL>Starts a section of text displayed in a smaller font. + * </SMALL> + * <SPAN>Starts an inline text fragment with a specific style.</SPAN> + * <STRONG>Starts a section of bold text.</STRONG> + * <SUB>Starts a piece of text displayed in subscript.</SUB> + * <SUP>Starts a piece of text displayed in superscript.</SUP> + * + * <table border = '1'> + * <caption>Animals</caption> + * <tr><th> Column 1 </th><th> Column 2 </th></tr> + * <tr><td> cow </td><td> dog </td></tr> + * <tr><td> cat </td><td> mouse </td></tr> + * <tr><td> horse </td><td> parrot </td></tr> + * </table> + * + * <TT>Starts a piece of text displayed in a typewriter font. + * </TT> + * <KBD>Starts a piece of text displayed in a typewriter font. + * </KBD> + * + * <UL> + * <LI>List item 1.</LI> + * <LI>List item 2.</LI> + * <LI>List item 3.</LI> + * </UL> + * + * <VAR>Starts a piece of text displayed in an italic font.</VAR> + * + * \htmlonly + * <u>underlined \b bold text - doxy commands are ignored inside 'htmlonly' section </u> + * \endhtmlonly + */ +void htmlFunction(int a, float b) +{ +} + +/** + * The meaning of flags: + * + * @param byFlags bits marking required items: + * <table> + * <tr><th> Size in bits</th><th> Items Required </th></tr> + * <tr><td> 1 - 8 </td><td> 1 </td></tr> + * <tr><td> 9 - 16 </td><td> 2 </td></tr> + * <tr><td> 17 - 32 </td><td> 4 </td></tr> + * </table> + * Almost all combinations of above flags are supported by + * \c htmlTable... functions. + */ +void htmlTableFunction(int byFlags) +{ +} + + +/** + * All entities are treated as commands © ™ ® + * should work also<in text + * > + * & + * ' + * " + * ‘ + * ’ + * “ + * ” + * – + * — + * + * × + * − + * ⋅ + * ∼ + * ≤ + * ≥ + * ← + * → + * Not an &text; html entity - ignored by Doxygen. + * Not an &text html entity - ampersand is replaced with entity. + */ +void htmlEntitiesFunction(int a, float b) +{ +} + + + +%} diff --git a/Examples/test-suite/doxygen_translate_all_tags.i b/Examples/test-suite/doxygen_translate_all_tags.i new file mode 100644 index 000000000..ba348fd50 --- /dev/null +++ b/Examples/test-suite/doxygen_translate_all_tags.i @@ -0,0 +1,399 @@ +%module doxygen_translate_all_tags + +%inline %{ + +/** + * \a Hello + * + * \addindex SomeLatexIndex + * + * \addtogroup someGroup "Some title" + * + * \anchor theAnchor + * + * \arg some list item + * + * \attention This is attention! + * You were warned! + * + * \authors lots of them + * \author Zubr + * + * \b boldword + * + * \brief Some brief description, + * extended to many lines. + * + * \bug Not everything works right now... + * \c codeword + * + * \callgraph + * \callergraph + * \category someCategory headerFile.h headerName + * + * \cite citationword + * \class someClass headerFile.h headerName + * \code some test code \endcode + */ +void func01(int a) +{ +} + + +/** + * \cond SOMECONDITION + * Some conditional comment + * \endcond + * + * \copybrief someClass::someMethod + * + * \copydetails someClass::someMethod2 + * + * \copydoc someClass::someMethod3 + * + * \copyright some copyright + * + * \date 1970 - 2012 + * + * \def someDefine + * + * \defgroup someGroup Some titles + * + * \deprecated Now use another function + * + * \details This is very large + * and detailed description of some thing + */ +void func02(int a) +{ +} + + +/** + * Comment for \b func03(). + * + * \dir /somePath/someFolder + * + * \dontinclude someFile.h + * + * \dot + * digraph example { + * node [shape=record, fontname=Helvetica, fontsize=10]; + * b [ label="class B" URL="\ref B"]; + * c [ label="class C" URL="\ref C"]; + * b -> c [ arrowhead="open", style="dashed" ]; + * } + * \enddot + * + * \dotfile dotFile.dot "The caption" + * + * \e italicword + * + * \em emphazedWord + * + * \enum someEnum + * + * \example someFile.txt + * Some details on using the example + */ +void func03(int a) +{ +} + + +/** + * + * \exception SuperError + * + * \extends someOtherFunction + * + * \f$ \sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \f$ + * + * \f[ + * \sqrt{(x_2-x_1)^2+(y_2-y_1)^2} + * \f] + * + * \f{ + * \sqrt{(x_2-x_1)^2+(y_2-y_1)^2} + * \f} + * + * \file file.h + * + * \fn someFn + * + * \headerfile someHeader.h "Header name" + * + * \hideinitializer + * + * \htmlinclude htmlFile.htm + * + * \htmlonly + * This will only appear in hmtl + * \endhtmlonly + */ +void func04(int a) +{ +} + + +/** + * \if ANOTHERCONDITION + * First part of comment + * \if SECONDCONDITION + * Nested condition text + * \elseif THIRDCONDITION + * The third condition text + * \else + * The last text block + * \endif + * \else + * Second part of comment + * \if CONDITION + * Second part extended + * \endif + * \endif + * + * \ifnot SOMECONDITION + * This is printed if not + * \endif + * + * \image html testImage.bmp "Hello, world!" asd=10qwe + * + * \implements someFunction + * + * \include header.h + * + * \includelineno header2.h + * + * \ingroup someGroup anotherGroup + * + * \internal + * + * \invariant Some text + * describing invariant. + */ +void func05(int a) +{ +} + + +/** + * Comment for \b func06(). + * + * \interface someInterface someHeader.h "Header name" + * + * \latexonly + * This will only appear in LATeX + * \endlatexonly + * + * <ul> + * + * \li Some unordered list + * \li With lots of items + * \li lots of lots of items + * + * </ul> + * + * \line example + * + * \link someMember Some description follows \endlink + * + * \mainpage Some title + * + * \manonly + * This will only appear in man + * \endmanonly + * + * \memberof someThing + * + * \msc + * Sender,Receiver; + * Sender->Receiver [label="Command()", URL="\ref Receiver::Command()"]; + * Sender<-Receiver [label="Ack()", URL="\ref Ack()", ID="1"]; + * \endmsc + * + * \mscfile mscFile.msc "The caption" + * + * \n \n \n + */ +void func06(int a) +{ +} + + +/** + * Comment for \b func07(). + * + * \name someHeader.h + * + * \namespace someNamespace + * + * \nosubgrouping + * + * \note Here + * is the note! + * + * \overload + * + * \p someword + * + * \package superPackage + * + * \page somePage The title + * + * \par The paragraph title + * The paragraph text. + * Maybe even multiline + * + * \paragraph someParagraph Paragraph title + * + * \param a the first param + * + * \post Some description + * + * \pre Some description + * + * \private + * + * \privatesection + * + * \property someVar + */ +void func07(int a) +{ +} + + +/** + * \protected + * + * \protectedsection + * + * \anchor someAnchor + * Text after anchor. + * \protocol someProtocol header.h "Header name" + * + * \public + * + * \publicsection + * + * \ref someAnchor "Anchor description" + * + * \ref someAnchor not quoted text is not part of ref tag + * + * \ref someAnchor + * + * \related toSomething + * + * \relates toSomethingElse + * + * \relatedalso someName + * + * \relatesalso someName + * + * \remark Some remark text + * + * \remarks Another remarks section + * + * \result Whatever + * + * \return it + * + * \returns may return + * + * \retval someValue Some description + */ +void func08(int a) +{ +} + + +/** + * \rtfonly + * This will only appear in RTF + * \endrtfonly + * + * \sa someOtherMethod + * + * \section someSection Some title + * + * \see function + * + * \short Same as + * brief description + * + * \showinitializer + * + * \since version 0.0.0.1 + * + * \skip somePattern + * + * \skipline someLine + * + * \snippet example.h Some snippet + * + * \struct someStruct + * + * \subpage someSubpage "Some description" + * + * \subsection someSubsection Some title + * + * \subsubsection someSubsection Some title + * + * \tableofcontents + * + * \test Some + * description of the + * test case + * + * \throw superException + * + * \throws RuntimeError + */ +void func09(int a) +{ +} + + +/** + * \todo Some very important task + * + * \tparam b B is mentioned again... + * + * \typedef someTypedef + * + * \union someUnion + * + * \until somePattern + * + * \var someVar + * + * \verbatim + * very long + * text with tags <sometag> + * \endverbatim + * + * \verbinclude someFile.h + * + * \version 0.0.0.2 + * + * \warning This is senseless! + * + * \weakgroup someGroup Some title + * + * \xmlonly + * This will only appear in XML + * \endxmlonly + * + * \xrefitem todo "Todo" "Todo List" + * + * Here goes test of symbols: + * \$ \@ \\ \& \~ \< \> \# \% \" \. \:: + * + * And here goes simple text + */ +void func10(int a, float b) +{ +} + +%} diff --git a/Examples/test-suite/doxygen_translate_links.i b/Examples/test-suite/doxygen_translate_links.i new file mode 100644 index 000000000..769a4f4e7 --- /dev/null +++ b/Examples/test-suite/doxygen_translate_links.i @@ -0,0 +1,67 @@ + + +%module doxygen_translate_links +%include "std_string.i" + +%inline %{ + +class Shape +{ +public: + typedef Shape* superType; +}; + +/** + * Testing typenames converting in \@ link + * + * \link superFunc(int,std::string) + * Test for std_string member + * \endlink + * + * \link superFunc(int,long,void*) + * Test for simple types + * \endlink + * + * \link superFunc(Shape::superType*) + * Test for custom types + * \endlink + * + * \link superFunc(int**[13]) + * Test for complex types + * \endlink + * + * same works for 'See also:' links: + * + * \sa superFunc(int,std::string) + * \sa superFunc(int,long,void*) + * \sa superFunc(Shape::superType*) + * \sa superFunc(int**[13]) + * + * some failing params: + * + * \sa superFunc() + * \sa superFunc() + * \sa superFunc() + * + */ +void function() +{ +} + +void superFunc(int, std::string) +{ +} + +void superFunc(int, long, void *) +{ +} + +void superFunc(Shape::superType *) +{ +} + +void superFunc(int **arr[13]) +{ +} + +%} diff --git a/Examples/test-suite/errors/Makefile.in b/Examples/test-suite/errors/Makefile.in index cf7889a1d..c66840997 100644 --- a/Examples/test-suite/errors/Makefile.in +++ b/Examples/test-suite/errors/Makefile.in @@ -27,12 +27,24 @@ SWIGINVOKE = $(SWIG_LIB_SET) $(SWIGTOOL) $(SWIGEXE) ALL_ERROR_TEST_CASES := $(patsubst %.i,%, $(notdir $(wildcard $(srcdir)/*.i))) CPP_ERROR_TEST_CASES := $(filter cpp_%, $(ALL_ERROR_TEST_CASES)) C_ERROR_TEST_CASES := $(filter-out $(CPP_ERROR_TEST_CASES), $(ALL_ERROR_TEST_CASES)) +DOXYGEN_ERROR_TEST_CASES := $(filter doxygen_%, $(C_ERROR_TEST_CASES)) +C_ERROR_TEST_CASES := $(filter-out $(DOXYGEN_ERROR_TEST_CASES), $(C_ERROR_TEST_CASES)) + +# Always use C++ for Doxygen tests, there doesn't seem to be any need to +# distinguish between C and C++ Doxygen tests. +DOXYGEN_ERROR_TEST_CASES := $(DOXYGEN_ERROR_TEST_CASES:=.cpptest) ERROR_TEST_CASES := $(CPP_ERROR_TEST_CASES:=.cpptest) \ - $(C_ERROR_TEST_CASES:=.ctest) + $(C_ERROR_TEST_CASES:=.ctest) \ + $(DOXYGEN_ERROR_TEST_CASES) include $(srcdir)/../common.mk +# This is tricky: we need to let common.mk define SWIGOPT before appending to +# it, if we do it before including it, its defining of SWIGOPT would override +# whatever we do here. +$(DOXYGEN_ERROR_TEST_CASES): SWIGOPT += -doxygen + # Portable dos2unix / todos for stripping CR TODOS = tr -d '\r' #TODOS = sed -e 's/\r$$//' # On Mac OS X behaves as if written 's/r$$//' diff --git a/Examples/test-suite/errors/doxygen_unknown_command.i b/Examples/test-suite/errors/doxygen_unknown_command.i new file mode 100644 index 000000000..0f32ee966 --- /dev/null +++ b/Examples/test-suite/errors/doxygen_unknown_command.i @@ -0,0 +1,6 @@ +%module xxx + +/** + There is an \unknown Doxygen comment here. + */ +void foo(); diff --git a/Examples/test-suite/errors/doxygen_unknown_command.stderr b/Examples/test-suite/errors/doxygen_unknown_command.stderr new file mode 100644 index 000000000..e5c32cc4b --- /dev/null +++ b/Examples/test-suite/errors/doxygen_unknown_command.stderr @@ -0,0 +1 @@ +doxygen_unknown_command.i:4: Warning 560: Unknown Doxygen command: unknown. diff --git a/Examples/test-suite/java/CommentParser.java b/Examples/test-suite/java/CommentParser.java new file mode 100644 index 000000000..c8adc1d1e --- /dev/null +++ b/Examples/test-suite/java/CommentParser.java @@ -0,0 +1,168 @@ + +import com.sun.javadoc.*; +import java.util.HashMap; +import java.util.Map.Entry; +import java.util.Map; +import java.util.Set; +import java.util.Iterator; +import java.io.BufferedWriter; +import java.io.OutputStreamWriter; +import java.io.FileOutputStream; +import java.io.IOException; + + +public class CommentParser { + private static Map<String, String> m_parsedComments = new HashMap<String, String>(); + + public static boolean start(RootDoc root) { + + /* + * This method is called by 'javadoc' and gets the whole parsed java + * file, we get comments and store them + */ + + for (ClassDoc classDoc : root.classes()) { + + if (classDoc.getRawCommentText().length() > 0) + m_parsedComments.put(classDoc.qualifiedName(), classDoc.getRawCommentText()); + + for (FieldDoc f : classDoc.enumConstants()) { + if (f.getRawCommentText().length() > 0) + m_parsedComments.put(f.qualifiedName(), f.getRawCommentText()); + } + for (FieldDoc f : classDoc.fields()) { + if (f.getRawCommentText().length() > 0) + m_parsedComments.put(f.qualifiedName(), f.getRawCommentText()); + } + for (MethodDoc m : classDoc.methods()) { + if (m.getRawCommentText().length() > 0) + m_parsedComments.put(m.toString(), m.getRawCommentText()); + } + } + return true; + } + + + public int check(Map<String, String> wantedComments) { + int errorCount=0; + Iterator<Entry<String, String>> it = m_parsedComments.entrySet().iterator(); + + while (it.hasNext()) { + + Entry<String, String> e = (Entry<String, String>) it.next(); + String actualStr = e.getValue(); + String wantedStr = wantedComments.get(e.getKey()); + // this may be weird, but I don't know any more effective solution + actualStr = actualStr.replace(" ", ""); + actualStr = actualStr.replaceAll("\t", ""); + actualStr = actualStr.replace("\n", ""); + + // Removing of <br> is temporary solution, since adding of + // <br> tag requires changes in all tests. However, <br> + // tag should be added more selectively and when this is + // implemented, tests should be updated. + actualStr = actualStr.replace("<br>", ""); + + if (wantedStr != null) { + wantedStr = wantedStr.replace(" ", ""); + wantedStr = wantedStr.replace("\t", ""); + wantedStr = wantedStr.replace("\n", ""); + wantedStr = wantedStr.replace("<br>", ""); + } + /* The following lines replace multiple whitespaces with a single one. + Although this would be more exact testing, it would also require + more work on test maintenance. + actualStr = actualStr.replace('\t', ' '); + actualStr = actualStr.replaceAll(" +", " "); + // actualStr = actualStr.replace("\n", ""); + if (wantedStr != null) { + wantedStr = wantedStr.replace('\t', ' '); + wantedStr = wantedStr.replaceAll(" +", " "); + // wantedStr = wantedStr.replace("\n", ""); + } */ + + if (!actualStr.equals(wantedStr)) { + System.out.println("\n\n////////////////////////////////////////////////////////////////////////"); + System.out.println("Documentation comments for '" + e.getKey() + "' do not match!"); + String expectedFileName = "expected.txt"; + String gotFileName = "got.txt"; + System.out.println("Output is also saved to files '" + expectedFileName + + "' and '" + gotFileName + "'"); + // here we print original strings, for nicer output + System.out.println("\n\n---\nexpected:\n" + wantedComments.get(e.getKey())); + System.out.println("\n\n---\ngot:\n" + e.getValue()); + + try { + // write expected string to file + BufferedWriter expectedFile = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(expectedFileName))); + expectedFile.write(wantedComments.get(e.getKey())); + expectedFile.close(); + + // write translated string to file + BufferedWriter gotFile = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(gotFileName))); + gotFile.write(e.getValue().replace("<br>", "")); + gotFile.close(); + } catch (IOException ex) { + System.out.println("Error when writing output to file: " + ex); + } + + errorCount++; + } + } + + if (m_parsedComments.size() != wantedComments.size()) { + System.out.println("Mismatch in the number of comments!\n Expected: " + + wantedComments.size() + "\n Parsed: " + + m_parsedComments.size()); + System.out.println("Expected keys: "); + printKeys(wantedComments); + System.out.println("Parsed keys: "); + printKeys(m_parsedComments); + + errorCount++; + } + + return errorCount > 0 ? 1 : 0; + } + + + private void printKeys(Map<String, String> map) { + + Set<String> keys = map.keySet(); + for (String key : keys) { + System.out.println(" " + key); + } + } + + + public static void printCommentListForJavaSource() { + + Iterator< Entry<String, String> > it = m_parsedComments.entrySet().iterator(); + + while (it.hasNext()) { + + Entry<String, String> e = (Entry<String, String>) it.next(); + String commentText = e.getValue(); + commentText = commentText.replace("\\", "\\\\"); + commentText = commentText.replace("\"", "\\\""); + commentText = commentText.replace("\n", "\\n\" +\n\t\t\""); + System.out.format("wantedComments.put(\"%s\",\n\t\t\"%s\");\n", e.getKey(), commentText); + } + } + + + public static void main(String argv[]) { + + if (argv.length<1) { + System.out.format("Usage:\n\tCommentParser <package to parse>\n"); + System.exit(1); + } + + com.sun.tools.javadoc.Main.execute("The comment parser program", + "CommentParser", new String[]{"-quiet", argv[0]}); + + // if we are run as standalone app, print the list of found comments as it would appear in java source + + printCommentListForJavaSource(); + } +} diff --git a/Examples/test-suite/java/Makefile.in b/Examples/test-suite/java/Makefile.in index 87538de59..f1717b81b 100644 --- a/Examples/test-suite/java/Makefile.in +++ b/Examples/test-suite/java/Makefile.in @@ -6,8 +6,11 @@ LANGUAGE = java JAVA = @JAVA@ JAVAC = @JAVAC@ JAVAFLAGS = @JAVAFLAGS@ +JAVA_CLASSPATH_SEP = @JAVA_CLASSPATH_SEP@ SCRIPTSUFFIX = _runme.java +JAVA_HOME ?= @JAVA_HOME@ + srcdir = @srcdir@ top_srcdir = ../@top_srcdir@ top_builddir = ../@top_builddir@ @@ -50,6 +53,12 @@ CPP11_TEST_CASES = \ cpp11_shared_ptr_upcast \ cpp11_strongly_typed_enumerations_simple \ +DOXYGEN_TEST_CASES := \ + doxygen_parsing_enums_simple \ + doxygen_parsing_enums_proper \ + doxygen_parsing_enums_typesafe \ + doxygen_parsing_enums_typeunsafe \ + include $(srcdir)/../common.mk # Overridden variables here @@ -95,14 +104,20 @@ setup = \ mkdir $(JAVA_PACKAGE); \ fi +# Doxygen test cases need to be compiled together with the CommentsParser class +# which depends on com.sun.javadoc package which is located in this JAR. +JAVA_CLASSPATH := . +$(DOXYGEN_TEST_CASES:=.cpptest): JAVA_CLASSPATH := "$(JAVA_HOME)/lib/tools.jar$(JAVA_CLASSPATH_SEP)." +$(DOXYGEN_TEST_CASES:=.cpptest): DOXYGEN_COMMENT_PARSER := $(srcdir)/CommentParser.java + # Compiles java files then runs the testcase. A testcase is only run if # a file is found which has _runme.java appended after the testcase name. # Note Java uses LD_LIBRARY_PATH under Unix, PATH under Cygwin/Windows, SHLIB_PATH on HPUX and DYLD_LIBRARY_PATH on Mac OS X. run_testcase = \ cd $(JAVA_PACKAGE) && $(COMPILETOOL) $(JAVAC) -classpath . `find . -name "*.java"` && cd .. && \ if [ -f $(SCRIPTDIR)/$(SCRIPTPREFIX)$*$(SCRIPTSUFFIX) ]; then \ - $(COMPILETOOL) $(JAVAC) -classpath . -d . $(SCRIPTDIR)/$(SCRIPTPREFIX)$*$(SCRIPTSUFFIX) && \ - env LD_LIBRARY_PATH="$(JAVA_PACKAGE):$$LD_LIBRARY_PATH" PATH="$(JAVA_PACKAGE):$$PATH" SHLIB_PATH="$(JAVA_PACKAGE):$$SHLIB_PATH" DYLD_LIBRARY_PATH="$(JAVA_PACKAGE):$$DYLD_LIBRARY_PATH" $(RUNTOOL) $(JAVA) $(JAVAFLAGS) -classpath . $*_runme; \ + $(COMPILETOOL) $(JAVAC) -classpath $(JAVA_CLASSPATH) -d . $(DOXYGEN_COMMENT_PARSER) $(SCRIPTDIR)/$(SCRIPTPREFIX)$*$(SCRIPTSUFFIX) && \ + env LD_LIBRARY_PATH="$(JAVA_PACKAGE):$$LD_LIBRARY_PATH" PATH="$(JAVA_PACKAGE):$$PATH" SHLIB_PATH="$(JAVA_PACKAGE):$$SHLIB_PATH" DYLD_LIBRARY_PATH="$(JAVA_PACKAGE):$$DYLD_LIBRARY_PATH" $(RUNTOOL) $(JAVA) $(JAVAFLAGS) -classpath $(JAVA_CLASSPATH) $*_runme; \ fi # Clean: remove testcase directories diff --git a/Examples/test-suite/java/doxygen_alias_runme.java b/Examples/test-suite/java/doxygen_alias_runme.java new file mode 100644 index 000000000..e21ed6d19 --- /dev/null +++ b/Examples/test-suite/java/doxygen_alias_runme.java @@ -0,0 +1,32 @@ + +import doxygen_alias.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_alias_runme { + static { + try { + System.loadLibrary("doxygen_alias"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_alias runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_alias"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + wantedComments.put("doxygen_alias.doxygen_alias.make_something()", + " A function returning something.<br>\n" + + " <br>\n" + + " @return A new object which may be null.\n" + + ""); + + System.exit(parser.check(wantedComments)); + } +} diff --git a/Examples/test-suite/java/doxygen_basic_notranslate_runme.java b/Examples/test-suite/java/doxygen_basic_notranslate_runme.java new file mode 100644 index 000000000..d1c433545 --- /dev/null +++ b/Examples/test-suite/java/doxygen_basic_notranslate_runme.java @@ -0,0 +1,101 @@ + +import doxygen_basic_notranslate.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_basic_notranslate_runme { + static { + try { + System.loadLibrary("doxygen_basic_notranslate"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + /* + Here we are using internal javadoc tool, it accepts the name of the class as paramterer, + and calls the start() method of that class with parsed information. + */ + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_basic_notranslate runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_basic_notranslate"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function3(int)", + " \n" + + " A test for overloaded functions\n" + + " This is function \\b one\n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function4()", + " \n" + + " A test of some mixed tag usage\n" + + " \\if CONDITION\n" + + " This \\a code fragment shows us something \\.\n" + + " \\par Minuses:\n" + + " \\arg it's senseless\n" + + " \\arg it's stupid\n" + + " \\arg it's null\n" + + " \n" + + " \\warning This may not work as expected\n" + + " \n" + + " \\code\n" + + " int main() { while(true); }\n" + + " \\endcode\n" + + " \\endif\n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function()", + " \n" + + " \\brief\n" + + " Brief description.\n" + + " \n" + + " The comment text\n" + + " \\author Some author\n" + + " \\return Some number\n" + + " \\sa function2\n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function5(int)", + " This is a post comment. \n" + + ""); + wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function7(doxygen_basic_notranslate.SWIGTYPE_p_p_p_Shape)", + " \n" + + " Test for a parameter with difficult type\n" + + " (mostly for python)\n" + + " @param a Very strange param\n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function3(int, int)", + " \n" + + " A test for overloaded functions\n" + + " This is function \\b two\n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function6(int)", + " \n" + + " Test for default args\n" + + " @param a Some parameter, default is 42\n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function6()", + " \n" + + " Test for default args\n" + + " @param a Some parameter, default is 42\n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_notranslate.doxygen_basic_notranslate.function2()", + " \n" + + " A test of a very very very very very very very very very very very very very very very very\n" + + " very very very very very long comment string.\n" + + " \n" + + ""); + + // and ask the parser to check comments for us + System.exit(parser.check(wantedComments)); + } +}
\ No newline at end of file diff --git a/Examples/test-suite/java/doxygen_basic_translate_runme.java b/Examples/test-suite/java/doxygen_basic_translate_runme.java new file mode 100644 index 000000000..f307b3abc --- /dev/null +++ b/Examples/test-suite/java/doxygen_basic_translate_runme.java @@ -0,0 +1,99 @@ + +import doxygen_basic_translate.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_basic_translate_runme { + static { + try { + System.loadLibrary("doxygen_basic_translate"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + /* + Here we are using internal javadoc tool, it accepts the name of the class as paramterer, + and calls the start() method of that class with parsed information. + */ + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_basic_translate runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_basic_translate"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + + wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function()", + " \n" + + " Brief description.\n" + + " \n" + + " The comment text.\n" + + " @author Some author\n" + + " @return Some number\n" + + " @see function2\n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function2()", + " A test of a very very very very very very very very very very very very very very very very \n" + + " very very very very very long comment string. \n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function4()", + " A test of some mixed tag usage \n" + + " If: CONDITION {\n" + + " This <i>code </i>fragment shows us something . \n" + + " <p alt=\"Minuses: \">\n" + + " <li>it's senseless \n" + + " </li><li>it's stupid \n" + + " </li><li>it's null \n" + + " \n" + + " </li></p>Warning: This may not work as expected \n" + + " \n" + + " {@code \n" + + "int main() { while(true); } \n" + + " }\n" + + " }\n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function3(int)", + " A test for overloaded functions \n" + + " This is function <b>one </b>\n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function5(int)", + " This is a post comment. \n" + + ""); + wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function6(int)", + " Test for default args \n" + + " @param a Some parameter, default is 42" + + " \n" + + ""); + wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function6()", + " Test for default args \n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function7(doxygen_basic_translate.SWIGTYPE_p_p_p_Shape)", + " Test for a parameter with difficult type \n" + + " (mostly for python) \n" + + " @param a Very strange param \n" + + ""); + wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function3(int, int)", + " A test for overloaded functions \n" + + " This is function <b>two </b>\n" + + " \n" + + ""); + wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.Atan2(double, double)", + " Multiple parameters test.\n" + + " \n" + + " @param y Vertical coordinate.\n" + + " @param x Horizontal coordinate.\n" + + " @return Arc tangent of <code>y/x</code>.\n" + + ""); + + // and ask the parser to check comments for us + System.exit(parser.check(wantedComments)); + } +} diff --git a/Examples/test-suite/java/doxygen_ignore_runme.java b/Examples/test-suite/java/doxygen_ignore_runme.java new file mode 100644 index 000000000..6250ce525 --- /dev/null +++ b/Examples/test-suite/java/doxygen_ignore_runme.java @@ -0,0 +1,44 @@ + +import doxygen_ignore.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_ignore_runme { + static { + try { + System.loadLibrary("doxygen_ignore"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_ignore runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_ignore"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + wantedComments.put("doxygen_ignore.doxygen_ignore.func()", + " A contrived example of ignoring too many commands in one comment.<br>\n" + + " <br>\n" + + " <br>\n" + + " <br>\n" + + " <br>\n" + + " This is specific to <i>Java</i>.<br>\n" + + " <br>\n" + + " <br>\n" + + " <br>\n" + + " <br>\n" + + " Command ignored, but anything here is still included.<br>\n" + + " <br>\n" + + "\n" + + "\n" + + "\n" + + ""); + + System.exit(parser.check(wantedComments)); + } +} diff --git a/Examples/test-suite/java/doxygen_misc_constructs_runme.java b/Examples/test-suite/java/doxygen_misc_constructs_runme.java new file mode 100644 index 000000000..7c799412e --- /dev/null +++ b/Examples/test-suite/java/doxygen_misc_constructs_runme.java @@ -0,0 +1,197 @@ + +import doxygen_misc_constructs.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_misc_constructs_runme { + static { + try { + System.loadLibrary("doxygen_misc_constructs"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + /* + Here we are using internal javadoc tool, it accepts the name of the class as paramterer, + and calls the start() method of that class with parsed information. + */ + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_misc_constructs runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_misc_constructs"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getConnection()", + "\n" + + "\n" + + " This function returns connection id.\n" + + "\n" + + ""); + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getAddress(doxygen_misc_constructs.SWIGTYPE_p_int, int)", + " Returns address of file line.\n" + + " \n" + + " @param fileName name of the file, where the source line is located\n" + + " @param line line number\n" + + " {@link Connection::getId() }<br>\n" + + "\n" + + ""); + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getG_zipCode()", + " Tag endlink must be recognized also when it is the last token\n" + + " in the commment.\n" + + " \n" + + " {@link Connection::getId() }<br>\n" + + " {@link debugIdeTraceProfilerCoverageSample.py Python example. }\n" + + "\n" + + ""); + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.setG_zipCode(int)", + " Tag endlink must be recognized also when it is the last token\n" + + " in the commment.\n" + + "\n" + + " {@link Connection::getId() }<br>\n" + + " {@link debugIdeTraceProfilerCoverageSample.py Python example. }\n" + + "\n" + + ""); + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getG_counter()", + " Tag endlink must be recognized also when followed by nonspace charater.\n" + + "\n" + + " {@link Connection::getId() }<br>\n" + + "\n" + + ""); + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.waitTime(int)", + " Determines how long the <code>isystem.connect</code> should wait for running\n" + + " instances to respond. Only one of <code>lfWaitXXX</code> flags from IConnect::ELaunchFlags\n" + + " may be specified.\n" + + "\n" + + ""); + wantedComments.put("doxygen_misc_constructs.CConnectionConfig", + " This class contains information for connection to winIDEA. Its methods\n" + + " return reference to self, so we can use it like this:\n" + + " <pre>\n" + + " CConnectionConfig config = new CConnectionConfig();\n" + + " config.discoveryPort(5534).dllPath(\"C:\\\\myWinIDEA\\\\connect.dll\").id(\"main\");\n" + + " </pre>\n" + + "\n" + + " All parameters are optional. Set only what is required, default values are\n" + + " used for unspecified parameters.\n" + + " <p>\n" + + "\n" + + " {@link advancedWinIDEALaunching.py Python example. }<br>\n" + + "\n" + + ""); + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getAddress(doxygen_misc_constructs.SWIGTYPE_p_int, int, boolean)", + " Returns address of file line.\n" + + "\n" + + " @param fileName name of the file, where the source line is located\n" + + " @param line line number\n" + + " @param isGetSize if set, for every object location both address and size are returned\n" + + "\n" + + " {@link Connection::getId() }<br>\n" + + "\n" + + ""); + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.setG_counter(char)", + " Tag endlink must be recognized also when followed by nonspace charater.\n" + + "\n" + + " {@link Connection::getId() }<br>\n" + + "\n" + + ""); + + wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum", + " Class description.\n" + + "\n"); + + wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested", + " Enum description.\n" + + "\n"); + + wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested.ONE", + " desc of one\n"); + + wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested.TWO", + " desc of two\n"); + + wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested.THREE", + " desc of three\n"); + + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.showList()", +" An example of a list in a documentation comment.<br>\n" + +" <br>\n" + +" - The first item of the list.<br>\n" + +" - The second list item, on<br>\n" + +" several indented lines,<br>\n" + +" showing that the indentation<br>\n" + +" is preserved.<br>\n" + +" - And the final list item after it.<br>\n" + +" <br>\n" + +" And this is not a list item any more.\n" + + ""); + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.isNoSpaceValidA()", + " This comment without space after '*' is valid in Doxygen.\n" + + "\n" + + ""); + + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.isNoSpaceValidB()", + " .This comment without space after '*' is valid in Doxygen.\n" + + "\n" + + ""); + + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.backslashA()", + " Backslash following<code>word</code> is a valid doxygen command. Output contains\n" + + " 'followingword' with 'word' in code font.\n" + + "\n" + + ""); + + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.backslashB()", + " Doxy command without trailing space is ignored - nothing appears\n" + + " on output. Standalone \\ and '\\' get to output.\n" + + " Standalone @ and '@' get to output.\n" + + " Commands \"in quoted \\b strings are treated as plain text\".\n" + + " Commands not recognized by Doxygen are ignored.\n" + + " Backslashes in DOS paths d:and words\n" + + " following them do not appear on output, we must quote them with\n" + + " double quotes: \"d:\\xyz\\qwe\\myfile\", \"@something\". Single quotes do not help:\n" + + " 'd:'. Escaping works: d:\\xyz\\qwe\\myfile. Unix\n" + + " paths of course have no such problems: /xyz/qwe/myfile\n" + + " Commands for escaped symbols:\n" + + " $ @ \\ & ~ < > # % " . :: @text ::text" + + "\n"); + + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.backslashC()", + " Backslash e at end of <i>line</i> froze SWIG\n" + + " <i>with</i> old comment parser.\n" + + " @see MyClass#fun(char,float)\n" + + ""); + + wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.cycle(int, java.lang.String)", + " The next line contains expression:\n" + + " <pre>\n" + + " ['retVal < 10', 'g_counter == 23 && g_mode & 3']\n" + + " </pre>\n" + + "\n" + + " Both words should be emphasized <b>isystem.connect</b>.\n" + + " But not the last period. For <b>example</b>, comma should not be emphasized.\n" + + " Similar <b>for</b>: double colon.\n" + + "\n" + + " Spaces at the start of line should be taken into account:\n" + + " @param id used as prefix in log\n" + + " statements. The default value is empty string, which is OK if\n" + + " there is only one app. instance. Example:\n" + + " <pre>\n" + + " ctrl.setBP(\"func1\");\n" + + " </pre>\n" + + " If we set the id to <code>main_</code>, we get:\n" + + " <pre>\n" + + " main_ctrl.setBP(\"func1\");\n" + + " </pre>\n" + + "\n" + + " @param fileName name of the log file\n"); + + + // and ask the parser to check comments for us + System.exit(parser.check(wantedComments)); + } +} diff --git a/Examples/test-suite/java/doxygen_parsing_enums_proper_runme.java b/Examples/test-suite/java/doxygen_parsing_enums_proper_runme.java new file mode 100644 index 000000000..a8527e364 --- /dev/null +++ b/Examples/test-suite/java/doxygen_parsing_enums_proper_runme.java @@ -0,0 +1,62 @@ + +import doxygen_parsing_enums_proper.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_parsing_enums_proper_runme { + static { + try { + System.loadLibrary("doxygen_parsing_enums_proper"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + /* + Here we are using internal javadoc tool, it accepts the name of the class as paramterer, + and calls the start() method of that class with parsed information. + */ + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_parsing_enums_proper runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_parsing_enums_proper"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + + wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum2.SOME_ITEM_10", + "Post comment for the first item \n" + + ""); + wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum.SOME_ITEM_1", + " The comment for the first item \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum", + " Testing comments before enum items \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum2.SOME_ITEM_30", + "Post comment for the third item \n" + + ""); + wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum2", + " Testing comments after enum items \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum.SOME_ITEM_3", + " The comment for the third item \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum.SOME_ITEM_2", + " The comment for the second item \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_proper.SomeAnotherEnum2.SOME_ITEM_20", + "Post comment for the second item \n" + + ""); + + // and ask the parser to check comments for us + System.exit(parser.check(wantedComments)); + } +} diff --git a/Examples/test-suite/java/doxygen_parsing_enums_simple_runme.java b/Examples/test-suite/java/doxygen_parsing_enums_simple_runme.java new file mode 100644 index 000000000..f68fff151 --- /dev/null +++ b/Examples/test-suite/java/doxygen_parsing_enums_simple_runme.java @@ -0,0 +1,54 @@ + +import doxygen_parsing_enums_simple.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_parsing_enums_simple_runme { + static { + try { + System.loadLibrary("doxygen_parsing_enums_simple"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + /* + Here we are using internal javadoc tool, it accepts the name of the class as paramterer, + and calls the start() method of that class with parsed information. + */ + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_parsing_enums_simple runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_parsing_enums_simple"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + + wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_30", + "Post comment for the third item \n" + + ""); + wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_3", + " The comment for the third item \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_2", + " The comment for the second item \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_10", + "Post comment for the first item \n" + + ""); + wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_20", + "Post comment for the second item \n" + + ""); + wantedComments.put("doxygen_parsing_enums_simple.doxygen_parsing_enums_simpleConstants.SOME_ITEM_1", + " The comment for the first item \n" + + " \n" + + ""); + + // and ask the parser to check comments for us + System.exit(parser.check(wantedComments)); + } +} diff --git a/Examples/test-suite/java/doxygen_parsing_enums_typesafe_runme.java b/Examples/test-suite/java/doxygen_parsing_enums_typesafe_runme.java new file mode 100644 index 000000000..7c7f05ccc --- /dev/null +++ b/Examples/test-suite/java/doxygen_parsing_enums_typesafe_runme.java @@ -0,0 +1,63 @@ + +import doxygen_parsing_enums_typesafe.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_parsing_enums_typesafe_runme { + static { + try { + System.loadLibrary("doxygen_parsing_enums_typesafe"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + /* + Here we are using internal javadoc tool, it accepts the name of the class as paramterer, + and calls the start() method of that class with parsed information. + */ + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_parsing_enums_typesafe runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_parsing_enums_typesafe"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + + wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum.SOME_ITEM_1", + " The comment for the first item \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum2", + " Testing comments after enum items \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum.SOME_ITEM_2", + " The comment for the second item \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum2.SOME_ITEM_20", + "Post comment for the second item \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum", + " Testing comments before enum items \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum2.SOME_ITEM_10", + "Post comment for the first item \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum.SOME_ITEM_3", + " The comment for the third item \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typesafe.SomeAnotherEnum2.SOME_ITEM_30", + "Post comment for the third item \n" + + ""); + + + // and ask the parser to check comments for us + System.exit(parser.check(wantedComments)); + } +} diff --git a/Examples/test-suite/java/doxygen_parsing_enums_typeunsafe_runme.java b/Examples/test-suite/java/doxygen_parsing_enums_typeunsafe_runme.java new file mode 100644 index 000000000..8c7dfeda0 --- /dev/null +++ b/Examples/test-suite/java/doxygen_parsing_enums_typeunsafe_runme.java @@ -0,0 +1,62 @@ + +import doxygen_parsing_enums_typeunsafe.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_parsing_enums_typeunsafe_runme { + static { + try { + System.loadLibrary("doxygen_parsing_enums_typeunsafe"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + /* + Here we are using internal javadoc tool, it accepts the name of the class as paramterer, + and calls the start() method of that class with parsed information. + */ + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_parsing_enums_typeunsafe runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_parsing_enums_typeunsafe"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + + wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum.SOME_ITEM_2", + " The comment for the second item \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum.SOME_ITEM_3", + " The comment for the third item \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum.SOME_ITEM_1", + " The comment for the first item \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum2.SOME_ITEM_20", + "Post comment for the second item \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum", + " Testing comments before enum items \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum2", + " Testing comments after enum items \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum2.SOME_ITEM_30", + "Post comment for the third item \n" + + ""); + wantedComments.put("doxygen_parsing_enums_typeunsafe.SomeAnotherEnum2.SOME_ITEM_10", + "Post comment for the first item \n" + + ""); + + // and ask the parser to check comments for us + System.exit(parser.check(wantedComments)); + } +} diff --git a/Examples/test-suite/java/doxygen_parsing_runme.java b/Examples/test-suite/java/doxygen_parsing_runme.java new file mode 100644 index 000000000..7a8b0fae9 --- /dev/null +++ b/Examples/test-suite/java/doxygen_parsing_runme.java @@ -0,0 +1,132 @@ + +import doxygen_parsing.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_parsing_runme { + static { + try { + System.loadLibrary("doxygen_parsing"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + /* + Here we are using internal javadoc tool, it accepts the name of the class as paramterer, + and calls the start() method of that class with parsed information. + */ + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_parsing runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_parsing"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + + wantedComments.put("doxygen_parsing.SomeAnotherClass.getClassAttr()", + " The class attribute comment \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherClass.setClassAttr3(int)", + "The class attribute post-comment with details \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherStruct.setStructAttr3(int)", + "The struct attribute post-comment with details \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherClass.classMethodExtended2(int, int)", + " The class method with parameter \n" + + " \n" + + " @param a Parameter a \n" + + " @param b Parameter b \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.SomeStruct", + " The struct comment \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.doxygen_parsing.setSomeVar(int)", + " The var comment \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherStruct.structMethod()", + " The struct method comment \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.doxygen_parsing.someFunction()", + " The function comment \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherClass.classMethodExtended(int, int)", + " The class method with parameter \n" + + " \n" + + " @param a Parameter a \n" + + " @param b Parameter b \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherClass.setClassAttr(int)", + " The class attribute comment \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherStruct.structMethodExtended(int, int)", + " The struct method with parameter \n" + + " \n" + + " @param a Parameter a \n" + + " @param b Parameter b \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherStruct.getStructAttr()", + " The struct attribute comment \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.SomeClass", + " The class comment \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherStruct.getStructAttr3()", + "The struct attribute post-comment with details \n" + + ""); + wantedComments.put("doxygen_parsing.doxygen_parsing.getSomeVar()", + " The var comment \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherStruct.setStructAttr2(int)", + "The struct attribute post-comment \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherClass.getClassAttr2()", + "The class attribute post-comment \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherStruct.getStructAttr2()", + "The struct attribute post-comment \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherStruct.setStructAttr(int)", + " The struct attribute comment \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.SomeEnum", + " The enum comment \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherClass.getClassAttr3()", + "The class attribute post-comment with details \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherClass.classMethod()", + " The class method comment.<br>\n" + + " <br>\n" + + " {@link SomeAnotherClass#classMethodExtended(int,int) a link text }\n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherStruct.structMethodExtended2(int, int)", + " The struct method with parameter \n" + + " \n" + + " @param a Parameter a \n" + + " @param b Parameter b \n" + + " \n" + + ""); + wantedComments.put("doxygen_parsing.SomeAnotherClass.setClassAttr2(int)", + "The class attribute post-comment \n" + + ""); + + // and ask the parser to check comments for us + System.exit(parser.check(wantedComments)); + } +} diff --git a/Examples/test-suite/java/doxygen_translate_all_tags_runme.java b/Examples/test-suite/java/doxygen_translate_all_tags_runme.java new file mode 100644 index 000000000..8bd65224f --- /dev/null +++ b/Examples/test-suite/java/doxygen_translate_all_tags_runme.java @@ -0,0 +1,153 @@ + +import doxygen_translate_all_tags.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_translate_all_tags_runme { + static { + try { + System.loadLibrary("doxygen_translate_all_tags"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + /* + Here we are using internal javadoc tool, it accepts the name of the class as paramterer, + and calls the start() method of that class with parsed information. + */ + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_translate_all_tags runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_translate_all_tags"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func01(int)", + " <i>Hello </i>\n\n\n" + + " <a id=\"theAnchor\"></a>\n\n\n" + + " <li>some list item</li>\n\n" + + " This is attention!\n" + + " You were warned!\n" + + " @author lots of them\n" + + " @author Zubr\n\n" + + " <b>boldword</b>\n\n" + + " Some brief description,\n" + + " extended to many lines.\n\n" + + " Not everything works right now...\n" + + " <code>codeword</code>\n\n\n\n\n\n" + + " <i>citationword</i>\n" + + " {@code some test code }\n"); + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func02(int)", + " Conditional comment: SOMECONDITION \n" + + " Some conditional comment \n" + + " End of conditional comment.\n" + + " Copyright: some copyright \n" + + " 1970 - 2012 \n" + + " @deprecated Now use another function \n" + + " This is very large \n" + + " and detailed description of some thing \n"); + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func03(int)", + " Comment for <b>func03()</b>.\n" + + " <i>italicword </i>\n" + + " <i>emphazedWord </i>\n" + + " @ example someFile.txt\n" + + " Some details on using the example"); + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func04(int)", + " @exception SuperError \n" + + " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" + + " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" + + " \\sqrt{(x_2-x_1)^2+(y_2-y_1)^2} \n" + + " This will only appear in hmtl \n"); + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func05(int)", + " If: ANOTHERCONDITION {\n" + + " First part of comment \n" + + " If: SECONDCONDITION {\n" + + " Nested condition text \n" + + " }Else if: THIRDCONDITION {\n" + + " The third condition text \n" + + " }Else: {The last text block \n" + + " }\n" + + " }Else: {Second part of comment \n" + + " If: CONDITION {\n" + + " Second part extended \n" + + " }\n" + + " }\n" + + " If not: SOMECONDITION {\n" + + " This is printed if not \n" + + " }\n" + + " <img src=testImage.bmp alt=\"Hello, world!\" />\n" + + " Some text \n" + + " describing invariant. \n"); + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func06(int)", + " Comment for <b>func06()</b>.\n" + + " This will only appear in LATeX \n" + + " <ul> \n" + + " <li>Some unordered list \n" + + " </li><li>With lots of items \n" + + " </li><li>lots of lots of items \n" + + " </li></ul> \n" + + " {@link someMember Some description follows }\n" + + " This will only appear in man\n"); + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func07(int)", + " Comment for <b>func07()</b>.\n" + + " Note: Here \n" + + " is the note! \n" + + " This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.\n" + + " <code>someword </code>\n" + + " @package superPackage \n" + + " <p alt=\"The paragraph title \">\n" + + " The paragraph text. \n" + + " Maybe even multiline \n" + + " </p>\n" + + " @param a the first param\n"); + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func08(int)", + "<a id=\"someAnchor\"></a>\n" + + "Text after anchor.\n" + + "<a href=\"#someAnchor\">Anchor description</a>\n" + + "<a href=\"#someAnchor\">someAnchor</a> not quoted text is not part of ref tag\n" + + "<a href=\"#someAnchor\">someAnchor</a>\n" + + " Remarks: Some remark text \n" + + " Remarks: Another remarks section \n" + + " @return Whatever \n" + + " @return it \n" + + " @return may return \n"); + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func09(int)", + " This will only appear in RTF \n" + + " @see someOtherMethod \n" + + " @see function \n" + + " Same as \n" + + " brief description \n" + + " @since version 0.0.0.1 \n" + + " @throws superException \n" + + " @throws RuntimeError \n"); + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func10(int, float)", + " TODO: Some very important task \n" + + " @param b B is mentioned again... \n" + + " {@literal \n" + + "very long \n" + + "text with tags <sometag> \n" + + " }\n" + + " @version 0.0.0.2 \n" + + " Warning: This is senseless! \n" + + " This will only appear in XML \n" + + " Here goes test of symbols: \n" + + " $ @ \\ & ~ < > # % " . :: \n" + + " And here goes simple text \n" + + ""); + // and ask the parser to check comments for us + System.exit(parser.check(wantedComments)); + } +} diff --git a/Examples/test-suite/java/doxygen_translate_links_runme.java b/Examples/test-suite/java/doxygen_translate_links_runme.java new file mode 100644 index 000000000..6d74e16fe --- /dev/null +++ b/Examples/test-suite/java/doxygen_translate_links_runme.java @@ -0,0 +1,69 @@ + +import doxygen_translate_links.*; +import com.sun.javadoc.*; +import java.util.HashMap; + +public class doxygen_translate_links_runme { + static { + try { + System.loadLibrary("doxygen_translate_links"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + /* + Here we are using internal javadoc tool, it accepts the name of the class as paramterer, + and calls the start() method of that class with parsed information. + */ + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_translate_links runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_translate_links"}); + + HashMap<String, String> wantedComments = new HashMap<String, String>(); + + + wantedComments.put("doxygen_translate_links.doxygen_translate_links.function()", + " \n" + + " Testing typenames converting in @ link \n" + + " \n" + + " {@link superFunc(int,String) \n" + + " Test for std_string member \n" + + " }\n" + + " \n" + + " {@link superFunc(int,int,SWIGTYPE_p_void) \n" + + " Test for simple types \n" + + " }\n" + + " \n" + + " {@link superFunc(SWIGTYPE_p_p_Shape) \n" + + " Test for custom types \n" + + " }\n" + + " \n" + + " {@link superFunc(SWIGTYPE_p_p_p_int) \n" + + " Test for complex types \n" + + " }\n" + + " \n" + + " same works for 'See also:' links: \n" + + " \n" + + " @see superFunc(int,String)\n" + + " @see superFunc(int,int,SWIGTYPE_p_void)\n" + + " @see superFunc(SWIGTYPE_p_p_Shape)\n" + + " @see superFunc(SWIGTYPE_p_p_p_int)\n" + + " \n" + + " some failing params: \n" + + " \n" + + " @see superFunc() \n" + + " @see superFunc() \n" + + " @see superFunc() \n" + + " \n" + + " \n" + + ""); + + // and ask the parser to check comments for us + System.exit(parser.check(wantedComments)); + } +}
\ No newline at end of file diff --git a/Examples/test-suite/java/doxygen_translate_runme.java b/Examples/test-suite/java/doxygen_translate_runme.java new file mode 100644 index 000000000..55e5d23d3 --- /dev/null +++ b/Examples/test-suite/java/doxygen_translate_runme.java @@ -0,0 +1,279 @@ + +import doxygen_translate.*; +import com.sun.javadoc.*; +import java.util.HashMap; +import java.util.Map; + +public class doxygen_translate_runme { + static { + try { + System.loadLibrary("doxygen_translate"); + } catch (UnsatisfiedLinkError e) { + System.err.println("Native code library failed to load. See the chapter on Dynamic Linking Problems in the SWIG Java documentation for help.\n" + e); + System.exit(1); + } + } + + public static void main(String argv[]) + { + /* + Here we are using internal javadoc tool, it accepts the name of the class as paramterer, + and calls the start() method of that class with parsed information. + */ + CommentParser parser = new CommentParser(); + com.sun.tools.javadoc.Main.execute("doxygen_translate runtime test", + "CommentParser", + new String[]{"-quiet", "doxygen_translate"}); + + Map<String, String> wantedComments = new HashMap<String, String>(); + + wantedComments.put("doxygen_translate.doxygen_translate.function(int, float)", + " <i>Hello </i>\n" + + " \n" + + " <li>some list item</li>\n" + + " \n" + + " @author lots of them \n" + + " \n" + + " @author Zubr \n" + + " \n" + + " <b>boldword </b>\n" + + " \n" + + " <code>codeword </code>\n" + + " \n" + + " <i>citationword </i>\n" + + " \n" + + " {@code some test code }\n" + + " \n" + + " Conditional comment: SOMECONDITION \n" + + " Some conditional comment \n" + + " End of conditional comment.\n" + + " \n" + + " Copyright: some copyright \n" + + " \n" + + " @deprecated Now use another function \n" + + " \n" + + " <i>italicword </i>\n" + + " \n" + + " @ example someFile.txt\n" + + " Some details on using the example\n" + + " \n" + + " @exception SuperError \n" + + " \n" + + " If: ANOTHERCONDITION {\n" + + " First part of comment \n" + + " If: SECONDCONDITION {\n" + + " Nested condition text}\n" + + " Else if: THIRDCONDITION {\n" + + " The third condition text}\n" + + " Else: {The last text block}}\n" + + " \n" + + " Else: {Second part of comment \n" + + " If: CONDITION {\n" + + " Second part extended}}\n" + + " \n" + + " \n" + + " \n" + + " If not: SOMECONDITION {\n" + + " This is printed if not}\n" + + " \n" + + " \n" + + " <img src=testImage.bmp alt=\"Hello, world!\"/>\n" + + " \n" + + " <ul> \n" + + " \n" + + " <li>Some unordered list</li>\n" + + " <li>With lots of items</li>\n" + + " <li>lots of lots of items</li>\n" + + " \n" + + " </ul> \n" + + " \n" + + " {@link someMember Some description follows }\n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " Note: Here \n" + + " is the note! \n" + + " \n" + + " This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.\n" + + " \n" + + " <code>someword </code>\n" + + " \n" + + " @package superPackage \n" + + " \n" + + " <p alt=\"The paragraph title \">\n" + + " The paragraph text. \n" + + " Maybe even multiline</p>\n" + + " \n" + + " @param a the first param \n" + + " \n" + + " Remarks: Some remark text \n" + + " \n" + + " Remarks: Another remarks section \n" + + " \n" + + " @return Whatever \n" + + " \n" + + " @return it \n" + + " \n" + + " @return may return \n" + + " \n" + + " @see someOtherMethod \n" + + " \n" + + " @see function \n" + + " \n" + + " @since version 0.0.0.1 \n" + + " \n" + + " @throws superException \n" + + " \n" + + " @throws RuntimeError \n" + + " \n" + + " TODO: Some very important task \n" + + " \n" + + " @param b B is mentioned again... \n" + + " \n" + + " {@literal \n" + + "very long \n" + + "text with tags <sometag> \n" + + " }\n" + + " \n" + + " @version 0.0.0.2 \n" + + " \n" + + " Warning: This is senseless! \n" + + " \n" + + " Here goes test of symbols: \n" + + " $ @ \\ & ~ < > # % " . :: \n" + + " \n" + + " And here goes simple text \n" + + " \n" + + ""); + + wantedComments.put("doxygen_translate.doxygen_translate.htmlFunction(int, float)", + " Test for html tags. See Doxygen doc for list of tags recognized by Doxygen. \n" + + " \n" + + " <a href=\"http://acme.com/index.html\">This is link</a> \n" + + " <b>bold</b> \n" + + " <blockquote cite=\"http://www.worldwildlife.org/who/index.html\"> \n" + + " Quotation block. \n" + + " </blockquote> \n" + + " <br> \n" + + " <center>center</center> \n" + + " <code>this is code</code> \n" + + "\n" + + " <dl>\n" + + " <dt>Starts an item title.</dt>\n" + + " <dd>Starts an item description.</dd>\n" + + " </dl>\n" + + "\n" + + " <dfn> Starts a piece of text displayed in a typewriter font. \n" + + " </dfn> \n" + + " <div> Starts a section with a specific style (HTML only) \n" + + " </div> \n" + + " <em> Starts a piece of text displayed in an italic font.</em> \n" + + "\n" + + " <form> 'Form' does not generate any output. \n" + + " </form> \n" + + " <hr> \n" + + " <h1> Heading 1 \n" + + " </h1> \n" + + " <h2> Heading 2 \n" + + " </h2> \n" + + " <h3> Heading 3 \n" + + " </h3> \n" + + " <i>Starts a piece of text displayed in an italic font.</i> \n" + + " <input>Input tag. \n" + + " \n" + + " <img src=\"slika.png\"> \n" + + " <meta>Meta tag. \n" + + " <multicol>Multicol is ignored by doxygen. \n" + + " </multicol> \n" + + " \n" + + " <ol> \n" + + " <li>List item 1.</li> \n" + + " <li>List item 2.</li> \n" + + " </ol> \n" + + " \n" + + " <p> Starts a new paragraph. \n" + + " </p> \n" + + " <pre> Starts a preformatted fragment. \n" + + " </pre> \n" + + " <small> Starts a section of text displayed in a smaller font. \n" + + " </small> \n" + + " <span> Starts an inline text fragment with a specific style.</span> \n" + + " \n" + + " <strong> Starts a section of bold text.</strong> \n" + + " <sub> Starts a piece of text displayed in subscript.</sub> \n" + + " <sup> Starts a piece of text displayed in superscript.</sup> \n" + + " \n" + + " <table border = '1'> \n" + + " <caption>Animals</caption> \n" + + " <tr><th> Column 1 </th><th> Column 2 </th></tr> \n" + + " <tr><td> cow </td><td> dog </td></tr> \n" + + " <tr><td> cat </td><td> mouse </td></tr> \n" + + " <tr><td> horse </td><td> parrot </td></tr> \n" + + " </table> \n" + + " \n" + + " <tt> Starts a piece of text displayed in a typewriter font. \n" + + " </tt> \n" + + " <kbd> Starts a piece of text displayed in a typewriter font. \n" + + " </kbd> \n" + + " \n" + + " <ul>\n" + + " <li>List item 1.</li>\n" + + " <li>List item 2.</li>\n" + + " <li>List item 3.</li>\n" + + " </ul>\n" + + " \n" + + " <var> Starts a piece of text displayed in an italic font.</var> \n" + + " \n" + + "\n" + + "<u>underlined \\b bold text - doxy commands are ignored inside 'htmlonly' section </u>\n" + + "\n" + + ""); + + wantedComments.put("doxygen_translate.doxygen_translate.htmlTableFunction(int)", + "The meaning of flags:\n" + + "\n" + + " @param byFlags bits marking required items:\n" + + " <table>\n" + + " <tr><th> Size in bits</th><th> Items Required </th></tr>\n" + + " <tr><td> 1 - 8 </td><td> 1 </td></tr>\n" + + " <tr><td> 9 - 16 </td><td> 2 </td></tr>\n" + + " <tr><td> 17 - 32 </td><td> 4 </td></tr>\n" + + " </table>\n" + + " Almost all combinations of above flags are supported by\n" + + " <code>htmlTable...</code> functions.\n" + + ""); + + + wantedComments.put("doxygen_translate.doxygen_translate.htmlEntitiesFunction(int, float)", + "All entities are treated as commands © ™ ®\n" + + "should work also<in text \n" + + "> \n" + + "& \n" + + "' \n" + + "" \n" + + "‘ \n" + + "’ \n" + + "“ \n" + + "” \n" + + "– \n" + + "— \n" + + " \n" + + "× \n" + + "− \n" + + "⋅ \n" + + "∼ \n" + + "≤ \n" + + "≥ \n" + + "← \n" + + "→ \n" + + "Not an html entity - ignored by Doxygen. \n" + + "Not an &text html entity - ampersand is replaced with entity.\n" + + ""); + + // and ask the parser to check comments for us + System.exit(parser.check(wantedComments)); + } +} diff --git a/Examples/test-suite/python/autodoc_runme.py b/Examples/test-suite/python/autodoc_runme.py index bf2fa621d..11e499d25 100644 --- a/Examples/test-suite/python/autodoc_runme.py +++ b/Examples/test-suite/python/autodoc_runme.py @@ -1,16 +1,14 @@ from autodoc import * +import comment_verifier +import inspect import sys - def check(got, expected, expected_builtin=None, skip=False): if not skip: expect = expected if is_python_builtin() and expected_builtin != None: expect = expected_builtin - if expect != got: - raise RuntimeError( - "\n" + "Expected: [" + str(expect) + "]\n" + "Got : [" + str(got) + "]") - + comment_verifier.check(got, expect) def is_new_style_class(cls): return hasattr(cls, "__class__") @@ -31,97 +29,35 @@ if is_fastproxy(dir()): # skip builtin check - the autodoc is missing, but it probably should not be skip = True -check(A.__doc__, "Proxy of C++ A class.", "::A") -check(A.funk.__doc__, "just a string.") -check(A.func0.__doc__, - "func0(self, arg2, hello) -> int", - "func0(arg2, hello) -> int") -check(A.func1.__doc__, - "func1(A self, short arg2, Tuple hello) -> int", - "func1(short arg2, Tuple hello) -> int") -check(A.func2.__doc__, - "\n" - " func2(self, arg2, hello) -> int\n" - "\n" - " Parameters\n" - " ----------\n" - " arg2: short\n" - " hello: int tuple[2]\n" - "\n" - " ", - "\n" - "func2(arg2, hello) -> int\n" +check(inspect.getdoc(A), "Proxy of C++ A class.", "::A") +check(inspect.getdoc(A.funk), "just a string.") +check(inspect.getdoc(A.func0), + "func0(self, arg2, hello) -> int") +check(inspect.getdoc(A.func1), + "func1(A self, short arg2, Tuple hello) -> int") +check(inspect.getdoc(A.func2), + "func2(self, arg2, hello) -> int\n" "\n" "Parameters\n" "----------\n" "arg2: short\n" - "hello: int tuple[2]\n" - "\n" - "" - ) -check(A.func3.__doc__, - "\n" - " func3(A self, short arg2, Tuple hello) -> int\n" - "\n" - " Parameters\n" - " ----------\n" - " arg2: short\n" - " hello: int tuple[2]\n" - "\n" - " ", - "\n" - "func3(short arg2, Tuple hello) -> int\n" + "hello: int tuple[2]") +check(inspect.getdoc(A.func3), + "func3(A self, short arg2, Tuple hello) -> int\n" "\n" "Parameters\n" "----------\n" "arg2: short\n" - "hello: int tuple[2]\n" - "\n" - "" - ) + "hello: int tuple[2]") -check(A.func0default.__doc__, - "\n" - " func0default(self, e, arg3, hello, f=2) -> int\n" - " func0default(self, e, arg3, hello) -> int\n" - " ", - "\n" - "func0default(e, arg3, hello, f=2) -> int\n" - "func0default(e, arg3, hello) -> int\n" - "" - ) -check(A.func1default.__doc__, - "\n" - " func1default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n" - " func1default(A self, A e, short arg3, Tuple hello) -> int\n" - " ", - "\n" - "func1default(A e, short arg3, Tuple hello, double f=2) -> int\n" - "func1default(A e, short arg3, Tuple hello) -> int\n" - "" - ) -check(A.func2default.__doc__, - "\n" - " func2default(self, e, arg3, hello, f=2) -> int\n" - "\n" - " Parameters\n" - " ----------\n" - " e: A *\n" - " arg3: short\n" - " hello: int tuple[2]\n" - " f: double\n" - "\n" - " func2default(self, e, arg3, hello) -> int\n" - "\n" - " Parameters\n" - " ----------\n" - " e: A *\n" - " arg3: short\n" - " hello: int tuple[2]\n" - "\n" - " ", - "\n" - "func2default(e, arg3, hello, f=2) -> int\n" +check(inspect.getdoc(A.func0default), + "func0default(self, e, arg3, hello, f=2) -> int\n" + "func0default(self, e, arg3, hello) -> int") +check(inspect.getdoc(A.func1default), + "func1default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n" + "func1default(A self, A e, short arg3, Tuple hello) -> int") +check(inspect.getdoc(A.func2default), + "func2default(self, e, arg3, hello, f=2) -> int\n" "\n" "Parameters\n" "----------\n" @@ -130,38 +66,15 @@ check(A.func2default.__doc__, "hello: int tuple[2]\n" "f: double\n" "\n" - "func2default(e, arg3, hello) -> int\n" + "func2default(self, e, arg3, hello) -> int\n" "\n" "Parameters\n" "----------\n" "e: A *\n" "arg3: short\n" - "hello: int tuple[2]\n" - "\n" - "" - ) -check(A.func3default.__doc__, - "\n" - " func3default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n" - "\n" - " Parameters\n" - " ----------\n" - " e: A *\n" - " arg3: short\n" - " hello: int tuple[2]\n" - " f: double\n" - "\n" - " func3default(A self, A e, short arg3, Tuple hello) -> int\n" - "\n" - " Parameters\n" - " ----------\n" - " e: A *\n" - " arg3: short\n" - " hello: int tuple[2]\n" - "\n" - " ", - "\n" - "func3default(A e, short arg3, Tuple hello, double f=2) -> int\n" + "hello: int tuple[2]") +check(inspect.getdoc(A.func3default), + "func3default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n" "\n" "Parameters\n" "----------\n" @@ -170,58 +83,21 @@ check(A.func3default.__doc__, "hello: int tuple[2]\n" "f: double\n" "\n" - "func3default(A e, short arg3, Tuple hello) -> int\n" + "func3default(A self, A e, short arg3, Tuple hello) -> int\n" "\n" "Parameters\n" "----------\n" "e: A *\n" "arg3: short\n" - "hello: int tuple[2]\n" - "\n" - "" - ) + "hello: int tuple[2]") -check(A.func0static.__doc__, - "\n" - " func0static(e, arg2, hello, f=2) -> int\n" - " func0static(e, arg2, hello) -> int\n" - " ", - "\n" +check(inspect.getdoc(A.func0static), "func0static(e, arg2, hello, f=2) -> int\n" - "func0static(e, arg2, hello) -> int\n" - "" - ) -check(A.func1static.__doc__, - "\n" - " func1static(A e, short arg2, Tuple hello, double f=2) -> int\n" - " func1static(A e, short arg2, Tuple hello) -> int\n" - " ", - "\n" + "func0static(e, arg2, hello) -> int") +check(inspect.getdoc(A.func1static), "func1static(A e, short arg2, Tuple hello, double f=2) -> int\n" - "func1static(A e, short arg2, Tuple hello) -> int\n" - "" - ) -check(A.func2static.__doc__, - "\n" - " func2static(e, arg2, hello, f=2) -> int\n" - "\n" - " Parameters\n" - " ----------\n" - " e: A *\n" - " arg2: short\n" - " hello: int tuple[2]\n" - " f: double\n" - "\n" - " func2static(e, arg2, hello) -> int\n" - "\n" - " Parameters\n" - " ----------\n" - " e: A *\n" - " arg2: short\n" - " hello: int tuple[2]\n" - "\n" - " ", - "\n" + "func1static(A e, short arg2, Tuple hello) -> int") +check(inspect.getdoc(A.func2static), "func2static(e, arg2, hello, f=2) -> int\n" "\n" "Parameters\n" @@ -237,31 +113,8 @@ check(A.func2static.__doc__, "----------\n" "e: A *\n" "arg2: short\n" - "hello: int tuple[2]\n" - "\n" - "" - ) -check(A.func3static.__doc__, - "\n" - " func3static(A e, short arg2, Tuple hello, double f=2) -> int\n" - "\n" - " Parameters\n" - " ----------\n" - " e: A *\n" - " arg2: short\n" - " hello: int tuple[2]\n" - " f: double\n" - "\n" - " func3static(A e, short arg2, Tuple hello) -> int\n" - "\n" - " Parameters\n" - " ----------\n" - " e: A *\n" - " arg2: short\n" - " hello: int tuple[2]\n" - "\n" - " ", - "\n" + "hello: int tuple[2]") +check(inspect.getdoc(A.func3static), "func3static(A e, short arg2, Tuple hello, double f=2) -> int\n" "\n" "Parameters\n" @@ -277,97 +130,78 @@ check(A.func3static.__doc__, "----------\n" "e: A *\n" "arg2: short\n" - "hello: int tuple[2]\n" - "\n" - "" - ) + "hello: int tuple[2]") if sys.version_info[0:2] > (2, 4): # Python 2.4 does not seem to work - check(A.variable_a.__doc__, + check(inspect.getdoc(A.variable_a), "A_variable_a_get(self) -> int", "A.variable_a" ) - check(A.variable_b.__doc__, + check(inspect.getdoc(A.variable_b), "A_variable_b_get(A self) -> int", "A.variable_b" ) - check(A.variable_c.__doc__, - "\n" + check(inspect.getdoc(A.variable_c), "A_variable_c_get(self) -> int\n" "\n" "Parameters\n" "----------\n" - "self: A *\n" - "\n", + "self: A *", "A.variable_c" - ) - check(A.variable_d.__doc__, - "\n" + ) + check(inspect.getdoc(A.variable_d), "A_variable_d_get(A self) -> int\n" "\n" "Parameters\n" "----------\n" - "self: A *\n" - "\n", + "self: A *", "A.variable_d" - ) + ) -check(B.__doc__, +check(inspect.getdoc(B), "Proxy of C++ B class.", "::B" ) -check(C.__init__.__doc__, "__init__(self, a, b, h) -> C", None, skip) -check(D.__init__.__doc__, +check(inspect.getdoc(C.__init__), "__init__(self, a, b, h) -> C", None, skip) +check(inspect.getdoc(D.__init__), "__init__(D self, int a, int b, Hola h) -> D", None, skip) -check(E.__init__.__doc__, +check(inspect.getdoc(E.__init__), + "__init__(self, a, b, h) -> E\n" "\n" - " __init__(self, a, b, h) -> E\n" + "__init__(self, a, b, h) -> E\n" "\n" - " Parameters\n" - " ----------\n" - " a: special comment for parameter a\n" - " b: another special comment for parameter b\n" - " h: enum Hola\n" - "\n" - " ", None, skip + "Parameters\n" + "----------\n" + "a: special comment for parameter a\n" + "b: another special comment for parameter b\n" + "h: enum Hola", None, skip ) -check(F.__init__.__doc__, +check(inspect.getdoc(F.__init__), + "__init__(F self, int a, int b, Hola h) -> F\n" "\n" - " __init__(F self, int a, int b, Hola h) -> F\n" + "__init__(F self, int a, int b, Hola h) -> F\n" "\n" - " Parameters\n" - " ----------\n" - " a: special comment for parameter a\n" - " b: another special comment for parameter b\n" - " h: enum Hola\n" - "\n" - " ", None, skip + "Parameters\n" + "----------\n" + "a: special comment for parameter a\n" + "b: another special comment for parameter b\n" + "h: enum Hola", None, skip ) -check(B.funk.__doc__, - "funk(B self, int c, int d) -> int", - "funk(int c, int d) -> int") -check(funk.__doc__, "funk(A e, short arg2, int c, int d) -> int") -check(funkdefaults.__doc__, - "\n" - " funkdefaults(A e, short arg2, int c, int d, double f=2) -> int\n" - " funkdefaults(A e, short arg2, int c, int d) -> int\n" - " ", - "\n" +check(inspect.getdoc(B.funk), + "funk(B self, int c, int d) -> int") +check(inspect.getdoc(funk), "funk(A e, short arg2, int c, int d) -> int") +check(inspect.getdoc(funkdefaults), "funkdefaults(A e, short arg2, int c, int d, double f=2) -> int\n" - "funkdefaults(A e, short arg2, int c, int d) -> int\n" - "" - ) + "funkdefaults(A e, short arg2, int c, int d) -> int") -check(func_input.__doc__, "func_input(int * INPUT) -> int") -check(func_output.__doc__, "func_output() -> int") -check(func_inout.__doc__, "func_inout(int * INOUT) -> int") -check(func_cb.__doc__, "func_cb(int c, int d) -> int") -check(banana.__doc__, "banana(S a, S b, int c, Integer d)") +check(inspect.getdoc(func_input), "func_input(int * INPUT) -> int") +check(inspect.getdoc(func_output), "func_output() -> int") +check(inspect.getdoc(func_inout), "func_inout(int * INOUT) -> int") +check(inspect.getdoc(func_cb), "func_cb(int c, int d) -> int") +check(inspect.getdoc(banana), "banana(S a, S b, int c, Integer d)") -check(TInteger.__doc__, "Proxy of C++ T< int > class.", "::T< int >") -check(TInteger.__init__.__doc__, "__init__(TInteger self) -> TInteger", None, skip) -check(TInteger.inout.__doc__, - "inout(TInteger self, TInteger t) -> TInteger", - "inout(TInteger t) -> TInteger") +check(inspect.getdoc(TInteger), "Proxy of C++ T< int > class.", "::T< int >") +check(inspect.getdoc(TInteger.__init__), "__init__(TInteger self) -> TInteger", None, skip) +check(inspect.getdoc(TInteger.inout), "inout(TInteger self, TInteger t) -> TInteger") diff --git a/Examples/test-suite/python/comment_verifier.py b/Examples/test-suite/python/comment_verifier.py new file mode 100644 index 000000000..57ac0b721 --- /dev/null +++ b/Examples/test-suite/python/comment_verifier.py @@ -0,0 +1,26 @@ +def check(got, expected, expected_builtin=None): + if got is None: # Absence of comment is equivalent to empty comment. + got = '' + + if got != expected: + import re + p = re.compile(r'^[+-]([^+-].*\S)?(\s+)$', re.M) + + def make_trailing_spaces_visible(str): + def replace_trailing_spaces(match): + res = match.group(0) + spaces = match.group(2) + if spaces is not None: + res = res + "{+%d trailing spaces}" % len(spaces) + return res + return re.sub(p, replace_trailing_spaces, str) + + from difflib import unified_diff + diff = unified_diff(expected.splitlines(True), + got.splitlines(True), "expected", "got") + lines = [] + for line in diff: + line = make_trailing_spaces_visible(line.strip("\r\n")) + lines.append(line + "\n") + + raise RuntimeError("Comments don't match:\n" + "".join(lines)) diff --git a/Examples/test-suite/python/doxygen_alias_runme.py b/Examples/test-suite/python/doxygen_alias_runme.py new file mode 100644 index 000000000..505261bcd --- /dev/null +++ b/Examples/test-suite/python/doxygen_alias_runme.py @@ -0,0 +1,10 @@ +import doxygen_alias +import inspect +import comment_verifier + +comment_verifier.check(inspect.getdoc(doxygen_alias.make_something), + """\ +A function returning something. + +:rtype: :py:class:`Something` +:return: A new object which may be None.""") diff --git a/Examples/test-suite/python/doxygen_basic_notranslate_runme.py b/Examples/test-suite/python/doxygen_basic_notranslate_runme.py new file mode 100644 index 000000000..81ac99975 --- /dev/null +++ b/Examples/test-suite/python/doxygen_basic_notranslate_runme.py @@ -0,0 +1,63 @@ +import doxygen_basic_notranslate +import inspect +import string +import sys +import comment_verifier + +comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function), + r"""\brief +Brief description. + +The comment text +\author Some author +\return Some number +\sa function2""" +) + +comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function2), + r"""A test of a very very very very very very very very very very very very very very very very +very very very very very long comment string.""" +) + +comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function3), + r"""*Overload 1:* + +A test for overloaded functions +This is function \b one + +| + +*Overload 2:* + +A test for overloaded functions +This is function \b two""" +) + +comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function4), + r"""A test of some mixed tag usage +\if CONDITION +This \a code fragment shows us something \. +\par Minuses: +\arg it's senseless +\arg it's stupid +\arg it's null + +\warning This may not work as expected + +\code +int main() { while(true); } +\endcode +\endif""" +) +comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function5), + r"""This is a post comment. """ +) +comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function6), + r"""Test for default args +@param a Some parameter, default is 42""" +) +comment_verifier.check(inspect.getdoc(doxygen_basic_notranslate.function7), + r"""Test for a parameter with difficult type +(mostly for python) +@param a Very strange param""" +) diff --git a/Examples/test-suite/python/doxygen_basic_translate_runme.py b/Examples/test-suite/python/doxygen_basic_translate_runme.py new file mode 100644 index 000000000..e664e06f6 --- /dev/null +++ b/Examples/test-suite/python/doxygen_basic_translate_runme.py @@ -0,0 +1,84 @@ +import doxygen_basic_translate +import inspect +import string +import sys +import comment_verifier + +comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function), + """\ +Brief description. + +The comment text. + +Author: Some author + +:rtype: int +:return: Some number + +See also: function2""" +) +comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function2), + """\ +A test of a very very very very very very very very very very very very very very very very +very very very very very long comment string.""" +) +comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function3), + """*Overload 1:* + +A test for overloaded functions +This is function **one** + +| + +*Overload 2:* + +A test for overloaded functions +This is function **two**""" +) +comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function4), + """\ +A test of some mixed tag usage +If: CONDITION { +This *code* fragment shows us something . +Title: Minuses: +* it\'s senseless +* it\'s stupid +* it\'s null + +Warning: This may not work as expected + +.. code-block:: c++ + + + int main() { while(true); } + +}""" +) +comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function5), + """This is a post comment.""" +) +comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function6), + """\ +Test for default args +:type a: int +:param a: Some parameter, default is 42""" +) +comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function7), + """\ +Test for a parameter with difficult type +(mostly for python) +:type a: :py:class:`Shape` +:param a: Very strange param""" +) + +comment_verifier.check(inspect.getdoc(doxygen_basic_translate.Atan2), + """\ +Multiple parameters test. + +:type y: float +:param y: Vertical coordinate. +:type x: float +:param x: Horizontal coordinate. +:rtype: float +:return: Arc tangent of ``y/x``.""" +) diff --git a/Examples/test-suite/python/doxygen_ignore_runme.py b/Examples/test-suite/python/doxygen_ignore_runme.py new file mode 100644 index 000000000..9a7b2e5df --- /dev/null +++ b/Examples/test-suite/python/doxygen_ignore_runme.py @@ -0,0 +1,17 @@ +import doxygen_ignore +import inspect +import comment_verifier + +comment_verifier.check(inspect.getdoc(doxygen_ignore.func), + """\ +A contrived example of ignoring too many commands in one comment. + + + + + + +This is specific to **Python**. + + +Command ignored, but anything here is still included.""") diff --git a/Examples/test-suite/python/doxygen_misc_constructs_runme.py b/Examples/test-suite/python/doxygen_misc_constructs_runme.py new file mode 100644 index 000000000..c441c3dfe --- /dev/null +++ b/Examples/test-suite/python/doxygen_misc_constructs_runme.py @@ -0,0 +1,133 @@ +import doxygen_misc_constructs +import inspect +import string +import sys +import comment_verifier + + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.getAddress), + r"""Returns address of file line. + +:type fileName: int +:param fileName: name of the file, where the source line is located +:type line: int +:param line: line number +:type isGetSize: boolean +:param isGetSize: if set, for every object location both address and size are returned + +Connection::getId() """) + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.CConnectionConfig), + r"""This class contains information for connection to winIDEA. Its methods +return reference to self, so we can use it like this: + +CConnectionConfig config = new CConnectionConfig(); +config.discoveryPort(5534).dllPath("C:\\myWinIDEA\\connect.dll").id("main"); + + +All parameters are optional. Set only what is required, default values are +used for unspecified parameters. + + + +advancedWinIDEALaunching.py Python example.""") + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.waitTime), + r"""Determines how long the ``isystem.connect`` should wait for running +instances to respond. Only one of ``lfWaitXXX`` flags from IConnect::ELaunchFlags +may be specified.""" +) + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.getConnection), + r"""This function returns connection id.""" +) + + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.getFirstLetter), + r'' +) + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.ClassWithNestedEnum), + r"""Class description.""" +) + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.showList), + r"""An example of a list in a documentation comment. + + - The first item of the list. + - The second list item, on + several indented lines, + showing that the indentation + is preserved. + - And the final list item after it. + +And this is not a list item any more.""" +) + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.isNoSpaceValidA), + r"""This comment without space after '*' is valid in Doxygen.""" +) + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.isNoSpaceValidB), + r""".This comment without space after '*' is valid in Doxygen.""" +) + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.isNoSpaceValidC), + r'' +) + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.backslashA), + r"""Backslash following``word`` is a valid doxygen command. Output contains +'followingword' with 'word' in code font.""" +) + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.backslashB), + r"""Doxy command without trailing space is ignored - nothing appears +on output. Standalone \ and '\' get to output. +Standalone @ and '@' get to output. +Commands "in quoted \b strings are treated as plain text". +Commands not recognized by Doxygen are ignored. +Backslashes in DOS paths d:and words +following them do not appear on output, we must quote them with +double quotes: "d:\xyz\qwe\myfile", "@something". Single quotes do not help: +'d:'. Escaping works: d:\xyz\qwe\myfile. Unix +paths of course have no such problems: /xyz/qwe/myfile +Commands for escaped symbols: +$ @ \ & ~ < > # % " . :: @text ::text""" +) + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.backslashC), + r"""Backslash e at end of *line* froze SWIG +*with* old comment parser. + +See also: MyClass::fun(char, + float)""" +) + + +comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.cycle), + r"""The next line contains expression: + +['retVal < 10', 'g_counter == 23 && g_mode & 3'] + + +Both words should be emphasized **isystem.connect**. +But not the last period. For **example**, comma should not be emphasized. +Similar **for**: double colon. + +Spaces at the start of line should be taken into account: +:type id: int +:param id: used as prefix in log + statements. The default value is empty string, which is OK if + there is only one app. instance. Example: + + ctrl.setBP("func1"); + + If we set the id to ``main_``, we get: + + main_ctrl.setBP("func1"); + + +:type fileName: string +:param fileName: name of the log file""" +); diff --git a/Examples/test-suite/python/doxygen_parsing_runme.py b/Examples/test-suite/python/doxygen_parsing_runme.py new file mode 100644 index 000000000..14579281d --- /dev/null +++ b/Examples/test-suite/python/doxygen_parsing_runme.py @@ -0,0 +1,64 @@ +import doxygen_parsing +import inspect +import string +import os +import sys +import comment_verifier + +comment_verifier.check(inspect.getdoc(doxygen_parsing.someFunction), + "The function comment") +comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeClass), + "The class comment") +comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeStruct), + "The struct comment") + +# There doesn't seem to be any way to specify the doc string for __init__ when +# using "-builtin" (see http://stackoverflow.com/q/11913492/15275), so skip +# this test in this case. +if str(os.environ.get('SWIG_FEATURES')).find('-builtin') == -1: + comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.__init__), + r"""*Overload 1:* +First overloaded constructor. + +| + +*Overload 2:* +Second overloaded constructor.""") + +comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethod), + r"""The class method comment. + +SomeAnotherClass#classMethodExtended(int, int) a link text""") +comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethodExtended), + r"""The class method with parameter + +:type a: int +:param a: Parameter a +:type b: int +:param b: Parameter b""" +) +comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethodExtended2), + r"""The class method with parameter + +:type a: int +:param a: Parameter a +:type b: int +:param b: Parameter b""" +) +comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethod), + r"""The struct method comment""") +comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethodExtended), + r"""The struct method with parameter + +:type a: int +:param a: Parameter a +:type b: int +:param b: Parameter b""" +) +comment_verifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethodExtended2), + r"""The struct method with parameter + +:type a: int +:param a: Parameter a +:type b: int +:param b: Parameter b""") diff --git a/Examples/test-suite/python/doxygen_translate_all_tags_runme.py b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py new file mode 100644 index 000000000..53d087e69 --- /dev/null +++ b/Examples/test-suite/python/doxygen_translate_all_tags_runme.py @@ -0,0 +1,306 @@ +import doxygen_translate_all_tags +import inspect +import string +import sys +import comment_verifier + + +comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func01), +r"""*Hello* + + + + + +* some list item + +This is attention! +You were warned! + +Authors: lots of them +Author: Zubr + +**boldword** + +Some brief description, +extended to many lines. + +Not everything works right now... +``codeword`` + + + + + +'citationword' + + +.. code-block:: c++ + + some test code""") + +comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func02), +r"""Conditional comment: SOMECONDITION +Some conditional comment +End of conditional comment. + + + + + + + +Copyright: some copyright + +1970 - 2012 + + + + + +Deprecated: Now use another function + +This is very large +and detailed description of some thing""") + +comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func03), +r"""Comment for **func03()**. + + + + + + + + + +*italicword* + +emphazedWord + + + +Example: someFile.txt +Some details on using the example""") + +comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func04), +r""":raises: SuperError + + + +:math:`\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}` + + +.. math:: + + \sqrt{(x_2-x_1)^2+(y_2-y_1)^2} + + + +.. math:: + + \sqrt{(x_2-x_1)^2+(y_2-y_1)^2} + + + + + + + + + + + + +This will only appear in hmtl""") + +comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func05), +r"""If: ANOTHERCONDITION { + First part of comment + If: SECONDCONDITION { + Nested condition text + }Else if: THIRDCONDITION { + The third condition text + }Else: { The last text block + } +}Else: { Second part of comment + If: CONDITION { + Second part extended + } +} + +If not: SOMECONDITION { + This is printed if not +} + +Image: testImage.bmp("Hello, world!") + + + + + + + + + + + +Some text +describing invariant.""") + +comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func06), +r"""Comment for **func06()**. + + + + +This will only appear in LATeX + + + + +* Some unordered list +* With lots of items +* lots of lots of items + + + + +someMember Some description follows + + + + +This will only appear in man""") + +comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func07), +r"""Comment for **func07()**. + + + + + + +Notes: Here +is the note! + +This is an overloaded member function, provided for convenience. +It differs from the above function only in what argument(s) it accepts. + +someword + + + + + +Title: The paragraph title +The paragraph text. +Maybe even multiline + + + +:type a: int +:param a: the first param""") + +comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func08), +r"""Text after anchor. + + + + + + +'Anchor description' + +'someAnchor' not quoted text is not part of ref tag + +'someAnchor' + + + + + + + + + +Remarks: Some remark text + +Another remarks section + +:rtype: void +:return: Whatever + +:rtype: void +:return: it + +:rtype: void +:return: may return""") + +comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func09), +r"""This will only appear in RTF + + +See also: someOtherMethod + + + +See also: function + +Same as +brief description + + + +Since: version 0.0.0.1 + + + + + + + + + + + + + + + +:raises: superException + +:raises: RuntimeError""") + +comment_verifier.check(inspect.getdoc(doxygen_translate_all_tags.func10), +r"""TODO: Some very important task + +:type b: float +:param b: B is mentioned again... + + + + + + + +very long +text with tags <sometag> + + + + +Version: 0.0.0.2 + +Warning: This is senseless! + + + + +This will only appear in XML + + +Here goes test of symbols: +$ @ \ & ~ < > # % " . :: + +And here goes simple text""") diff --git a/Examples/test-suite/python/doxygen_translate_links_runme.py b/Examples/test-suite/python/doxygen_translate_links_runme.py new file mode 100644 index 000000000..89f276f6e --- /dev/null +++ b/Examples/test-suite/python/doxygen_translate_links_runme.py @@ -0,0 +1,38 @@ +import doxygen_translate_links +import inspect +import string +import sys +import comment_verifier + + +comment_verifier.check(inspect.getdoc(doxygen_translate_links.function), +r"""Testing typenames converting in @ link + +superFunc(int,std::string) +Test for std_string member + + +superFunc(int,long,void*) +Test for simple types + + +superFunc(Shape::superType*) +Test for custom types + + +superFunc(int**[13]) +Test for complex types + + +same works for 'See also:' links: + +See also: superFunc(int,std::string) +See also: superFunc(int,long,void*) +See also: superFunc(Shape::superType*) +See also: superFunc(int**[13]) + +some failing params: + +See also: superFunc() +See also: superFunc() +See also: superFunc()""") diff --git a/Examples/test-suite/python/doxygen_translate_runme.py b/Examples/test-suite/python/doxygen_translate_runme.py new file mode 100644 index 000000000..2d0840a1f --- /dev/null +++ b/Examples/test-suite/python/doxygen_translate_runme.py @@ -0,0 +1,264 @@ +import doxygen_translate +import inspect +import string +import sys +import comment_verifier + + +comment_verifier.check(inspect.getdoc(doxygen_translate.function), +r"""*Hello* + +* some list item + +Authors: lots of them + +Author: Zubr + +**boldword** + +``codeword`` + +'citationword' + + +.. code-block:: c++ + + some test code + + +Conditional comment: SOMECONDITION +Some conditional comment +End of conditional comment. + +Copyright: some copyright + +Deprecated: Now use another function + +*italicword* + +Example: someFile.txt +Some details on using the example + +:raises: SuperError + +If: ANOTHERCONDITION { + First part of comment + If: SECONDCONDITION { + Nested condition text + }Else if: THIRDCONDITION { + The third condition text + }Else: { The last text block + } +}Else: { Second part of comment + If: CONDITION { + Second part extended + } +} + +If not: SOMECONDITION { + This is printed if not +} + +Image: testImage.bmp("Hello, world!") + + + +* Some unordered list +* With lots of items +* lots of lots of items + + + +someMember Some description follows + + + + + + +Notes: Here +is the note! + +This is an overloaded member function, provided for convenience. +It differs from the above function only in what argument(s) it accepts. + +someword + + + +Title: The paragraph title +The paragraph text. +Maybe even multiline + +:type a: int +:param a: the first param + +Remarks: Some remark text + +Another remarks section + +:rtype: int +:return: Whatever + +:rtype: int +:return: it + +:rtype: int +:return: may return + +See also: someOtherMethod + +See also: function + +Since: version 0.0.0.1 + +:raises: superException + +:raises: RuntimeError + +TODO: Some very important task + +:type b: float +:param b: B is mentioned again... + + +very long +text with tags <sometag> + + +Version: 0.0.0.2 + +Warning: This is senseless! + +Here goes test of symbols: +$ @ \ & ~ < > # % " . :: + +And here goes simple text""" +) + + + +comment_verifier.check(inspect.getdoc(doxygen_translate.htmlFunction), +r"""Test for html tags. See Doxygen doc for list of tags recognized by Doxygen. + +This is link ("http://acme.com/index.html") +**bold** +Quote: +Quotation block. + ("http://www.worldwildlife.org/who/index.html") + + +center +``this is code`` + + +Starts an item title. + Starts an item description. + + +Starts a piece of text displayed in a typewriter font. + +Starts a section with a specific style (HTML only) + +**Starts a piece of text displayed in an italic font.** + +'Form' does not generate any output. + +-------------------------------------------------------------------- + +# Heading 1 + +## Heading 2 + +### Heading 3 + +*Starts a piece of text displayed in an italic font.* +Input tag. +Image: src="slika.png" +Meta tag. +Multicol is ignored by doxygen. + + + +* List item 1. +* List item 2. + + + +Starts a new paragraph. + +Starts a preformatted fragment. + +Starts a section of text displayed in a smaller font. + +'Starts an inline text fragment with a specific style.' +**Starts a section of bold text.** + Starts a piece of text displayed in subscript. + Starts a piece of text displayed in superscript. + + +Animals +| Column 1 | Column 2 | +----------------------- +| cow | dog | +| cat | mouse | +| horse | parrot | + + +Starts a piece of text displayed in a typewriter font. + +Starts a piece of text displayed in a typewriter font. + + + +* List item 1. +* List item 2. +* List item 3. + + +*Starts a piece of text displayed in an italic font.* + + +<u>underlined \b bold text - doxy commands are ignored inside 'htmlonly' section </u>""") + + +comment_verifier.check(inspect.getdoc(doxygen_translate.htmlTableFunction), +r"""The meaning of flags: + +:type byFlags: int +:param byFlags: bits marking required items: + + | Size in bits| Items Required | + -------------------------------- + | 1 - 8 | 1 | + | 9 - 16 | 2 | + | 17 - 32 | 4 | + + Almost all combinations of above flags are supported by + ``htmlTable...`` functions.""") + + +comment_verifier.check(inspect.getdoc(doxygen_translate.htmlEntitiesFunction), +r"""All entities are treated as commands (C) TM (R) +should work also<in text +> +& +' +" +` +' +" +" +- +-- + +x +- +. +~ +<= +>= +<-- +--> +Not an html entity - ignored by Doxygen. +Not an &text html entity - ampersand is replaced with entity.""") diff --git a/Lib/python/boost_shared_ptr.i b/Lib/python/boost_shared_ptr.i index a4cde2581..709e7811d 100644 --- a/Lib/python/boost_shared_ptr.i +++ b/Lib/python/boost_shared_ptr.i @@ -398,6 +398,12 @@ #error "typemaps for $1_type not available" %} +%typemap(doctype) SWIG_SHARED_PTR_QNAMESPACE::shared_ptr< CONST TYPE >, + SWIG_SHARED_PTR_QNAMESPACE::shared_ptr< CONST TYPE > &, + SWIG_SHARED_PTR_QNAMESPACE::shared_ptr< CONST TYPE > *, + SWIG_SHARED_PTR_QNAMESPACE::shared_ptr< CONST TYPE > *& + %{TYPE%} + %template() SWIG_SHARED_PTR_QNAMESPACE::shared_ptr< CONST TYPE >; diff --git a/Lib/python/pydocs.swg b/Lib/python/pydocs.swg index 969af92aa..1eea41b8d 100644 --- a/Lib/python/pydocs.swg +++ b/Lib/python/pydocs.swg @@ -22,3 +22,24 @@ %typemap(doc) SWIGTYPE *INPUT, SWIGTYPE &INPUT "$1_name: $1_type (input)"; %typemap(doc) SWIGTYPE *OUTPUT, SWIGTYPE &OUTPUT "$1_name: $1_type (output)"; #endif + + +// Types to use in Python documentation for the parameters of the given C++ type. +%typemap(doctype) bool "boolean"; + +%define int_doctype_for_cppint_type(cppint_type) + %typemap(doctype) cppint_type, unsigned cppint_type "int"; +%enddef +%formacro(int_doctype_for_cppint_type, short, int, long, long long) + +%typemap(doctype) size_t "int"; + +%typemap(doctype) enum SWIGTYPE "int"; + +%typemap(doctype) float, double, long double "float"; + +%typemap(doctype) char*, std::string "string"; + +%typemap(doctype) SWIGTYPE "$1_basetype" +%typemap(doctype) SWIGTYPE * "$typemap(doctype, $*1_ltype)" +%typemap(doctype) SWIGTYPE & "$typemap(doctype, $*1_ltype)" diff --git a/Source/CParse/cparse.h b/Source/CParse/cparse.h index 8079805e4..c67ffeaba 100644 --- a/Source/CParse/cparse.h +++ b/Source/CParse/cparse.h @@ -28,6 +28,7 @@ extern "C" { extern int cparse_cplusplusout; extern int cparse_start_line; extern String *cparse_unknown_directive; + extern int scan_doxygen_comments; extern void Swig_cparse_cplusplus(int); extern void Swig_cparse_cplusplusout(int); @@ -61,7 +62,7 @@ extern "C" { extern void cparse_normalize_void(Node *); extern Parm *Swig_cparse_parm(String *s); extern ParmList *Swig_cparse_parms(String *s, Node *file_line_node); - extern Node *new_node(const_String_or_char_ptr tag); + extern Node *Swig_cparse_new_node(const_String_or_char_ptr tag); /* templ.c */ extern int Swig_cparse_template_expand(Node *n, String *rname, ParmList *tparms, Symtab *tscope); diff --git a/Source/CParse/cscanner.c b/Source/CParse/cscanner.c index 637ac9d60..4566817a0 100644 --- a/Source/CParse/cscanner.c +++ b/Source/CParse/cscanner.c @@ -50,6 +50,57 @@ static int last_brace = 0; static int last_id = 0; static int rename_active = 0; +/* Doxygen comments scanning */ +int scan_doxygen_comments = 0; + +int isStructuralDoxygen(String *s) { + static const char* const structuralTags[] = { + "addtogroup", + "callgraph", + "callergraph", + "category", + "def", + "defgroup", + "dir", + "example", + "file", + "headerfile", + "internal", + "mainpage", + "name", + "nosubgrouping", + "overload", + "package", + "page", + "protocol", + "relates", + "relatesalso", + "showinitializer", + "weakgroup", + }; + + unsigned n; + char *slashPointer = Strchr(s, '\\'); + char *atPointer = Strchr(s,'@'); + if (slashPointer == NULL && atPointer == NULL) + return 0; + else if(slashPointer == NULL) + slashPointer = atPointer; + + slashPointer++; /* skip backslash or at sign */ + + for (n = 0; n < sizeof(structuralTags)/sizeof(structuralTags[0]); n++) { + const size_t len = strlen(structuralTags[n]); + if (strncmp(slashPointer, structuralTags[n], len) == 0) { + /* Take care to avoid false positives with prefixes of other tags. */ + if (slashPointer[len] == '\0' || isspace(slashPointer[len])) + return 1; + } + } + + return 0; +} + /* ----------------------------------------------------------------------------- * Swig_cparse_cplusplus() * ----------------------------------------------------------------------------- */ @@ -367,10 +418,70 @@ static int yylook(void) { case SWIG_TOKEN_COMMENT: { - String *cmt = Scanner_text(scan); - char *loc = Char(cmt); - if ((strncmp(loc,"/*@SWIG",7) == 0) && (loc[Len(cmt)-3] == '@')) { - Scanner_locator(scan, cmt); + typedef enum { + DOX_COMMENT_PRE = -1, + DOX_COMMENT_NONE, + DOX_COMMENT_POST + } comment_kind_t; + comment_kind_t existing_comment = DOX_COMMENT_NONE; + + /* Concatenate or skip all consecutive comments at once. */ + do { + String *cmt = Scanner_text(scan); + char *loc = Char(cmt); + if ((strncmp(loc, "/*@SWIG", 7) == 0) && (loc[Len(cmt)-3] == '@')) { + Scanner_locator(scan, cmt); + } + if (scan_doxygen_comments) { /* else just skip this node, to avoid crashes in parser module*/ + /* Check for all possible Doxygen comment start markers while ignoring + comments starting with a row of asterisks or slashes just as + Doxygen itself does. */ + if (Len(cmt) > 3 && loc[0] == '/' && + ((loc[1] == '/' && ((loc[2] == '/' && loc[3] != '/') || loc[2] == '!')) || + (loc[1] == '*' && ((loc[2] == '*' && loc[3] != '*') || loc[2] == '!')))) { + comment_kind_t this_comment = loc[3] == '<' ? DOX_COMMENT_POST : DOX_COMMENT_PRE; + if (existing_comment != DOX_COMMENT_NONE && this_comment != existing_comment) { + /* We can't concatenate together Doxygen pre- and post-comments. */ + break; + } + + if (this_comment == DOX_COMMENT_POST || !isStructuralDoxygen(loc)) { + String *str; + + int begin = this_comment == DOX_COMMENT_POST ? 4 : 3; + int end = Len(cmt); + if (loc[end - 1] == '/' && loc[end - 2] == '*') { + end -= 2; + } + + str = NewStringWithSize(loc + begin, end - begin); + + if (existing_comment == DOX_COMMENT_NONE) { + yylval.str = str; + Setline(yylval.str, Scanner_start_line(scan)); + Setfile(yylval.str, Scanner_file(scan)); + } else { + Append(yylval.str, str); + } + + existing_comment = this_comment; + } + } + } + do { + tok = Scanner_token(scan); + } while (tok == SWIG_TOKEN_ENDLINE); + } while (tok == SWIG_TOKEN_COMMENT); + + Scanner_pushtoken(scan, tok, Scanner_text(scan)); + + switch (existing_comment) { + case DOX_COMMENT_PRE: + return DOXYGENSTRING; + case DOX_COMMENT_NONE: + break; + case DOX_COMMENT_POST: + return DOXYGENPOSTSTRING; } } break; @@ -907,6 +1018,8 @@ int yylex(void) { return (ID); case POUND: return yylex(); + case SWIG_TOKEN_COMMENT: + return yylex(); default: return (l); } diff --git a/Source/CParse/parser.y b/Source/CParse/parser.y index fc0d983fa..b9268cf03 100644 --- a/Source/CParse/parser.y +++ b/Source/CParse/parser.y @@ -65,6 +65,13 @@ static int cparse_externc = 0; int ignore_nested_classes = 0; int kwargs_supported = 0; /* ----------------------------------------------------------------------------- + * Doxygen Comment Globals + * ----------------------------------------------------------------------------- */ +static String *currentDeclComment = NULL; /* Comment of C/C++ declaration. */ +static Node *previousNode = NULL; /* Pointer to the previous node (for post comments) */ +static Node *currentNode = NULL; /* Pointer to the current node (for post comments) */ + +/* ----------------------------------------------------------------------------- * Assist Functions * ----------------------------------------------------------------------------- */ @@ -75,6 +82,14 @@ static void yyerror (const char *e) { (void)e; } +static Node *new_node(const_String_or_char_ptr tag) { + Node *n = Swig_cparse_new_node(tag); + /* Remember the previous node in case it will need a post-comment */ + previousNode = currentNode; + currentNode = n; + return n; +} + /* Copies a node. Does not copy tree links or symbol table data (except for sym:name) */ @@ -159,6 +174,36 @@ static Node *copy_node(Node *n) { return nn; } +static void set_comment(Node *n, String *comment) { + String *name; + Parm *p; + if (!n || !comment) + return; + + if (Getattr(n, "doxygen")) + Append(Getattr(n, "doxygen"), comment); + else { + Setattr(n, "doxygen", comment); + /* This is the first comment, populate it with @params, if any */ + p = Getattr(n, "parms"); + while (p) { + if (Getattr(p, "doxygen")) + Printv(comment, "\n@param ", Getattr(p, "name"), Getattr(p, "doxygen"), NIL); + p=nextSibling(p); + } + } + + /* Append same comment to every generated overload */ + name = Getattr(n, "name"); + if (!name) + return; + n = nextSibling(n); + while (n && Getattr(n, "name") && Strcmp(Getattr(n, "name"), name) == 0) { + Setattr(n, "doxygen", comment); + n = nextSibling(n); + } +} + /* ----------------------------------------------------------------------------- * Variables * ----------------------------------------------------------------------------- */ @@ -1553,6 +1598,9 @@ static String *add_qualifier_to_declarator(SwigType *type, SwigType *qualifier) %token <str> CONVERSIONOPERATOR %token PARSETYPE PARSEPARM PARSEPARMS +%token <str> DOXYGENSTRING +%token <str> DOXYGENPOSTSTRING + %left CAST %left QUESTIONMARK %left LOR @@ -1579,11 +1627,11 @@ static String *add_qualifier_to_declarator(SwigType *type, SwigType *qualifier) /* C declarations */ %type <node> c_declaration c_decl c_decl_tail c_enum_key c_enum_inherit c_enum_decl c_enum_forward_decl c_constructor_decl; -%type <node> enumlist edecl; +%type <node> enumlist enumlist_tail enumlist_item edecl_with_dox edecl; /* C++ declarations */ %type <node> cpp_declaration cpp_class_decl cpp_forward_class_decl cpp_template_decl cpp_alternate_rettype; -%type <node> cpp_members cpp_member; +%type <node> cpp_members cpp_member cpp_member_no_dox; %type <node> cpp_constructor_decl cpp_destructor_decl cpp_protection_decl cpp_conversion_operator cpp_static_assert; %type <node> cpp_swig_directive cpp_template_possible cpp_opt_declarators ; %type <node> cpp_using_decl cpp_namespace_decl cpp_catch_decl cpp_lambda_decl; @@ -1595,7 +1643,7 @@ static String *add_qualifier_to_declarator(SwigType *type, SwigType *qualifier) %type <id> storage_class extern_string; %type <pl> parms ptail rawparms varargs_parms ; %type <pl> templateparameters templateparameterstail; -%type <p> parm valparm rawvalparms valparms valptail ; +%type <p> parm_no_dox parm valparm rawvalparms valparms valptail ; %type <p> typemap_parm tm_list tm_tail ; %type <p> templateparameter ; %type <id> templcpptype cpptype classkey classkeyopt access_specifier; @@ -1628,7 +1676,6 @@ static String *add_qualifier_to_declarator(SwigType *type, SwigType *qualifier) %type <node> featattr; %type <node> lambda_introducer lambda_body; %type <pl> lambda_tail; -%type <node> optional_constant_directive; %type <str> virt_specifier_seq virt_specifier_seq_opt; %% @@ -1675,9 +1722,24 @@ program : interface { interface : interface declaration { /* add declaration to end of linked list (the declaration isn't always a single declaration, sometimes it is a linked list itself) */ + if (currentDeclComment != NULL) { + set_comment($2, currentDeclComment); + currentDeclComment = NULL; + } appendChild($1,$2); $$ = $1; } + | interface DOXYGENSTRING { + currentDeclComment = $2; + $$ = $1; + } + | interface DOXYGENPOSTSTRING { + Node *node = lastChild($1); + if (node) { + set_comment(node, $2); + } + $$ = $1; + } | empty { $$ = new_node("top"); } @@ -4553,7 +4615,7 @@ cpp_members : cpp_member cpp_members { /* A class member. May be data or a function. Static or virtual as well */ -cpp_member : c_declaration { $$ = $1; } +cpp_member_no_dox : c_declaration { $$ = $1; } | cpp_constructor_decl { $$ = $1; if (extendmode && current_class) { @@ -4587,6 +4649,18 @@ cpp_member : c_declaration { $$ = $1; } | fragment_directive {$$ = $1; } | types_directive {$$ = $1; } | SEMI { $$ = 0; } + +cpp_member : cpp_member_no_dox { + $$ = $1; + } + | DOXYGENSTRING cpp_member_no_dox { + $$ = $2; + set_comment($2, $1); + } + | cpp_member_no_dox DOXYGENPOSTSTRING { + $$ = $1; + set_comment($1, $2); + } ; /* Possibly a constructor */ @@ -4974,20 +5048,31 @@ rawparms : parm ptail { set_nextSibling($1,$2); $$ = $1; } - | empty { $$ = 0; } + | empty { + $$ = 0; + previousNode = currentNode; + currentNode=0; + } ; ptail : COMMA parm ptail { set_nextSibling($2,$3); $$ = $2; } + | COMMA DOXYGENPOSTSTRING parm ptail { + set_comment(previousNode, $2); + set_nextSibling($3, $4); + $$ = $3; + } | empty { $$ = 0; } ; -parm : rawtype parameter_declarator { +parm_no_dox : rawtype parameter_declarator { SwigType_push($1,$2.type); $$ = NewParmWithoutFileLineInfo($1,$2.id); + previousNode = currentNode; + currentNode = $$; Setfile($$,cparse_file); Setline($$,cparse_line); if ($2.defarg) { @@ -4997,6 +5082,8 @@ parm : rawtype parameter_declarator { | TEMPLATE LESSTHAN cpptype GREATERTHAN cpptype idcolon def_args { $$ = NewParmWithoutFileLineInfo(NewStringf("template<class> %s %s", $5,$6), 0); + previousNode = currentNode; + currentNode = $$; Setfile($$,cparse_file); Setline($$,cparse_line); if ($7.val) { @@ -5006,11 +5093,26 @@ parm : rawtype parameter_declarator { | PERIOD PERIOD PERIOD { SwigType *t = NewString("v(...)"); $$ = NewParmWithoutFileLineInfo(t, 0); + previousNode = currentNode; + currentNode = $$; Setfile($$,cparse_file); Setline($$,cparse_line); } ; +parm : parm_no_dox { + $$ = $1; + } + | DOXYGENSTRING parm_no_dox { + $$ = $2; + set_comment($2, $1); + } + | parm_no_dox DOXYGENPOSTSTRING { + $$ = $1; + set_comment($1, $2); + } + ; + valparms : rawvalparms { Parm *p; $$ = $1; @@ -6217,28 +6319,70 @@ ename : identifier { $$ = $1; } | empty { $$ = (char *) 0;} ; -optional_constant_directive : constant_directive { $$ = $1; } - | empty { $$ = 0; } - ; +optional_ignored_define + : constant_directive + | empty + ; + +optional_ignored_define_after_comma + : empty + | COMMA + | COMMA constant_directive + ; /* Enum lists - any #define macros (constant directives) within the enum list are ignored. Trailing commas accepted. */ -enumlist : enumlist COMMA optional_constant_directive edecl optional_constant_directive { - Node *leftSibling = Getattr($1,"_last"); - set_nextSibling(leftSibling,$4); - Setattr($1,"_last",$4); - $$ = $1; - } - | enumlist COMMA optional_constant_directive { - $$ = $1; - } - | optional_constant_directive edecl optional_constant_directive { - Setattr($2,"_last",$2); - $$ = $2; - } - | optional_constant_directive { - $$ = 0; - } - ; +enumlist : enumlist_item optional_ignored_define_after_comma { + Setattr($1,"_last",$1); + $$ = $1; + } + | enumlist_item enumlist_tail optional_ignored_define_after_comma { + set_nextSibling($1, $2); + Setattr($1,"_last",Getattr($2,"_last")); + Setattr($2,"_last",NULL); + $$ = $1; + } + | optional_ignored_define { + $$ = 0; + } + ; + +enumlist_tail : COMMA enumlist_item { + Setattr($2,"_last",$2); + $$ = $2; + } + | enumlist_tail COMMA enumlist_item { + set_nextSibling(Getattr($1,"_last"), $3); + Setattr($1,"_last",$3); + $$ = $1; + } + ; + +enumlist_item : optional_ignored_define edecl_with_dox optional_ignored_define { + $$ = $2; + } + ; + +edecl_with_dox : edecl { + $$ = $1; + } + | DOXYGENSTRING edecl { + $$ = $2; + set_comment($2, $1); + } + | edecl DOXYGENPOSTSTRING { + $$ = $1; + set_comment($1, $2); + } + | DOXYGENPOSTSTRING edecl { + $$ = $2; + set_comment(previousNode, $1); + } + | DOXYGENPOSTSTRING edecl DOXYGENPOSTSTRING { + $$ = $2; + set_comment(previousNode, $1); + set_comment($2, $3); + } + ; edecl : identifier { SwigType *type = NewSwigType(T_INT); diff --git a/Source/CParse/util.c b/Source/CParse/util.c index 0e2136a49..714bb2972 100644 --- a/Source/CParse/util.c +++ b/Source/CParse/util.c @@ -112,12 +112,12 @@ void cparse_normalize_void(Node *n) { } /* ----------------------------------------------------------------------------- - * new_node() + * Swig_cparse_new_node() * * Create an empty parse node, setting file and line number information * ----------------------------------------------------------------------------- */ -Node *new_node(const_String_or_char_ptr tag) { +Node *Swig_cparse_new_node(const_String_or_char_ptr tag) { Node *n = NewHash(); set_nodeType(n,tag); Setfile(n,cparse_file); diff --git a/Source/Doxygen/doxycommands.h b/Source/Doxygen/doxycommands.h new file mode 100644 index 000000000..1f7b5fa5b --- /dev/null +++ b/Source/Doxygen/doxycommands.h @@ -0,0 +1,170 @@ +/* ----------------------------------------------------------------------------- + * This file is part of SWIG, which is licensed as a whole under version 3 + * (or any later version) of the GNU General Public License. Some additional + * terms also apply to certain portions of SWIG. The full details of the SWIG + * license and copyrights can be found in the LICENSE and COPYRIGHT files + * included with the SWIG source code as distributed by the SWIG developers + * and at http://www.swig.org/legal.html. + * + * doxycommands.h + * + * Part of the Doxygen comment translation module of SWIG. + * ----------------------------------------------------------------------------- */ + +#ifndef DOXYGENCOMMANDS_H +#define DOXYGENCOMMANDS_H + +// doxy commands are not processed inside this block +const char *CMD_HTML_ONLY = "htmlonly"; +// doxy commands are not processed inside this block +const char *CMD_VERBATIM = "verbatim"; +const char *CMD_LATEX_1 = "f$"; +const char *CMD_LATEX_2 = "f{"; +const char *CMD_LATEX_3 = "f["; +const char *CMD_END_HTML_ONLY = "endhtmlonly"; +const char *CMD_END_VERBATIM = "endverbatim"; +const char *CMD_END_LATEX_1 = "f$"; +const char *CMD_END_LATEX_2 = "f}"; +const char *CMD_END_LATEX_3 = "f]"; + +const char *sectionIndicators[] = { + "attention", "author", "authors", "brief", "bug", "cond", "date", + "deprecated", "details", "else", "elseif", "endcond", "endif", + "exception", "if", "ifnot", "invariant", "note", "par", "param", + "tparam", "post", "pre", "remarks", "remark", "result", "return", + "returns", "retval", "sa", "see", "since", "test", "throw", "throws", + "todo", "version", "warning", "xrefitem" +}; + +const int sectionIndicatorsSize = sizeof(sectionIndicators) / sizeof(*sectionIndicators); + +/* All of the doxygen commands divided up by how they are parsed */ +const char *simpleCommands[] = { + // the first line are escaped chars, except \~, which is a language ID command. + "n", "$", "@", "\\", "&", "~", "<", ">", "#", "%", "\"", ".", "::", + "endcond", + "callgraph", "callergraph", "showinitializer", "hideinitializer", "internal", + "nosubgrouping", "public", "publicsection", "private", "privatesection", + "protected", "protectedsection", "tableofcontents" +}; + +const int simpleCommandsSize = sizeof(simpleCommands) / sizeof(*simpleCommands); + +const char *commandWords[] = { + "a", "b", "c", "e", "em", "p", "def", "enum", "package", "relates", + "namespace", "relatesalso", "anchor", "dontinclude", "include", + "includelineno", "copydoc", "copybrief", "copydetails", "verbinclude", + "htmlinclude", "extends", "implements", "memberof", "related", "relatedalso", + "cite" +}; + +const int commandWordsSize = sizeof(commandWords) / sizeof(*commandWords); + +const char *commandLines[] = { + "addindex", "fn", "name", "line", "var", "skipline", "typedef", "skip", + "until", "property" +}; + +const int commandLinesSize = sizeof(commandLines) / sizeof(*commandLines); + +const char *commandParagraph[] = { + "partofdescription", "result", "return", "returns", "remarks", "remark", + "since", "test", "sa", "see", "pre", "post", "details", "invariant", + "deprecated", "date", "note", "warning", "version", "todo", "bug", + "attention", "brief", "author", "authors", "copyright", "short" +}; + +const int commandParagraphSize = sizeof(commandParagraph) / sizeof(*commandParagraph); + +const char *commandEndCommands[] = { + CMD_HTML_ONLY, "latexonly", "manonly", "xmlonly", "link", "rtfonly" +}; + +const int commandEndCommandsSize = sizeof(commandEndCommands) / sizeof(*commandEndCommands); + +const char *commandWordParagraphs[] = { + "param", "tparam", "throw", "throws", "retval", "exception", "example" +}; + +const int commandWordParagraphsSize = sizeof(commandWordParagraphs) / sizeof(*commandWordParagraphs); + +const char *commandWordLines[] = { + "page", "subsection", "subsubsection", "section", "paragraph", "defgroup", + "snippet", "mainpage" +}; + +const int commandWordLinesSize = sizeof(commandWordLines) / sizeof(*commandWordLines); + +const char *commandWordOWordOWords[] = { + "category", "class", "protocol", "interface", "struct", "union" +}; + +const int commandWordOWordOWordsSize = sizeof(commandWordOWordOWords) / sizeof(*commandWordOWordOWords); + +const char *commandOWords[] = { + "dir", "file", "cond" +}; + +const int commandOWordsSize = sizeof(commandOWords) / sizeof(*commandOWords); + +const char *commandErrorThrowings[] = { + "annotatedclassstd::list", "classhierarchy", "define", "functionindex", "header", + "headerfilestd::list", "inherit", "l", "postheader", "endcode", "enddot", "endmsc", "endhtmlonly", + "endlatexonly", "endmanonly", "endlink", "endverbatim", "endxmlonly", "f]", "f}", "endif", "else", + "endrtfonly" +}; + +const int commandErrorThrowingsSize = sizeof(commandErrorThrowings) / sizeof(*commandErrorThrowings); + +const char *commandUniques[] = { + "xrefitem", "arg", "ingroup", "par", "headerfile", "overload", "weakgroup", "ref", "subpage", "dotfile", "image", "addtogroup", "li", + "if", "ifnot", "elseif", "else", "mscfile", "code", CMD_VERBATIM, "f{", "f[", "f$", "dot", "msc" +}; + +const int commandUniquesSize = sizeof(commandUniques) / sizeof(*commandUniques); + +// These HTML commands are transformed when producing output in other formats. +// Other commands are left intact, but '<' and '> are replaced with entities in HTML +// output. So <varName> appears as <varName> in HTML output. The same +// behavior must be repeated by SWIG. See Doxygen doc for the list of commands. +// '<' is prepended to distinguish HTML tags from Doxygen commands. +const char *commandHtml[] = { + "<a", "<b", "<blockquote", "<body", "<br", "<center", "<caption", "<code", "<dd", "<dfn", + "<div", "<dl", "<dt", "<em", "<form", "<hr", "<h1", "<h2", "<h3", "<i", "<input", "<img", + "<li", "<meta", "<multicol", "<ol", "<p", "<pre", "<small", "<span", "<strong", + "<sub", "<sup", "<table", "<td", "<th", "<tr", "<tt", "<kbd", "<ul", "<var" +}; + +const int commandHtmlSize = sizeof(commandHtml) / sizeof(*commandHtml); + +// Only entities which are translatable to plain text are used here. Others +// are copied unchanged to output. +const char *commandHtmlEntities[] = { + "©", // (C) + "&trade", // (TM) + "®", // (R) + "<", // less-than symbol + ">", // greater-than symbol + "&", // ampersand + "&apos", // single quotation mark (straight) + """, // double quotation mark (straight) + "&lsquo", // left single quotation mark + "&rsquo", // right single quotation mark + "&ldquo", // left double quotation mark + "&rdquo", // right double quotation mark + "&ndash", // n-dash (for numeric ranges, e.g. 2–8) + "&mdash", // -- + " ", // + "×", // x + "&minus", // - + "&sdot", // . + "&sim", // ~ + "&le", // <= + "&ge", // >= + "&larr", // <-- + "&rarr" // --> +}; + +const int commandHtmlEntitiesSize = sizeof(commandHtmlEntities) / sizeof(*commandHtmlEntities); + +#endif diff --git a/Source/Doxygen/doxyentity.cxx b/Source/Doxygen/doxyentity.cxx new file mode 100644 index 000000000..8b9f65736 --- /dev/null +++ b/Source/Doxygen/doxyentity.cxx @@ -0,0 +1,69 @@ +/* ----------------------------------------------------------------------------- + * This file is part of SWIG, which is licensed as a whole under version 3 + * (or any later version) of the GNU General Public License. Some additional + * terms also apply to certain portions of SWIG. The full details of the SWIG + * license and copyrights can be found in the LICENSE and COPYRIGHT files + * included with the SWIG source code as distributed by the SWIG developers + * and at http://www.swig.org/legal.html. + * + * doxyentity.cxx + * + * Part of the Doxygen comment translation module of SWIG. + * ----------------------------------------------------------------------------- */ + +#include "doxyentity.h" +#include <iostream> + +using std::cout; + +DoxygenEntity::DoxygenEntity(const std::string &typeEnt):typeOfEntity(typeEnt), isLeaf(true) { +} + + +/* Basic node for commands that have + * only 1 item after them + * example: \b word + * OR holding a std::string + */ +DoxygenEntity::DoxygenEntity(const std::string &typeEnt, const std::string ¶m1) : typeOfEntity(typeEnt), data(param1), isLeaf(true) { +} + + +/* Nonterminal node + * contains + */ +DoxygenEntity::DoxygenEntity(const std::string &typeEnt, const DoxygenEntityList &entList) : typeOfEntity(typeEnt), isLeaf(false), entityList(entList) { +} + + +void DoxygenEntity::printEntity(int level) const { + + int thisLevel = level; + + if (isLeaf) { + for (int i = 0; i < thisLevel; i++) { + cout << "\t"; + } + + cout << "Node Leaf Command: '" << typeOfEntity << "', "; + + if (!data.empty()) { + cout << "Node Data: '" << data << "'"; + } + cout << std::endl; + + } else { + + for (int i = 0; i < thisLevel; i++) { + cout << "\t"; + } + + cout << "Node Command: '" << typeOfEntity << "'" << std::endl; + + thisLevel++; + + for (DoxygenEntityListCIt p = entityList.begin(); p != entityList.end(); p++) { + p->printEntity(thisLevel); + } + } +} diff --git a/Source/Doxygen/doxyentity.h b/Source/Doxygen/doxyentity.h new file mode 100644 index 000000000..93737e604 --- /dev/null +++ b/Source/Doxygen/doxyentity.h @@ -0,0 +1,45 @@ +/* ----------------------------------------------------------------------------- + * This file is part of SWIG, which is licensed as a whole under version 3 + * (or any later version) of the GNU General Public License. Some additional + * terms also apply to certain portions of SWIG. The full details of the SWIG + * license and copyrights can be found in the LICENSE and COPYRIGHT files + * included with the SWIG source code as distributed by the SWIG developers + * and at http://www.swig.org/legal.html. + * + * doxyentity.h + * + * Part of the Doxygen comment translation module of SWIG. + * ----------------------------------------------------------------------------- */ + +#ifndef DOXYGENENTITY_H_ +#define DOXYGENENTITY_H_ + +#include <string> +#include <list> + + +class DoxygenEntity; + +typedef std::list<DoxygenEntity> DoxygenEntityList; +typedef DoxygenEntityList::iterator DoxygenEntityListIt; +typedef DoxygenEntityList::const_iterator DoxygenEntityListCIt; + + +/* + * Structure to represent a doxygen comment entry + */ +class DoxygenEntity { +public: + std::string typeOfEntity; + std::string data; + bool isLeaf; + DoxygenEntityList entityList; + + DoxygenEntity(const std::string &typeEnt); + DoxygenEntity(const std::string &typeEnt, const std::string ¶m1); + DoxygenEntity(const std::string &typeEnt, const DoxygenEntityList &entList); + + void printEntity(int level) const; +}; + +#endif diff --git a/Source/Doxygen/doxyparser.cxx b/Source/Doxygen/doxyparser.cxx new file mode 100644 index 000000000..7286adeb0 --- /dev/null +++ b/Source/Doxygen/doxyparser.cxx @@ -0,0 +1,1421 @@ +/* ----------------------------------------------------------------------------- + * This file is part of SWIG, which is licensed as a whole under version 3 + * (or any later version) of the GNU General Public License. Some additional + * terms also apply to certain portions of SWIG. The full details of the SWIG + * license and copyrights can be found in the LICENSE and COPYRIGHT files + * included with the SWIG source code as distributed by the SWIG developers + * and at http://www.swig.org/legal.html. + * + * doxyparser.cxx + * ----------------------------------------------------------------------------- */ + +#include "doxyparser.h" +#include "doxycommands.h" +#include "swig.h" +#include "swigwarn.h" + +#include <iostream> +#include <algorithm> +#include <vector> + +using std::string; +using std::cout; +using std::endl; + +// This constant defines the (only) characters valid inside a Doxygen "word". +// It includes some unusual ones because of the commands such as \f[, \f{, \f], +// \f} and \f$. +static const char *DOXYGEN_WORD_CHARS = "abcdefghijklmnopqrstuvwxyz" "ABCDEFGHIJKLMNOPQRSTUVWXYZ" "0123456789" "$[]{}"; + +// Define static class members +DoxygenParser::DoxyCommandsMap DoxygenParser::doxygenCommands; +std::set<std::string> DoxygenParser::doxygenSectionIndicators; + +const int TOKENSPERLINE = 8; //change this to change the printing behaviour of the token list +const std::string END_HTML_TAG_MARK("/"); + +DoxygenParser::DoxygenParser(bool noisy) : noisy(noisy) { + fillTables(); +} + +DoxygenParser::~DoxygenParser() { +} + +void DoxygenParser::fillTables() { + // run it only once + if (doxygenCommands.size()) + return; + + // fill in tables with data from doxycommands.h + for (int i = 0; i < simpleCommandsSize; i++) + doxygenCommands[simpleCommands[i]] = SIMPLECOMMAND; + + for (int i = 0; i < commandWordsSize; i++) + doxygenCommands[commandWords[i]] = COMMANDWORD; + + for (int i = 0; i < commandLinesSize; i++) + doxygenCommands[commandLines[i]] = COMMANDLINE; + + for (int i = 0; i < commandParagraphSize; i++) + doxygenCommands[commandParagraph[i]] = COMMANDPARAGRAPH; + + for (int i = 0; i < commandEndCommandsSize; i++) + doxygenCommands[commandEndCommands[i]] = COMMANDENDCOMMAND; + + for (int i = 0; i < commandWordParagraphsSize; i++) + doxygenCommands[commandWordParagraphs[i]] = COMMANDWORDPARAGRAPH; + + for (int i = 0; i < commandWordLinesSize; i++) + doxygenCommands[commandWordLines[i]] = COMMANDWORDLINE; + + for (int i = 0; i < commandWordOWordOWordsSize; i++) + doxygenCommands[commandWordOWordOWords[i]] = COMMANDWORDOWORDWORD; + + for (int i = 0; i < commandOWordsSize; i++) + doxygenCommands[commandOWords[i]] = COMMANDOWORD; + + for (int i = 0; i < commandErrorThrowingsSize; i++) + doxygenCommands[commandErrorThrowings[i]] = COMMANDERRORTHROW; + + for (int i = 0; i < commandUniquesSize; i++) + doxygenCommands[commandUniques[i]] = COMMANDUNIQUE; + + for (int i = 0; i < commandHtmlSize; i++) + doxygenCommands[commandHtml[i]] = COMMAND_HTML; + + for (int i = 0; i < commandHtmlEntitiesSize; i++) + doxygenCommands[commandHtmlEntities[i]] = COMMAND_HTML_ENTITY; + + // fill section indicators command set + for (int i = 0; i < sectionIndicatorsSize; i++) + doxygenSectionIndicators.insert(sectionIndicators[i]); +} + +std::string DoxygenParser::stringToLower(const std::string &stringToConvert) { + + string result(stringToConvert.size(), ' '); + + for (size_t i = 0; i < result.size(); i++) { + result[i] = tolower(stringToConvert[i]); + } + + return result; +} + +bool DoxygenParser::isSectionIndicator(const std::string &smallString) { + + std::set<std::string>::iterator it = doxygenSectionIndicators.find(stringToLower(smallString)); + + return it != doxygenSectionIndicators.end(); +} + +void DoxygenParser::printTree(const DoxygenEntityList &rootList) { + DoxygenEntityList::const_iterator p = rootList.begin(); + while (p != rootList.end()) { + (*p).printEntity(0); + p++; + } +} + +DoxygenParser::DoxyCommandEnum DoxygenParser::commandBelongs(const std::string &theCommand) { + DoxyCommandsMapIt it = doxygenCommands.find(stringToLower(theCommand)); + + if (it != doxygenCommands.end()) { + return it->second; + } + // Check if this command is defined as an alias. + if (Getattr(m_node, ("feature:doxygen:alias:" + theCommand).c_str())) { + return COMMAND_ALIAS; + } + // Check if this command should be ignored. + if (String *const ignore = getIgnoreFeature(theCommand)) { + // Check that no value is specified for this feature ("1" is the implicit + // one given to it by SWIG itself), we may use the value in the future, but + // for now we only use the attributes. + if (Strcmp(ignore, "1") != 0) { + Swig_warning(WARN_PP_UNEXPECTED_TOKENS, m_fileName.c_str(), m_fileLineNo, + "Feature \"doxygen:ignore\" value ignored for Doxygen command \"%s\".\n", theCommand.c_str()); + } + // Also ensure that the matching end command, if any, will be recognized. + const string endCommand = getIgnoreFeatureEndCommand(theCommand); + if (!endCommand.empty()) { + Setattr(m_node, ("feature:doxygen:ignore:" + endCommand).c_str(), NewString("1")); + } + + return COMMAND_IGNORE; + } + + return NONE; +} + +std::string DoxygenParser::trim(const std::string &text) { + size_t start = text.find_first_not_of(" \t"); + size_t end = text.find_last_not_of(" \t"); + + if (start == string::npos || start > end) { + return ""; + } + return text.substr(start, end - start + 1); +} + +bool DoxygenParser::isEndOfLine() { + if (m_tokenListIt == m_tokenList.end()) { + return false; + } + Token nextToken = *m_tokenListIt; + return nextToken.m_tokenType == END_LINE; +} + +void DoxygenParser::skipWhitespaceTokens() { + if (m_tokenListIt == m_tokenList.end()) { + return; + } + + while (m_tokenListIt != m_tokenList.end() + && (m_tokenListIt->m_tokenType == END_LINE || trim(m_tokenListIt->m_tokenString).empty())) { + + m_tokenListIt++; + } +} + +std::string DoxygenParser::getNextToken() { + + if (m_tokenListIt == m_tokenList.end()) { + return ""; + } + + if (m_tokenListIt->m_tokenType == PLAINSTRING) { + return (m_tokenListIt++)->m_tokenString; + } + + return ""; +} + +std::string DoxygenParser::getNextWord() { + + /* if (m_tokenListIt == m_tokenList.end()) { + return ""; + } + */ + while (m_tokenListIt != m_tokenList.end() + && (m_tokenListIt->m_tokenType == PLAINSTRING)) { + // handle quoted strings as words + string token = m_tokenListIt->m_tokenString; + if (token == "\"") { + + string word = m_tokenListIt->m_tokenString; + m_tokenListIt++; + while (true) { + string nextWord = getNextToken(); + if (nextWord.empty()) { // maybe report unterminated string error + return word; + } + word += nextWord; + if (nextWord == "\"") { + return word; + } + } + } + + string tokenStr = trim(m_tokenListIt->m_tokenString); + m_tokenListIt++; + if (!tokenStr.empty()) { + return tokenStr; + } + } + + return ""; +} + +DoxygenParser::TokenListCIt DoxygenParser::getOneLine(const TokenList &tokList) { + + TokenListCIt endOfLineIt = m_tokenListIt; + + while (endOfLineIt != tokList.end()) { + if (endOfLineIt->m_tokenType == END_LINE) { + return endOfLineIt; + } + endOfLineIt++; + } + + return tokList.end(); +} + +std::string DoxygenParser::getStringTilCommand(const TokenList &tokList) { + + if (m_tokenListIt == tokList.end()) { + return ""; + } + + string description; + + while (m_tokenListIt->m_tokenType == PLAINSTRING) { + const Token ¤tToken = *m_tokenListIt++; + if (currentToken.m_tokenType == PLAINSTRING) { + description = description + currentToken.m_tokenString; // + " "; + } + } + return description; +} + +std::string DoxygenParser::getStringTilEndCommand(const std::string &theCommand, const TokenList &tokList) { + + if (m_tokenListIt == tokList.end()) { + return ""; + } + + string description; + while (m_tokenListIt != tokList.end()) { + + if (m_tokenListIt->m_tokenType == PLAINSTRING) { + description += m_tokenListIt->m_tokenString; + } else if (m_tokenListIt->m_tokenType == END_LINE) { + description += "\n"; + } else if (m_tokenListIt->m_tokenString == theCommand) { + m_tokenListIt++; + return description; + } + + m_tokenListIt++; + } + + printListError(WARN_DOXYGEN_COMMAND_EXPECTED, "Expected Doxygen command: " + theCommand + "."); + + return description; +} + +DoxygenParser::TokenListCIt DoxygenParser::getEndOfParagraph(const TokenList &tokList) { + + TokenListCIt endOfParagraph = m_tokenListIt; + + while (endOfParagraph != tokList.end()) { + if (endOfParagraph->m_tokenType == END_LINE) { + endOfParagraph++; + if (endOfParagraph != tokList.end() + && endOfParagraph->m_tokenType == END_LINE) { + endOfParagraph++; + //cout << "ENCOUNTERED END OF PARA" << endl; + return endOfParagraph; + } + + } else if (endOfParagraph->m_tokenType == COMMAND) { + + if (isSectionIndicator(endOfParagraph->m_tokenString)) { + return endOfParagraph; + } else { + endOfParagraph++; + } + + } else if (endOfParagraph->m_tokenType == PLAINSTRING) { + endOfParagraph++; + } else { + return tokList.end(); + } + } + + return tokList.end(); +} + +DoxygenParser::TokenListCIt DoxygenParser::getEndOfSection(const std::string &theCommand, const TokenList &tokList) { + + TokenListCIt endOfParagraph = m_tokenListIt; + + while (endOfParagraph != tokList.end()) { + if (endOfParagraph->m_tokenType == COMMAND) { + if (theCommand == endOfParagraph->m_tokenString) + return endOfParagraph; + else + endOfParagraph++; + } else if (endOfParagraph->m_tokenType == PLAINSTRING) { + endOfParagraph++; + } else if (endOfParagraph->m_tokenType == END_LINE) { + endOfParagraph++; + if (endOfParagraph->m_tokenType == END_LINE) { + endOfParagraph++; + return endOfParagraph; + } + } + } + return tokList.end(); +} + +DoxygenParser::TokenListCIt DoxygenParser::getEndCommand(const std::string &theCommand, const TokenList &tokList) { + + TokenListCIt endOfCommand = m_tokenListIt; + + while (endOfCommand != tokList.end()) { + endOfCommand++; + if ((*endOfCommand).m_tokenType == COMMAND) { + if (theCommand == (*endOfCommand).m_tokenString) { + return endOfCommand; + } + } + } + //End command not found + return tokList.end(); +} + +void DoxygenParser::skipEndOfLine() { + if (m_tokenListIt != m_tokenList.end() + && m_tokenListIt->m_tokenType == END_LINE) { + m_tokenListIt++; + } +} + +void DoxygenParser::addSimpleCommand(const std::string &theCommand, DoxygenEntityList &doxyList) { + if (noisy) + cout << "Parsing " << theCommand << endl; + + doxyList.push_back(DoxygenEntity(theCommand)); +} + +void DoxygenParser::addCommandWord(const std::string &theCommand, const TokenList &, DoxygenEntityList &doxyList) { + if (noisy) + cout << "Parsing " << theCommand << endl; + + if (isEndOfLine()) { + // handles cases when command is at the end of line (for example "\c\nreally" + skipWhitespaceTokens(); + doxyList.push_back(DoxygenEntity("plainstd::endl")); + } + std::string name = getNextWord(); + if (!name.empty()) { + DoxygenEntityList aNewList; + aNewList.push_back(DoxygenEntity("plainstd::string", name)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } else { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored."); + } +} + +void DoxygenParser::addCommandLine(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList) { + if (noisy) + cout << "Parsing " << theCommand << endl; + TokenListCIt endOfLine = getOneLine(tokList); + DoxygenEntityList aNewList = parse(endOfLine, tokList); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + skipEndOfLine(); +} + +void DoxygenParser::addCommandParagraph(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList) { + if (noisy) + cout << "Parsing " << theCommand << endl; + + TokenListCIt endOfParagraph = getEndOfParagraph(tokList); + DoxygenEntityList aNewList; + aNewList = parse(endOfParagraph, tokList); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); +} + +void DoxygenParser::addCommandEndCommand(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList) { + if (noisy) + cout << "Parsing " << theCommand << endl; + TokenListCIt endCommand = getEndCommand("end" + theCommand, tokList); + if (endCommand == tokList.end()) { + printListError(WARN_DOXYGEN_COMMAND_EXPECTED, "Expected Doxygen command: end" + theCommand + "."); + return; + } + DoxygenEntityList aNewList; + aNewList = parse(endCommand, tokList); + m_tokenListIt++; + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); +} + +void DoxygenParser::addCommandWordParagraph(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList) { + if (noisy) + cout << "Parsing " << theCommand << endl; + + std::string name = getNextWord(); + + if (name.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored."); + return; + } + TokenListCIt endOfParagraph = getEndOfParagraph(tokList); + DoxygenEntityList aNewList; + aNewList = parse(endOfParagraph, tokList); + aNewList.push_front(DoxygenEntity("plainstd::string", name)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); +} + +void DoxygenParser::addCommandWordLine(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList) { + if (noisy) + cout << "Parsing " << theCommand << endl; + std::string name = getNextWord(); + if (name.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored."); + return; + } + + TokenListCIt endOfLine = getOneLine(tokList); + DoxygenEntityList aNewList; + aNewList = parse(endOfLine, tokList); + aNewList.push_front(DoxygenEntity("plainstd::string", name)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + //else cout << "No line followed " << theCommand << " command. Not added" << endl; +} + +void DoxygenParser::addCommandWordOWordOWord(const std::string &theCommand, const TokenList &, DoxygenEntityList &doxyList) { + if (noisy) + cout << "Parsing " << theCommand << endl; + + std::string name = getNextWord(); + if (name.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored."); + return; + } + std::string headerfile = getNextWord(); + std::string headername = getNextWord(); + DoxygenEntityList aNewList; + aNewList.push_back(DoxygenEntity("plainstd::string", name)); + if (!headerfile.empty()) + aNewList.push_back(DoxygenEntity("plainstd::string", headerfile)); + if (!headername.empty()) + aNewList.push_back(DoxygenEntity("plainstd::string", headername)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); +} + +void DoxygenParser::addCommandOWord(const std::string &theCommand, const TokenList &, DoxygenEntityList &doxyList) { + if (noisy) + cout << "Parsing " << theCommand << endl; + + std::string name = getNextWord(); + DoxygenEntityList aNewList; + aNewList.push_back(DoxygenEntity("plainstd::string", name)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); +} + +void DoxygenParser::addCommandErrorThrow(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &) { + + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": Unexpectedly encountered this command."); + m_tokenListIt = getOneLine(tokList); +} + +void DoxygenParser::addCommandHtml(const std::string &theCommand, const TokenList &, DoxygenEntityList &doxyList) { + if (noisy) + cout << "Parsing " << theCommand << endl; + + std::string htmlTagArgs = getNextToken(); + doxyList.push_back(DoxygenEntity(theCommand, htmlTagArgs)); +} + +void DoxygenParser::addCommandHtmlEntity(const std::string &theCommand, const TokenList &, DoxygenEntityList &doxyList) { + if (noisy) + cout << "Parsing " << theCommand << endl; + + DoxygenEntityList aNewList; + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); +} + +void DoxygenParser::addCommandUnique(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList) { + + static std::map<std::string, std::string> endCommands; + DoxygenEntityList aNewList; + if (theCommand == "arg" || theCommand == "li") { + TokenListCIt endOfSection = getEndOfSection(theCommand, tokList); + DoxygenEntityList aNewList; + aNewList = parse(endOfSection, tokList); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } + // \xrefitem <key> "(heading)" "(std::list title)" {text} + else if (theCommand == "xrefitem") { + if (noisy) + cout << "Parsing " << theCommand << endl; + std::string key = getNextWord(); + if (key.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No key followed the command. Command ignored."); + return; + } + std::string heading = getNextWord(); + if (key.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No heading followed the command. Command ignored."); + return; + } + std::string title = getNextWord(); + if (title.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No title followed the command. Command ignored."); + return; + } + TokenListCIt endOfParagraph = getEndOfParagraph(tokList); + aNewList = parse(endOfParagraph, tokList); + aNewList.push_front(DoxygenEntity("plainstd::string", title)); + aNewList.push_front(DoxygenEntity("plainstd::string", heading)); + aNewList.push_front(DoxygenEntity("plainstd::string", key)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } + // \ingroup (<groupname> [<groupname> <groupname>]) + else if (theCommand == "ingroup") { + std::string name = getNextWord(); + aNewList.push_back(DoxygenEntity("plainstd::string", name)); + name = getNextWord(); + if (!name.empty()) + aNewList.push_back(DoxygenEntity("plainstd::string", name)); + name = getNextWord(); + if (!name.empty()) + aNewList.push_back(DoxygenEntity("plainstd::string", name)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } + // \par [(paragraph title)] { paragraph } + else if (theCommand == "par") { + TokenListCIt endOfLine = getOneLine(tokList); + aNewList = parse(endOfLine, tokList); + DoxygenEntityList aNewList2; + TokenListCIt endOfParagraph = getEndOfParagraph(tokList); + aNewList2 = parse(endOfParagraph, tokList); + aNewList.splice(aNewList.end(), aNewList2); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } + // \headerfile <header-file> [<header-name>] + else if (theCommand == "headerfile") { + DoxygenEntityList aNewList; + std::string name = getNextWord(); + aNewList.push_back(DoxygenEntity("plainstd::string", name)); + name = getNextWord(); + if (!name.empty()) + aNewList.push_back(DoxygenEntity("plainstd::string", name)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } + // \overload [(function declaration)] + else if (theCommand == "overload") { + TokenListCIt endOfLine = getOneLine(tokList); + if (endOfLine != m_tokenListIt) { + DoxygenEntityList aNewList; + aNewList = parse(endOfLine, tokList); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } else + doxyList.push_back(DoxygenEntity(theCommand)); + } + // \weakgroup <name> [(title)] + else if (theCommand == "weakgroup") { + if (noisy) + cout << "Parsing " << theCommand << endl; + std::string name = getNextWord(); + if (name.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored."); + return; + } + DoxygenEntityList aNewList; + TokenListCIt endOfLine = getOneLine(tokList); + if (endOfLine != m_tokenListIt) { + aNewList = parse(endOfLine, tokList); + } + aNewList.push_front(DoxygenEntity("plainstd::string", name)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } + // \ref <name> ["(text)"] + else if (theCommand == "ref") { + if (noisy) + cout << "Parsing " << theCommand << endl; + std::string name = getNextWord(); + if (name.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No key followed the command. Command ignored."); + return; + } + DoxygenEntityList aNewList; + aNewList.push_front(DoxygenEntity("plainstd::string", name)); + // TokenListCIt endOfLine = getOneLine(tokList); + // if (endOfLine != m_tokenListIt) { + // aNewList = parse(endOfLine, tokList); + //} + TokenListCIt tmpIt = m_tokenListIt; + std::string refTitle = getNextWord(); + // If title is following the ref tag, it must be quoted. Otherwise + // doxy puts link on ref id. + if (refTitle.size() > 1 && refTitle[0] == '"') { + // remove quotes + refTitle = refTitle.substr(1, refTitle.size() - 2); + aNewList.push_back(DoxygenEntity("plainstd::string", refTitle)); + } else { + // no quoted string is following, so we have to restore iterator + m_tokenListIt = tmpIt; + } + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } + // \subpage <name> ["(text)"] + else if (theCommand == "subpage") { + if (noisy) + cout << "Parsing " << theCommand << endl; + std::string name = getNextWord(); + if (name.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No name followed the command. Command ignored."); + return; + } + std::string text = getNextWord(); + aNewList.push_back(DoxygenEntity("plainstd::string", name)); + if (!text.empty()) + aNewList.push_back(DoxygenEntity("plainstd::string", text)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } + // \code ... \endcode + // \verbatim ... \endverbatim + // \dot dotcode \enddot + // \msc msccode \endmsc + // \f[ ... \f] + // \f{ ... \f} + // \f{env}{ ... \f} + // \f$ ... \f$ + else if (theCommand == "code" || theCommand == "verbatim" + || theCommand == "dot" || theCommand == "msc" || theCommand == "f[" || theCommand == "f{" || theCommand == "f$") { + if (!endCommands.size()) { + // fill in static table of end commands + endCommands["f["] = "f]"; + endCommands["f{"] = "f}"; + endCommands["f$"] = "f$"; + } + if (noisy) + cout << "Parsing " << theCommand << endl; + + std::string endCommand; + std::map<std::string, std::string>::iterator it; + it = endCommands.find(theCommand); + if (it != endCommands.end()) + endCommand = it->second; + else + endCommand = "end" + theCommand; + + std::string content = getStringTilEndCommand(endCommand, tokList); + aNewList.push_back(DoxygenEntity("plainstd::string", content)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } + // \dotfile <file> ["caption"] + // \mscfile <file> ["caption"] + else if (theCommand == "dotfile" || theCommand == "mscfile") { + if (noisy) + cout << "Parsing " << theCommand << endl; + std::string file = getNextWord(); + if (file.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No file followed the command. Command ignored."); + return; + } + std::string caption = getNextWord(); + aNewList.push_back(DoxygenEntity("plainstd::string", file)); + if (!caption.empty()) + aNewList.push_back(DoxygenEntity("plainstd::string", caption)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } + // \image <format> <file> ["caption"] [<sizeindication>=<size>] + else if (theCommand == "image") { + if (noisy) + cout << "Parsing " << theCommand << endl; + std::string format = getNextWord(); + if (format.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No format followed the command. Command ignored."); + return; + } + std::string file = getNextWord(); + if (file.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No name followed the command. Command ignored."); + return; + } + std::string caption = getNextWord(); + std::string size = getNextWord(); + + DoxygenEntityList aNewList; + aNewList.push_back(DoxygenEntity("plainstd::string", format)); + aNewList.push_back(DoxygenEntity("plainstd::string", file)); + if (!caption.empty()) + aNewList.push_back(DoxygenEntity("plainstd::string", caption)); + if (!size.empty()) + aNewList.push_back(DoxygenEntity("plainstd::string", size)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } + // \addtogroup <name> [(title)] + else if (theCommand == "addtogroup") { + if (noisy) + cout << "Parsing " << theCommand << endl; + std::string name = getNextWord(); + if (name.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": There should be at least one word following the command. Command ignored."); + return; + } + DoxygenEntityList aNewList; + TokenListCIt endOfLine = getOneLine(tokList); + if (endOfLine != m_tokenListIt) { + aNewList = parse(endOfLine, tokList); + } + aNewList.push_front(DoxygenEntity("plainstd::string", name)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + skipEndOfLine(); + } + // \if <cond> [\else ...] [\elseif <cond> ...] \endif + else if (theCommand == "if" || theCommand == "ifnot" || theCommand == "else" || theCommand == "elseif") { + if (noisy) + cout << "Parsing " << theCommand << endl; + + std::string cond; + bool skipEndif = false; // if true then we skip endif after parsing block of code + bool needsCond = (theCommand == "if" || theCommand == "ifnot" || theCommand == "elseif"); + if (needsCond) { + cond = getNextWord(); + if (cond.empty()) { + printListError(WARN_DOXYGEN_COMMAND_ERROR, "Error parsing Doxygen command " + theCommand + ": No word followed the command. Command ignored."); + return; + } + } + + int nestedCounter = 1; + TokenListCIt endCommand = tokList.end(); + + // go through the commands and find closing endif or else or elseif + for (TokenListCIt it = m_tokenListIt; it != tokList.end(); it++) { + if (it->m_tokenType == COMMAND) { + if (it->m_tokenString == "if" || it->m_tokenString == "ifnot") + nestedCounter++; + else if (it->m_tokenString == "endif") + nestedCounter--; + if (nestedCounter == 1 && (it->m_tokenString == "else" || it->m_tokenString == "elseif")) { // else found + endCommand = it; + break; + } + if (nestedCounter == 0) { // endif found + endCommand = it; + skipEndif = true; + break; + } + } + } + + if (endCommand == tokList.end()) { + printListError(WARN_DOXYGEN_COMMAND_EXPECTED, "Expected Doxygen command: endif."); + return; + } + + DoxygenEntityList aNewList; + aNewList = parse(endCommand, tokList); + if (skipEndif) + m_tokenListIt++; + if (needsCond) + aNewList.push_front(DoxygenEntity("plainstd::string", cond)); + doxyList.push_back(DoxygenEntity(theCommand, aNewList)); + } +} + +void DoxygenParser::aliasCommand(const std::string &theCommand, const TokenList &/* tokList */ , DoxygenEntityList &doxyList) { + String *const alias = Getattr(m_node, ("feature:doxygen:alias:" + theCommand).c_str()); + if (!alias) + return; + + doxyList.push_back(DoxygenEntity("plainstd::string", Char(alias))); +} + +String *DoxygenParser::getIgnoreFeature(const std::string &theCommand, const char *argument) const { + string feature_name = "feature:doxygen:ignore:" + theCommand; + if (argument) { + feature_name += ':'; + feature_name += argument; + } + + return Getattr(m_node, feature_name.c_str()); +} + +string DoxygenParser::getIgnoreFeatureEndCommand(const std::string &theCommand) const { + // We may be dealing either with a simple command or with the starting command + // of a block, as indicated by the value of "range" starting with "end". + string endCommand; + if (String *const range = getIgnoreFeature(theCommand, "range")) { + const char *const p = Char(range); + if (strncmp(p, "end", 3) == 0) { + if (p[3] == ':') { + // Normally the end command name follows after the colon. + endCommand = p + 4; + } else if (p[3] == '\0') { + // But it may be omitted in which case the default Doxygen convention of + // using "something"/"endsomething" is used. + endCommand = "end" + theCommand; + } + } + } + + return endCommand; +} + +void DoxygenParser::ignoreCommand(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList) { + const string endCommand = getIgnoreFeatureEndCommand(theCommand); + if (!endCommand.empty()) { + TokenListCIt itEnd = getEndCommand(endCommand, tokList); + if (itEnd == tokList.end()) { + printListError(WARN_DOXYGEN_COMMAND_EXPECTED, "Expected Doxygen command: " + endCommand + "."); + return; + } + // If we ignore the command, also ignore any whitespace preceding it as we + // want to avoid having lines consisting of whitespace only or trailing + // whitespace in general (at least Python, with its pep8 tool, really + // doesn't like it). + if (!doxyList.empty()) { + DoxygenEntityList::iterator i = doxyList.end(); + --i; + if (i->typeOfEntity == "plainstd::string" && i->data.find_first_not_of(" \t") == std::string::npos) { + doxyList.erase(i); + } + } + // Determine what to do with the part of the comment between the start and + // end commands: by default, we simply throw it away, but "contents" + // attribute may be used to change this. + if (String *const contents = getIgnoreFeature(theCommand, "contents")) { + // Currently only "parse" is supported but we may need to add "copy" to + // handle custom tags which contain text that is supposed to be copied + // verbatim in the future. + if (Strcmp(contents, "parse") == 0) { + DoxygenEntityList aNewList = parse(itEnd, tokList); + doxyList.splice(doxyList.end(), aNewList); + } else { + Swig_error(m_fileName.c_str(), m_fileLineNo, "Invalid \"doxygen:ignore\" feature \"contents\" attribute \"%s\".\n", Char(contents)); + return; + } + } + + m_tokenListIt = itEnd; + m_tokenListIt++; + } else if (String *const range = getIgnoreFeature(theCommand, "range")) { + // Currently we only support "line" but, in principle, we should also + // support "word" and "paragraph" for consistency with the built-in Doxygen + // commands which can have either of these three ranges (which are indicated + // using <word-arg>, (line-arg) and {para-arg} respectively in Doxygen + // documentation). + if (Strcmp(range, "line") == 0) { + // Consume everything until the end of line. + m_tokenListIt = getOneLine(tokList); + skipEndOfLine(); + } else { + Swig_error(m_fileName.c_str(), m_fileLineNo, "Invalid \"doxygen:ignore\" feature \"range\" attribute \"%s\".\n", Char(range)); + return; + } + } +} + +void DoxygenParser::addCommand(const std::string &commandString, const TokenList &tokList, DoxygenEntityList &doxyList) { + + string theCommand = stringToLower(commandString); + + if (theCommand == "plainstd::string") { + string nextPhrase = getStringTilCommand(tokList); + if (noisy) + cout << "Parsing plain std::string :" << nextPhrase << endl; + doxyList.push_back(DoxygenEntity("plainstd::string", nextPhrase)); + return; + } + + switch (commandBelongs(commandString)) { + case SIMPLECOMMAND: + addSimpleCommand(theCommand, doxyList); + break; + case COMMANDWORD: + addCommandWord(theCommand, tokList, doxyList); + break; + case COMMANDLINE: + addCommandLine(theCommand, tokList, doxyList); + break; + case COMMANDPARAGRAPH: + addCommandParagraph(theCommand, tokList, doxyList); + break; + case COMMANDENDCOMMAND: + addCommandEndCommand(theCommand, tokList, doxyList); + break; + case COMMANDWORDPARAGRAPH: + addCommandWordParagraph(theCommand, tokList, doxyList); + break; + case COMMANDWORDLINE: + addCommandWordLine(theCommand, tokList, doxyList); + break; + case COMMANDWORDOWORDWORD: + addCommandWordOWordOWord(theCommand, tokList, doxyList); + break; + case COMMANDOWORD: + addCommandOWord(theCommand, tokList, doxyList); + break; + case COMMANDERRORTHROW: + addCommandErrorThrow(theCommand, tokList, doxyList); + break; + case COMMANDUNIQUE: + addCommandUnique(theCommand, tokList, doxyList); + break; + case COMMAND_HTML: + addCommandHtml(theCommand, tokList, doxyList); + break; + case COMMAND_HTML_ENTITY: + addCommandHtmlEntity(theCommand, tokList, doxyList); + break; + case COMMAND_ALIAS: + aliasCommand(commandString, tokList, doxyList); + break; + case COMMAND_IGNORE: + ignoreCommand(commandString, tokList, doxyList); + break; + case NONE: + case END_LINE: + case PARAGRAPH_END: + case PLAINSTRING: + case COMMAND: + // TODO: Ensure that these values either are correctly ignored here or can't happen. + break; + } +} + +/** + * This method converts TokenList to DoxygenEntryList. + */ +DoxygenEntityList DoxygenParser::parse(TokenListCIt endParsingIndex, const TokenList &tokList, bool root) { + // if we are root, than any strings should be added as 'partofdescription', else as 'plainstd::string' + std::string currPlainstringCommandType = root ? "partofdescription" : "plainstd::string"; + DoxygenEntityList aNewList; + + while (m_tokenListIt != endParsingIndex) { + + Token currToken = *m_tokenListIt; + + if (noisy) + cout << "Parsing for phrase starting in:" << currToken.toString() << endl; + + if (currToken.m_tokenType == END_LINE) { + aNewList.push_back(DoxygenEntity("plainstd::endl")); + m_tokenListIt++; + } else if (currToken.m_tokenType == COMMAND) { + m_tokenListIt++; + addCommand(currToken.m_tokenString, tokList, aNewList); + } else if (currToken.m_tokenType == PLAINSTRING) { + addCommand(currPlainstringCommandType, tokList, aNewList); + } + + if (endParsingIndex != tokList.end() && m_tokenListIt == tokList.end()) { + // this could happen if we can't reach the original endParsingIndex + printListError(WARN_DOXYGEN_UNEXPECTED_END_OF_COMMENT, "Unexpected end of Doxygen comment encountered."); + break; + } + } + return aNewList; +} + +DoxygenEntityList DoxygenParser::createTree(Node *node, String *documentation) { + m_node = node; + + tokenizeDoxygenComment(Char(documentation), Char(Getfile(documentation)), Getline(documentation)); + + if (noisy) { + cout << "---TOKEN LIST---" << endl; + printList(); + } + + DoxygenEntityList rootList = parse(m_tokenList.end(), m_tokenList, true); + + if (noisy) { + cout << "PARSED LIST" << endl; + printTree(rootList); + } + return rootList; +} + +/* + * Splits 'text' on 'separator' chars. Separator chars are not part of the + * strings. + */ +DoxygenParser::StringVector DoxygenParser::split(const std::string &text, char separator) { + StringVector lines; + size_t prevPos = 0, pos = 0; + + while (pos < string::npos) { + pos = text.find(separator, prevPos); + lines.push_back(text.substr(prevPos, pos - prevPos)); + prevPos = pos + 1; + } + + return lines; +} + +/* + * Returns true, if 'c' is one of doxygen comment block start + * characters: *, /, or ! + */ +bool DoxygenParser::isStartOfDoxyCommentChar(char c) { + return (strchr("*/!", c) != NULL); +} + +/* + * Adds token with Doxygen command to token list, but only if command is one of + * Doxygen commands. In that case true is returned. If the command is not + * recognized as a doxygen command, it is ignored and false is returned. + */ +bool DoxygenParser::addDoxyCommand(DoxygenParser::TokenList &tokList, const std::string &cmd) { + if (commandBelongs(cmd) != NONE) { + tokList.push_back(Token(COMMAND, cmd)); + return true; + } else { + // This function is called for the special Doxygen commands, but also for + // HTML commands (or anything that looks like them, actually) and entities. + // We don't recognize all of those, so just ignore them and pass them + // through, but warn about unknown Doxygen commands as ignoring them will + // often result in wrong output being generated. + const char ch = *cmd.begin(); + if (ch != '<' && ch != '&') { + // Before calling printListError() we must ensure that m_tokenListIt used + // by it is valid. + const TokenListCIt itSave = m_tokenListIt; + m_tokenListIt = m_tokenList.end(); + + printListError(WARN_DOXYGEN_UNKNOWN_COMMAND, "Unknown Doxygen command: " + cmd + "."); + + m_tokenListIt = itSave; + } + } + + return false; +} + +/* + * This method copies comment text to output as it is - no processing is + * done, Doxygen commands are ignored. It is used for commands \verbatim, + * \htmlonly, \f$, \f[, and \f{. + */ +size_t DoxygenParser::processVerbatimText(size_t pos, const std::string &line) { + if (line[pos] == '\\' || line[pos] == '@') { // check for end commands + + pos++; + size_t endOfWordPos = line.find_first_not_of(DOXYGEN_WORD_CHARS, pos); + string cmd = line.substr(pos, endOfWordPos - pos); + + if (cmd == CMD_END_HTML_ONLY || cmd == CMD_END_VERBATIM || cmd == CMD_END_LATEX_1 || cmd == CMD_END_LATEX_2 || cmd == CMD_END_LATEX_3) { + + m_isVerbatimText = false; + addDoxyCommand(m_tokenList, cmd); + + } else { + + m_tokenList.push_back(Token(PLAINSTRING, + // include '\' or '@' + line.substr(pos - 1, endOfWordPos - pos + 1))); + } + + pos = endOfWordPos; + + } else { + + // whitespaces are stored as plain strings + size_t startOfPossibleEndCmd = line.find_first_of("\\@", pos); + m_tokenList.push_back(Token(PLAINSTRING, line.substr(pos, startOfPossibleEndCmd - pos))); + pos = startOfPossibleEndCmd; + } + + return pos; +} + +/* + * Processes doxy commands for escaped characters: \$ \@ \\ \& \~ \< \> \# \% \" \. \:: + * Handling this separately supports documentation text like \@someText. + */ +bool DoxygenParser::processEscapedChars(size_t &pos, const std::string &line) { + if ((pos + 1) < line.size()) { + + // \ and @ with trailing whitespace or quoted get to output as plain string + string whitespaces = " '\t\n"; + if (whitespaces.find(line[pos + 1]) != string::npos) { + m_tokenList.push_back(Token(PLAINSTRING, line.substr(pos, 1))); + pos++; + return true; + } + // these chars can be escaped for doxygen + string escapedChars = "$@\\&~<>#%\"."; + if (escapedChars.find(line[pos + 1]) != string::npos) { + + addDoxyCommand(m_tokenList, line.substr(pos + 1, 1)); + pos += 2; + return true; + + } else if ((pos + 2) < line.size() && line[pos + 1] == ':' && line[pos + 2] == ':') { + + // add command \:: - handling this separately supports documentation + // text like \::someText + addDoxyCommand(m_tokenList, line.substr(pos + 1, 2)); + pos += 3; + return true; + } + } + return false; +} + +/* + * Processes word doxygen commands, like \arg, \c, \b, \return, ... + */ +void DoxygenParser::processWordCommands(size_t &pos, const std::string &line) { + pos++; + size_t endOfWordPos = line.find_first_not_of(DOXYGEN_WORD_CHARS, pos); + + string cmd = line.substr(pos, endOfWordPos - pos); + addDoxyCommand(m_tokenList, cmd); + + if (cmd == CMD_HTML_ONLY || cmd == CMD_VERBATIM || cmd == CMD_LATEX_1 || cmd == CMD_LATEX_2 || cmd == CMD_LATEX_3) { + + m_isVerbatimText = true; + + } else { + // skip any possible spaces after command, because some commands have parameters, + // and spaces between command and parameter must be ignored. + if (endOfWordPos != string::npos) { + endOfWordPos = line.find_first_not_of(" \t", endOfWordPos); + } + } + pos = endOfWordPos; +} + +void DoxygenParser::processHtmlTags(size_t &pos, const std::string &line) { + bool isEndHtmlTag = false; + pos++; + if (line.size() > pos && line[pos] == '/') { + isEndHtmlTag = true; + pos++; + } + + size_t endHtmlPos = line.find_first_of("\t >", pos); + + string cmd = line.substr(pos, endHtmlPos - pos); + pos = endHtmlPos; + + // prepend '<' to distinguish HTML tags from doxygen commands + if (!cmd.empty() && addDoxyCommand(m_tokenList, '<' + cmd)) { + // it is a valid HTML command + if (line[pos] != '>') { + // it should be HTML tag with args, + // for example <A ...>, <IMG ...>, ... + if (isEndHtmlTag) { + m_tokenListIt = m_tokenList.end(); + printListError(WARN_DOXYGEN_HTML_ERROR, "Doxygen HTML error for tag " + cmd + ": Illegal end HTML tag without '>' found."); + } + + endHtmlPos = line.find(">", pos); + if (endHtmlPos == string::npos) { + m_tokenListIt = m_tokenList.end(); + printListError(WARN_DOXYGEN_HTML_ERROR, "Doxygen HTML error for tag " + cmd + ": HTML tag without '>' found."); + } + // add args of HTML command, like link URL, image URL, ... + m_tokenList.push_back(Token(PLAINSTRING, line.substr(pos, endHtmlPos - pos))); + pos = endHtmlPos; + } else { + if (isEndHtmlTag) { + m_tokenList.push_back(Token(PLAINSTRING, END_HTML_TAG_MARK)); + } else { + // it is a simple tag, so push empty string + m_tokenList.push_back(Token(PLAINSTRING, "")); + } + } + + if (pos != string::npos) { + pos++; // skip '>' + } + } else { + // the command is not HTML supported by Doxygen, < and > will be + // replaced by HTML entities < and > respectively, + addDoxyCommand(m_tokenList, "<"); + m_tokenList.push_back(Token(PLAINSTRING, cmd)); + } +} + +void DoxygenParser::processHtmlEntities(size_t &pos, const std::string &line) { + size_t endOfWordPos = line.find_first_not_of("abcdefghijklmnopqrstuvwxyz", pos + 1); + + if (endOfWordPos != string::npos) { + + if (line[endOfWordPos] == ';' && (endOfWordPos - pos) > 1) { + // if entity is not recognized by Doxygen (not in the list of + // commands) nothing is added (here and in Doxygen). + addDoxyCommand(m_tokenList, line.substr(pos, endOfWordPos - pos)); + endOfWordPos++; // skip ';' + } else { + // it is not an entity - add entity for ampersand and the rest of string + addDoxyCommand(m_tokenList, "&"); + m_tokenList.push_back(Token(PLAINSTRING, line.substr(pos + 1, endOfWordPos - pos - 1))); + } + } + pos = endOfWordPos; +} + +/* + * This method processes normal comment, which has to be tokenized. + */ +size_t DoxygenParser::processNormalComment(size_t pos, const std::string &line) { + switch (line[pos]) { + case '\\': + case '@': + if (processEscapedChars(pos, line)) { + break; + } + // handle word commands \arg, \c, \return, ... and \f[, \f$, ... commands + processWordCommands(pos, line); + break; + + case ' ': // whitespace + case '\t': + { + // whitespaces are stored as plain strings + size_t startOfNextWordPos = line.find_first_not_of(" \t", pos + 1); + m_tokenList.push_back(Token(PLAINSTRING, line.substr(pos, startOfNextWordPos - pos))); + pos = startOfNextWordPos; + } + break; + + case '<': + processHtmlTags(pos, line); + break; + case '>': // this char is detected here only when it is not part of HTML tag + addDoxyCommand(m_tokenList, ">"); + pos++; + break; + case '&': + processHtmlEntities(pos, line); + break; + case '"': + m_isInQuotedString = true; + m_tokenList.push_back(Token(PLAINSTRING, "\"")); + pos++; + break; + default: + m_tokenListIt = m_tokenList.end(); + printListError(WARN_DOXYGEN_UNKNOWN_CHARACTER, std::string("Unknown special character in Doxygen comment: ") + line[pos] + "."); + } + + return pos; +} + +/* + * This is the main method, which tokenizes Doxygen comment to words and + * doxygen commands. + */ +void DoxygenParser::tokenizeDoxygenComment(const std::string &doxygenComment, const std::string &fileName, int fileLine) { + m_isVerbatimText = false; + m_isInQuotedString = false; + m_tokenList.clear(); + m_fileLineNo = fileLine; + m_fileName = fileName; + + StringVector lines = split(doxygenComment, '\n'); + + // remove trailing spaces, because they cause additional new line at the end + // comment, which is wrong, because these spaces are space preceding + // end of comment : ' */' + if (!doxygenComment.empty() && doxygenComment[doxygenComment.size() - 1] == ' ') { + + string lastLine = lines[lines.size() - 1]; + + if (trim(lastLine).empty()) { + lines.pop_back(); // remove trailing empy line + } + } + + for (StringVectorCIt it = lines.begin(); it != lines.end(); it++) { + const string &line = *it; + size_t pos = line.find_first_not_of(" \t"); + + if (pos == string::npos) { + m_tokenList.push_back(Token(END_LINE, "\n")); + continue; + } + // skip sequences of '*', '/', and '!' of any length + bool isStartOfCommentLineCharFound = false; + while (pos < line.size() && isStartOfDoxyCommentChar(line[pos])) { + pos++; + isStartOfCommentLineCharFound = true; + } + + if (pos == line.size()) { + m_tokenList.push_back(Token(END_LINE, "\n")); + continue; + } + // if 'isStartOfCommentLineCharFound' then preserve leading spaces, so + // ' * comment' gets translated to ' * comment', not ' * comment' + // This is important to keep formatting for comments translated to Python. + if (isStartOfCommentLineCharFound && line[pos] == ' ') { + pos++; // points to char after ' * ' + if (pos == line.size()) { + m_tokenList.push_back(Token(END_LINE, "\n")); + continue; + } + } + // line[pos] may be ' \t' or start of word, it there was no '*', '/' or '!' + // at beginning of the line. Make sure it points to start of the first word + // in the line. + if (isStartOfCommentLineCharFound) { + size_t firstWordPos = line.find_first_not_of(" \t", pos); + if (firstWordPos == string::npos) { + m_tokenList.push_back(Token(END_LINE, "\n")); + continue; + } + + if (firstWordPos > pos) { + m_tokenList.push_back(Token(PLAINSTRING, line.substr(pos, firstWordPos - pos))); + pos = firstWordPos; + } + } else { + m_tokenList.push_back(Token(PLAINSTRING, line.substr(0, pos))); + } + + while (pos != string::npos) { + // find the end of the word + size_t doxyCmdOrHtmlTagPos = line.find_first_of("\\@<>&\" \t", pos); + if (doxyCmdOrHtmlTagPos != pos) { + // plain text found + // if the last char is punctuation, make it a separate word, otherwise + // it may be included with word also when not appropriate, for example: + // colors are \b red, green, and blue --> colors are <b>red,</b> green, and blue + // instead of (comma not bold): + // colors are \b red, green, and blue --> colors are <b>red</b>, green, and blue + // In Python it looks even worse: + // colors are \b red, green, and blue --> colors are 'red,' green, and blue + string text = line.substr(pos, doxyCmdOrHtmlTagPos - pos); + string punctuations(".,:"); + size_t textSize = text.size(); + + if (!text.empty() + && punctuations.find(text[text.size() - 1]) != string::npos && + // but do not break ellipsis (...) + !(textSize > 1 && text[textSize - 2] == '.')) { + m_tokenList.push_back(Token(PLAINSTRING, text.substr(0, text.size() - 1))); + m_tokenList.push_back(Token(PLAINSTRING, text.substr(text.size() - 1))); + } else { + m_tokenList.push_back(Token(PLAINSTRING, text)); + } + } + + pos = doxyCmdOrHtmlTagPos; + if (pos != string::npos) { + if (m_isVerbatimText) { + pos = processVerbatimText(pos, line); + + } else if (m_isInQuotedString) { + + if (line[pos] == '"') { + m_isInQuotedString = false; + } + m_tokenList.push_back(Token(PLAINSTRING, line.substr(pos, 1))); + pos++; + + } else { + pos = processNormalComment(pos, line); + } + } + } + m_tokenList.push_back(Token(END_LINE, "\n")); // add when pos == npos - end of line + } + + m_tokenListIt = m_tokenList.begin(); +} + +void DoxygenParser::printList() { + + int tokNo = 0; + for (TokenListCIt it = m_tokenList.begin(); it != m_tokenList.end(); it++, tokNo++) { + + cout << it->toString() << " "; + + if ((tokNo % TOKENSPERLINE) == 0) { + cout << endl; + } + } +} + +void DoxygenParser::printListError(int warningType, const std::string &message) { + int curLine = m_fileLineNo; + for (TokenListCIt it = m_tokenList.begin(); it != m_tokenListIt; it++) { + if (it->m_tokenType == END_LINE) { + curLine++; + } + } + + Swig_warning(warningType, m_fileName.c_str(), curLine, "%s\n", message.c_str()); +} diff --git a/Source/Doxygen/doxyparser.h b/Source/Doxygen/doxyparser.h new file mode 100644 index 000000000..96c71d22f --- /dev/null +++ b/Source/Doxygen/doxyparser.h @@ -0,0 +1,372 @@ +/* ----------------------------------------------------------------------------- + * This file is part of SWIG, which is licensed as a whole under version 3 + * (or any later version) of the GNU General Public License. Some additional + * terms also apply to certain portions of SWIG. The full details of the SWIG + * license and copyrights can be found in the LICENSE and COPYRIGHT files + * included with the SWIG source code as distributed by the SWIG developers + * and at http://www.swig.org/legal.html. + * + * doxyparser.h + * ----------------------------------------------------------------------------- */ + +#ifndef DOXYGENPARSER_H_ +#define DOXYGENPARSER_H_ +#include <string> +#include <list> +#include <map> +#include <vector> +#include <set> + +#include "swig.h" + +#include "doxyentity.h" + +class DoxygenParser { +private: + + enum DoxyCommandEnum { + NONE = -1, + SIMPLECOMMAND, + COMMANDWORD, + COMMANDLINE, + COMMANDPARAGRAPH, + COMMANDENDCOMMAND, + COMMANDWORDPARAGRAPH, + COMMANDWORDLINE, + COMMANDWORDOWORDWORD, + COMMANDOWORD, + COMMANDERRORTHROW, + COMMANDUNIQUE, + COMMAND_HTML, + COMMAND_HTML_ENTITY, + COMMAND_ALIAS, + COMMAND_IGNORE, + END_LINE, + PARAGRAPH_END, + PLAINSTRING, + COMMAND + }; + + + /** This class contains parts of Doxygen comment as a token. */ + class Token { + public: + DoxyCommandEnum m_tokenType; + std::string m_tokenString; /* the data , such as param for @param */ + + Token(DoxyCommandEnum tType, std::string tString) : m_tokenType(tType), m_tokenString(tString) { + } + + std::string toString() const { + switch (m_tokenType) { + case END_LINE: + return "{END OF LINE}"; + case PARAGRAPH_END: + return "{END OF PARAGRAPH}"; + case PLAINSTRING: + return "{PLAINSTRING :" + m_tokenString + "}"; + case COMMAND: + return "{COMMAND : " + m_tokenString + "}"; + default: + return ""; + } + } + }; + + + typedef std::vector<Token> TokenList; + typedef TokenList::const_iterator TokenListCIt; + typedef TokenList::iterator TokenListIt; + + TokenList m_tokenList; + TokenListCIt m_tokenListIt; + + typedef std::map<std::string, DoxyCommandEnum> DoxyCommandsMap; + typedef DoxyCommandsMap::iterator DoxyCommandsMapIt; + + /* + * Map of Doxygen commands to determine if a string is a + * command and how it needs to be parsed + */ + static DoxyCommandsMap doxygenCommands; + static std::set<std::string> doxygenSectionIndicators; + + bool m_isVerbatimText; // used to handle \htmlonly and \verbatim commands + bool m_isInQuotedString; + + Node *m_node; + std::string m_fileName; + int m_fileLineNo; + + /* + * Return the end command for a command appearing in "ignore" feature or empty + * string if this is a simple command and not a block one. + */ + std::string getIgnoreFeatureEndCommand(const std::string &theCommand) const; + + /* + * Helper for getting the value of doxygen:ignore feature or its argument. + */ + String *getIgnoreFeature(const std::string &theCommand, const char *argument = NULL) const; + + /* + * Whether to print lots of debug info during parsing + */ + bool noisy; + + /* + *Changes a std::string to all lower case + */ + std::string stringToLower(const std::string &stringToConvert); + + /* + * isSectionIndicator returns a boolean if the command is a section indicator + * This is a helper method for finding the end of a paragraph + * by Doxygen's terms + */ + bool isSectionIndicator(const std::string &smallString); + /* + * Determines how a command should be handled (what group it belongs to + * for parsing rules + */ + DoxyCommandEnum commandBelongs(const std::string &theCommand); + + /* + *prints the parse tree + */ + void printTree(const std::list<DoxygenEntity> &rootList); + + /** + * Returns true if the next token is end of line token. This is important + * when single word commands like \c are at the end of line. + */ + bool isEndOfLine(); + + /** + * Skips spaces, tabs, and end of line tokens. + */ + void skipWhitespaceTokens(); + + /** + * Removes all spaces and tabs from beginning end end of string. + */ + std::string trim(const std::string &text); + + /* + * Returns string of the next token if the next token is PLAINSTRING. Returns + * empty string otherwise. + */ + std::string getNextToken(); + + /* + * Returns the next word ON THE CURRENT LINE ONLY + * if a new line is encountered, returns a blank std::string. + * Updates the iterator if successful. + */ + std::string getNextWord(); + + /* + * Returns the next word, which is not necessarily on the same line. + * Updates the iterator if successful. + */ + std::string getNextWordInComment(); + + /* + * Returns the location of the end of the line as + * an iterator. + */ + TokenListCIt getOneLine(const TokenList &tokList); + + /* + * Returns a properly formatted std::string + * up til ANY command or end of line is encountered. + */ + std::string getStringTilCommand(const TokenList &tokList); + + /* + * Returns a properly formatted std::string + * up til the command specified is encountered + */ + //TODO check that this behaves properly for formulas + std::string getStringTilEndCommand(const std::string &theCommand, const TokenList &tokList); + + /* + * Returns the end of a Paragraph as an iterator- + * Paragraph is defined in Doxygen to be a paragraph of text + * separated by either a structural command or a blank line + */ + TokenListCIt getEndOfParagraph(const TokenList &tokList); + + /* + * Returns the end of a section, defined as the first blank line OR first + * encounter of the same command. Example of this behaviour is \arg. + * If no end is encountered, returns the last token of the std::list. + */ + TokenListCIt getEndOfSection(const std::string &theCommand, const TokenList &tokList); + + /* + * This method is for returning the end of a specific form of doxygen command + * that begins with a \command and ends in \endcommand + * such as \code and \endcode. The proper usage is + * progressTilEndCommand("endcode", tokenList); + * If the end is never encountered, it returns the end of the std::list. + */ + TokenListCIt getEndCommand(const std::string &theCommand, const TokenList &tokList); + /* + * A special method for commands such as \arg that end at the end of a + * paragraph OR when another \arg is encountered + //TODO getTilAnyCommand + TokenListCIt getTilAnyCommand(const std::string &theCommand, const TokenList &tokList); + */ + + /** + * This methods skips end of line token, if it is the next token to be + * processed. It is called with comment commands which have args till the + * end of line, such as 'addtogroup' or 'addindex'. + * It is up to translator to specific language to decide whether + * to insert eol or not. For example, if a command is ignored in target + * language, new lines may make formatting ugly (Python). + */ + void skipEndOfLine(); + + /* + * Method for Adding a Simple Command + * Format: @command + * Plain commands, such as newline etc, they contain no other data + * \n \\ \@ \& \$ \# \< \> \% + */ + void addSimpleCommand(const std::string &theCommand, DoxygenEntityList &doxyList); + /* + * CommandWord + * Format: @command <word> + * Commands with a single WORD after then such as @b + * "a", "b", "c", "e", "em", "p", "def", "enum", "example", "package", + * "relates", "namespace", "relatesalso","anchor", "dontinclude", "include", + * "includelineno" + */ + void addCommandWord(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + /* + * CommandLine + * Format: @command (line) + * Commands with a single LINE after then such as @var + * "addindex", "fn", "name", "line", "var", "skipline", "typedef", "skip", + * "until", "property" + */ + void addCommandLine(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + /* + * CommandParagraph + * Format: @command {paragraph} + * Commands with a single paragraph after then such as @return + * "return", "remarks", "since", "test", "sa", "see", "pre", "post", + * "details", "invariant", "deprecated", "date", "note", "warning", + * "version", "todo", "bug", "attention", "brief", "arg", "author" + */ + void addCommandParagraph(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + /* + * Command EndCommand + * Format: @command and ends at @endcommand + * Commands that take in a block of text such as @code: + * "code", "dot", "msc", "f$", "f[", "f{environment}{", "htmlonly", + * "latexonly", "manonly", "verbatim", "xmlonly", "cond", "if", "ifnot", + * "link" + * Returns 1 if success, 0 if the endcommand is never encountered. + */ + void addCommandEndCommand(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + /* + * CommandWordParagraph + * Format: @command <word> {paragraph} + * Commands such as param + * "param", "tparam", "throw", "throws", "retval", "exception" + */ + void addCommandWordParagraph(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + /* + * CommandWordLine + * Format: @command <word> (line) + * Commands such as param + * "page", "subsection", "subsubsection", "section", "paragraph", "defgroup" + */ + void addCommandWordLine(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + /* + * Command Word Optional Word Optional Word + * Format: @command <word> [<header-file>] [<header-name>] + * Commands such as class + * "category", "class", "protocol", "interface", "struct", "union" + */ + void addCommandWordOWordOWord(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + /* + * Command Optional Word + * Format: @command [<word>] + * Commands such as dir + * "dir", "file", "cond" + */ + void addCommandOWord(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + + /* + * Commands that should not be encountered (such as PHP only) + * goes til the end of line then returns + */ + void addCommandErrorThrow(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + + void addCommandHtml(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + + void addCommandHtmlEntity(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + + /* + *Adds the unique commands- different process for each unique command + */ + void addCommandUnique(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + + /* + * Replace the given command with its predefined alias expansion. + */ + void aliasCommand(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + + /* + * Simply ignore the given command, possibly with the word following it or + * until the matching end command. + */ + void ignoreCommand(const std::string &theCommand, const TokenList &tokList, DoxygenEntityList &doxyList); + + /* + * The actual "meat" of the doxygen parser. Calls the correct addCommand...() + * function. + */ + void addCommand(const std::string &commandString, const TokenList &tokList, DoxygenEntityList &doxyList); + + DoxygenEntityList parse(TokenListCIt endParsingIndex, const TokenList &tokList, bool root = false); + + /* + * Fill static doxygenCommands and sectionIndicators containers + */ + void fillTables(); + + /** Processes comment when \htmlonly and \verbatim commands are encountered. */ + size_t processVerbatimText(size_t pos, const std::string &line); + + bool processEscapedChars(size_t &pos, const std::string &line); + void processWordCommands(size_t &pos, const std::string &line); + void processHtmlTags(size_t &pos, const std::string &line); + void processHtmlEntities(size_t &pos, const std::string &line); + + + /** Processes comment outside \htmlonly and \verbatim commands. */ + size_t processNormalComment(size_t pos, const std::string &line); + + void tokenizeDoxygenComment(const std::string &doxygenComment, const std::string &fileName, int fileLine); + void printList(); + void printListError(int warningType, const std::string &message); + + typedef std::vector<std::string> StringVector; + typedef StringVector::const_iterator StringVectorCIt; + + StringVector split(const std::string &text, char separator); + bool isStartOfDoxyCommentChar(char c); + bool addDoxyCommand(DoxygenParser::TokenList &tokList, const std::string &cmd); + +public: + DoxygenParser(bool noisy = false); + virtual ~DoxygenParser(); + DoxygenEntityList createTree(Node *node, String *documentation); +}; + +#endif diff --git a/Source/Doxygen/doxytranslator.cxx b/Source/Doxygen/doxytranslator.cxx new file mode 100644 index 000000000..2684adcea --- /dev/null +++ b/Source/Doxygen/doxytranslator.cxx @@ -0,0 +1,50 @@ +/* ----------------------------------------------------------------------------- + * This file is part of SWIG, which is licensed as a whole under version 3 + * (or any later version) of the GNU General Public License. Some additional + * terms also apply to certain portions of SWIG. The full details of the SWIG + * license and copyrights can be found in the LICENSE and COPYRIGHT files + * included with the SWIG source code as distributed by the SWIG developers + * and at http://www.swig.org/legal.html. + * + * doxytranslator.cxx + * + * Module to return documentation for nodes formatted for various documentation + * systems. + * ----------------------------------------------------------------------------- */ + +#include "doxytranslator.h" + +DoxygenTranslator::DoxygenTranslator(int flags) : m_flags(flags), parser((flags &debug_parser) != 0) { +} + + +DoxygenTranslator::~DoxygenTranslator() { +} + + +bool DoxygenTranslator::hasDocumentation(Node *node) { + return getDoxygenComment(node) != NULL; +} + + +String *DoxygenTranslator::getDoxygenComment(Node *node) { + return Getattr(node, "doxygen"); +} + + +String *DoxygenTranslator::getDocumentation(Node *node) { + + if (!hasDocumentation(node)) { + return NewString(""); + } + + return makeDocumentation(node); +} + + +void DoxygenTranslator::printTree(const DoxygenEntityList &entityList) { + + for (DoxygenEntityListCIt p = entityList.begin(); p != entityList.end(); p++) { + p->printEntity(0); + } +} diff --git a/Source/Doxygen/doxytranslator.h b/Source/Doxygen/doxytranslator.h new file mode 100644 index 000000000..ffc378a7b --- /dev/null +++ b/Source/Doxygen/doxytranslator.h @@ -0,0 +1,89 @@ +/* ----------------------------------------------------------------------------- + * This file is part of SWIG, which is licensed as a whole under version 3 + * (or any later version) of the GNU General Public License. Some additional + * terms also apply to certain portions of SWIG. The full details of the SWIG + * license and copyrights can be found in the LICENSE and COPYRIGHT files + * included with the SWIG source code as distributed by the SWIG developers + * and at http://www.swig.org/legal.html. + * + * doxytranslator.h + * + * Module to return documentation for nodes formatted for various documentation + * systems. + * ----------------------------------------------------------------------------- */ + +#ifndef DOXYGENTRANSLATOR_H_ +#define DOXYGENTRANSLATOR_H_ + +#include "swig.h" +#include "doxyentity.h" +#include "doxyparser.h" +#include <list> +#include <string> + + +/* + * This is a base class for translator classes. It defines the basic interface + * for translators, which convert Doxygen comments into alternative formats for + * target languages. + */ +class DoxygenTranslator { +public: + /* + * Bit flags for the translator ctor. + * + * Derived classes may define additional flags. + */ + enum { + // Use DoxygenParser in "noisy" mode. + debug_parser = 1, + + // Output results of translating Doxygen comments. + debug_translator = 2 + }; + + /* + * Constructor + */ + DoxygenTranslator(int flags = 0); + + /* + * Virtual destructor. + */ + virtual ~DoxygenTranslator(); + + /* + * Return the documentation for a given node formated for the correct + * documentation system. + */ + String *getDocumentation(Node *node); + + /* + * Returns truem is the specified node has comment attached. + */ + bool hasDocumentation(Node *node); + + /* + * Get original comment string in Doxygen-format. + */ + String *getDoxygenComment(Node *node); + +protected: + // The flags passed to the ctor. + const int m_flags; + + DoxygenParser parser; + + /* + * Returns the documentation formatted for a target language. + */ + virtual String *makeDocumentation(Node *node) = 0; + + /* + * Prints the details of a parsed entity list to stdout (for debugging). + */ + void printTree(const DoxygenEntityList &entityList); + +}; + +#endif diff --git a/Source/Doxygen/javadoc.cxx b/Source/Doxygen/javadoc.cxx new file mode 100644 index 000000000..3b81c55a5 --- /dev/null +++ b/Source/Doxygen/javadoc.cxx @@ -0,0 +1,844 @@ +/* ----------------------------------------------------------------------------- + * This file is part of SWIG, which is licensed as a whole under version 3 + * (or any later version) of the GNU General Public License. Some additional + * terms also apply to certain portions of SWIG. The full details of the SWIG + * license and copyrights can be found in the LICENSE and COPYRIGHT files + * included with the SWIG source code as distributed by the SWIG developers + * and at http://www.swig.org/legal.html. + * + * javadoc.cxx + * ----------------------------------------------------------------------------- */ + +#include "javadoc.h" +#include "doxyparser.h" +#include <iostream> +#include <vector> +#include <list> +#include "swigmod.h" +#define APPROX_LINE_LENGTH 64 // characters per line allowed +#define TAB_SIZE 8 // current tab size in spaces +//TODO {@link} {@linkplain} {@docRoot}, and other useful doxy commands that are not a javadoc tag + +// define static tables, they are filled in JavaDocConverter's constructor +std::map<std::string, std::pair<JavaDocConverter::tagHandler, std::string> > JavaDocConverter::tagHandlers; + +using std::string; +using std::list; +using std::vector; + +void JavaDocConverter::fillStaticTables() { + if (tagHandlers.size()) // fill only once + return; + + /* + * Some translation rules: + * + * @ and \ must be escaped for both Java and Python to appear on output: \@, \\, + * while Doxygen produces output in both cases. + * Rule: @ and \ with space on the right should get to output. + * + * :: remains intact, even in class::method(). But you can use class#method also + * in C++ comment and it is properly translated to C++ output (changed by doxygen to ::) + * and Java output (remains #). + * Rule: SWIG type system can't be used to convert C::m to C#m, because in Java it is C.m + * Use string replacement :: --> # in tag see and links. + * + * HTML tags must be translated - remain in Java, to markdown in Python + * + * Unknown HTML tags, for example <x> is translated to <x> by doxygen, while + * Java src is <x> and therefore invisible on output - browser ignores unknown command. + * This is handy in syntax descriptions, for example: more <fileName>. + * + * Standalone < and > need not be translated, they are rendered properly in + * all three outputs. + * + * ., %, and " need not to be translated + * + * entities must be translated - remain in Java, something meaningful in Python (<, ...) + * + * - Python + * - add comments also to auto-generated methods like equals(), delete() in Java, + * and methods for std::vector(), ... + * Commenting methods of std types is simple - add comment to std_*.i file. + */ + + // these commands insert HTML tags + tagHandlers["a"] = make_pair(&JavaDocConverter::handleTagHtml, "i"); + tagHandlers["arg"] = make_pair(&JavaDocConverter::handleTagHtml, "li"); + tagHandlers["b"] = make_pair(&JavaDocConverter::handleTagHtml, "b"); + tagHandlers["c"] = make_pair(&JavaDocConverter::handleTagHtml, "code"); + tagHandlers["cite"] = make_pair(&JavaDocConverter::handleTagHtml, "i"); + tagHandlers["e"] = make_pair(&JavaDocConverter::handleTagHtml, "i"); + tagHandlers["em"] = make_pair(&JavaDocConverter::handleTagHtml, "i"); + tagHandlers["li"] = make_pair(&JavaDocConverter::handleTagHtml, "li"); + tagHandlers["p"] = make_pair(&JavaDocConverter::handleTagHtml, "code"); + // these commands insert just a single char, some of them need to be escaped + tagHandlers["$"] = make_pair(&JavaDocConverter::handleTagChar, ""); + tagHandlers["@"] = make_pair(&JavaDocConverter::handleTagChar, ""); + tagHandlers["\\"] = make_pair(&JavaDocConverter::handleTagChar, ""); + tagHandlers["<"] = make_pair(&JavaDocConverter::handleTagChar, "<"); + tagHandlers[">"] = make_pair(&JavaDocConverter::handleTagChar, ">"); + tagHandlers["&"] = make_pair(&JavaDocConverter::handleTagChar, "&"); + tagHandlers["#"] = make_pair(&JavaDocConverter::handleTagChar, ""); + tagHandlers["%"] = make_pair(&JavaDocConverter::handleTagChar, ""); + tagHandlers["~"] = make_pair(&JavaDocConverter::handleTagChar, ""); + tagHandlers["\""] = make_pair(&JavaDocConverter::handleTagChar, """); + tagHandlers["."] = make_pair(&JavaDocConverter::handleTagChar, ""); + tagHandlers["::"] = make_pair(&JavaDocConverter::handleTagChar, ""); + // these commands are stripped out + tagHandlers["attention"] = make_pair(&JavaDocConverter::handleParagraph, ""); + tagHandlers["anchor"] = make_pair(&JavaDocConverter::handleTagAnchor, ""); + tagHandlers["brief"] = make_pair(&JavaDocConverter::handleParagraph, ""); + tagHandlers["bug"] = make_pair(&JavaDocConverter::handleParagraph, ""); + tagHandlers["date"] = make_pair(&JavaDocConverter::handleParagraph, ""); + tagHandlers["details"] = make_pair(&JavaDocConverter::handleParagraph, ""); + // this command is inserts text accumulated after cmd htmlonly - + // see DoxygenParser - CMD_HTML_ONLY. + tagHandlers["htmlonly"] = make_pair(&JavaDocConverter::handleParagraph, ""); + tagHandlers["invariant"] = make_pair(&JavaDocConverter::handleParagraph, ""); + tagHandlers["latexonly"] = make_pair(&JavaDocConverter::handleParagraph, ""); + tagHandlers["manonly"] = make_pair(&JavaDocConverter::handleParagraph, ""); + tagHandlers["partofdescription"] = make_pair(&JavaDocConverter::handleParagraph, ""); + tagHandlers["rtfonly"] = make_pair(&JavaDocConverter::handleParagraph, ""); + tagHandlers["short"] = make_pair(&JavaDocConverter::handleParagraph, ""); + tagHandlers["xmlonly"] = make_pair(&JavaDocConverter::handleParagraph, ""); + // these commands are kept as-is, they are supported by JavaDoc + tagHandlers["author"] = make_pair(&JavaDocConverter::handleTagSame, ""); + tagHandlers["authors"] = make_pair(&JavaDocConverter::handleTagSame, "author"); + tagHandlers["deprecated"] = make_pair(&JavaDocConverter::handleTagSame, ""); + tagHandlers["exception"] = make_pair(&JavaDocConverter::handleTagSame, ""); + tagHandlers["package"] = make_pair(&JavaDocConverter::handleTagSame, ""); + tagHandlers["param"] = make_pair(&JavaDocConverter::handleTagParam, ""); + tagHandlers["tparam"] = make_pair(&JavaDocConverter::handleTagParam, ""); + tagHandlers["ref"] = make_pair(&JavaDocConverter::handleTagRef, ""); + tagHandlers["result"] = make_pair(&JavaDocConverter::handleTagSame, "return"); + tagHandlers["return"] = make_pair(&JavaDocConverter::handleTagSame, ""); + tagHandlers["returns"] = make_pair(&JavaDocConverter::handleTagSame, "return"); + //tagHandlers["see"] = make_pair(&JavaDocConverter::handleTagSame, ""); + //tagHandlers["sa"] = make_pair(&JavaDocConverter::handleTagSame, "see"); + tagHandlers["since"] = make_pair(&JavaDocConverter::handleTagSame, ""); + tagHandlers["throws"] = make_pair(&JavaDocConverter::handleTagSame, ""); + tagHandlers["throw"] = make_pair(&JavaDocConverter::handleTagSame, "throws"); + tagHandlers["version"] = make_pair(&JavaDocConverter::handleTagSame, ""); + // these commands have special handlers + tagHandlers["code"] = make_pair(&JavaDocConverter::handleTagExtended, "code"); + tagHandlers["cond"] = make_pair(&JavaDocConverter::handleTagMessage, "Conditional comment: "); + tagHandlers["copyright"] = make_pair(&JavaDocConverter::handleTagMessage, "Copyright: "); + tagHandlers["else"] = make_pair(&JavaDocConverter::handleTagIf, "Else: "); + tagHandlers["elseif"] = make_pair(&JavaDocConverter::handleTagIf, "Else if: "); + tagHandlers["endcond"] = make_pair(&JavaDocConverter::handleTagMessage, "End of conditional comment."); + // space in second arg prevents Javadoc to treat '@ example' as command. File name of + // example is still informative to user. + tagHandlers["example"] = make_pair(&JavaDocConverter::handleTagSame, " example"); + tagHandlers["if"] = make_pair(&JavaDocConverter::handleTagIf, "If: "); + tagHandlers["ifnot"] = make_pair(&JavaDocConverter::handleTagIf, "If not: "); + tagHandlers["image"] = make_pair(&JavaDocConverter::handleTagImage, ""); + tagHandlers["link"] = make_pair(&JavaDocConverter::handleTagLink, ""); + tagHandlers["see"] = make_pair(&JavaDocConverter::handleTagSee, ""); + tagHandlers["sa"] = make_pair(&JavaDocConverter::handleTagSee, ""); + tagHandlers["note"] = make_pair(&JavaDocConverter::handleTagMessage, "Note: "); + tagHandlers["overload"] = make_pair(&JavaDocConverter::handleTagMessage, + "This is an overloaded member function, provided for" + " convenience. It differs from the above function only in what" " argument(s) it accepts."); + tagHandlers["par"] = make_pair(&JavaDocConverter::handleTagPar, ""); + tagHandlers["remark"] = make_pair(&JavaDocConverter::handleTagMessage, "Remarks: "); + tagHandlers["remarks"] = make_pair(&JavaDocConverter::handleTagMessage, "Remarks: "); + tagHandlers["todo"] = make_pair(&JavaDocConverter::handleTagMessage, "TODO: "); + tagHandlers["verbatim"] = make_pair(&JavaDocConverter::handleTagExtended, "literal"); + + // \f commands output literal Latex formula, which is still better than nothing. + tagHandlers["f$"] = make_pair(&JavaDocConverter::handleTagVerbatim, ""); + tagHandlers["f["] = make_pair(&JavaDocConverter::handleTagVerbatim, ""); + tagHandlers["f{"] = make_pair(&JavaDocConverter::handleTagVerbatim, ""); + + tagHandlers["warning"] = make_pair(&JavaDocConverter::handleTagMessage, "Warning: "); + // this command just prints it's contents + // (it is internal command of swig's parser, contains plain text) + tagHandlers["plainstd::string"] = make_pair(&JavaDocConverter::handlePlainString, ""); + tagHandlers["plainstd::endl"] = make_pair(&JavaDocConverter::handleNewLine, ""); + tagHandlers["n"] = make_pair(&JavaDocConverter::handleNewLine, ""); + + // HTML tags + tagHandlers["<a"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<a"); + tagHandlers["<b"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<b"); + tagHandlers["<blockquote"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<blockquote"); + tagHandlers["<body"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<body"); + tagHandlers["<br"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<br"); + tagHandlers["<center"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<center"); + tagHandlers["<caption"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<caption"); + tagHandlers["<code"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<code"); + tagHandlers["<dd"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<dd"); + tagHandlers["<dfn"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<dfn"); + tagHandlers["<div"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<div"); + tagHandlers["<dl"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<dl"); + tagHandlers["<dt"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<dt"); + tagHandlers["<em"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<em"); + tagHandlers["<form"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<form"); + tagHandlers["<hr"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<hr"); + tagHandlers["<h1"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<h1"); + tagHandlers["<h2"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<h2"); + tagHandlers["<h3"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<h3"); + tagHandlers["<i"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<i"); + tagHandlers["<input"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<input"); + tagHandlers["<img"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<img"); + tagHandlers["<li"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<li"); + tagHandlers["<meta"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<meta"); + tagHandlers["<multicol"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<multicol"); + tagHandlers["<ol"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<ol"); + tagHandlers["<p"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<p"); + tagHandlers["<pre"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<pre"); + tagHandlers["<small"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<small"); + tagHandlers["<span"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<span"); + tagHandlers["<strong"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<strong"); + tagHandlers["<sub"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<sub"); + tagHandlers["<sup"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<sup"); + tagHandlers["<table"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<table"); + tagHandlers["<td"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<td"); + tagHandlers["<th"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<th"); + tagHandlers["<tr"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<tr"); + tagHandlers["<tt"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<tt"); + tagHandlers["<kbd"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<kbd"); + tagHandlers["<ul"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<ul"); + tagHandlers["<var"] = make_pair(&JavaDocConverter::handleDoxyHtmlTag, "<var"); + + // HTML entities + tagHandlers["©"] = make_pair(&JavaDocConverter::handleHtmlEntity, "©"); + tagHandlers["&trade"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&trade"); + tagHandlers["®"] = make_pair(&JavaDocConverter::handleHtmlEntity, "®"); + tagHandlers["<"] = make_pair(&JavaDocConverter::handleHtmlEntity, "<"); + tagHandlers[">"] = make_pair(&JavaDocConverter::handleHtmlEntity, ">"); + tagHandlers["&"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&"); + tagHandlers["&apos"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&apos"); + tagHandlers["""] = make_pair(&JavaDocConverter::handleHtmlEntity, """); + tagHandlers["&lsquo"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&lsquo"); + tagHandlers["&rsquo"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&rsquo"); + tagHandlers["&ldquo"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&ldquo"); + tagHandlers["&rdquo"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&rdquo"); + tagHandlers["&ndash"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&ndash"); + tagHandlers["&mdash"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&mdash"); + tagHandlers[" "] = make_pair(&JavaDocConverter::handleHtmlEntity, " "); + tagHandlers["×"] = make_pair(&JavaDocConverter::handleHtmlEntity, "×"); + tagHandlers["&minus"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&minus"); + tagHandlers["&sdot"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&sdot"); + tagHandlers["&sim"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&sim"); + tagHandlers["&le"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&le"); + tagHandlers["&ge"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&ge"); + tagHandlers["&larr"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&larr"); + tagHandlers["&rarr"] = make_pair(&JavaDocConverter::handleHtmlEntity, "&rarr"); +} + +JavaDocConverter::JavaDocConverter(int flags) : + DoxygenTranslator(flags) { + fillStaticTables(); +} + +/** + * Formats comment lines by inserting '\n *' at to long lines and tabs for + * indent. Currently it is disabled, which means original comment format is + * preserved. Experience shows, that this is usually better than breaking + * lines automatically, especially because original line endings are not removed, + * which results in short lines. To be useful, this function should have much + * better algorithm. + */ +std::string JavaDocConverter::formatCommand(std::string unformattedLine, int indent) { + std::string formattedLines; + return unformattedLine; // currently disabled + int lastPosition = 0; + int i = 0; + int isFirstLine = 1; + while (i != -1 && i < (int) unformattedLine.length()) { + lastPosition = i; + if (isFirstLine) { + i += APPROX_LINE_LENGTH; + } else { + i += APPROX_LINE_LENGTH - indent * TAB_SIZE; + } + + i = unformattedLine.find(" ", i); + + if (i > 0 && i + 1 < (int) unformattedLine.length()) { + if (!isFirstLine) + for (int j = 0; j < indent; j++) { + formattedLines.append("\t"); + } else { + isFirstLine = 0; + } + formattedLines.append(unformattedLine.substr(lastPosition, i - lastPosition + 1)); + formattedLines.append("\n *"); + + } + } + if (lastPosition < (int) unformattedLine.length()) { + if (!isFirstLine) { + for (int j = 0; j < indent; j++) { + formattedLines.append("\t"); + } + } + formattedLines.append(unformattedLine.substr(lastPosition, unformattedLine.length() - lastPosition)); + } + + return formattedLines; +} + +/** + * Returns true, if the given parameter exists in the current node + * (for example param is a name of function parameter). If feature + * 'doxygen:nostripparams' is set, then this method always returns + * true - parameters are copied to output regardless of presence in + * function params list. + */ +bool JavaDocConverter::paramExists(std::string param) { + + if (GetFlag(currentNode, "feature:doxygen:nostripparams")) { + return true; + } + + ParmList *plist = CopyParmList(Getattr(currentNode, "parms")); + + for (Parm *p = plist; p;) { + + if (Getattr(p, "name") && Char(Getattr(p, "name")) == param) { + return true; + } + /* doesn't seem to work always: in some cases (especially for 'self' parameters) + * tmap:in is present, but tmap:in:next is not and so this code skips all the parameters + */ + //p = Getattr(p, "tmap:in") ? Getattr(p, "tmap:in:next") : nextSibling(p); + p = nextSibling(p); + } + + Delete(plist); + + return false; +} + +std::string JavaDocConverter::translateSubtree(DoxygenEntity &doxygenEntity) { + std::string translatedComment; + + if (doxygenEntity.isLeaf) { + return translatedComment; + } + + for (DoxygenEntityListIt p = doxygenEntity.entityList.begin(); p != doxygenEntity.entityList.end(); p++) { + + translateEntity(*p, translatedComment); + translateSubtree(*p); + } + + return translatedComment; +} + +/** + * Checks if a handler for the given tag exists, and calls it. + */ +void JavaDocConverter::translateEntity(DoxygenEntity &tag, std::string &translatedComment) { + + std::map<std::string, std::pair<tagHandler, std::string> >::iterator it; + it = tagHandlers.find(tag.typeOfEntity); + + if (it != tagHandlers.end()) { + (this->*(it->second.first))(tag, translatedComment, it->second.second); + } else { + // do NOT print warning, since there are many tags, which are not + // translatable - many warnings hide important ones + // addError(WARN_DOXYGEN_COMMAND_ERROR, "Unknown doxygen or HTML tag: " + tag.typeOfEntity); + } +} + + +void JavaDocConverter::handleTagAnchor(DoxygenEntity &tag, std::string &translatedComment, std::string &) { + translatedComment += "<a id=\"" + translateSubtree(tag) + "\"></a>"; +} + + +void JavaDocConverter::handleTagHtml(DoxygenEntity &tag, std::string &translatedComment, std::string &arg) { + if (tag.entityList.size()) { // do not include empty tags + std::string tagData = translateSubtree(tag); + // wrap the thing, ignoring whitespace + size_t wsPos = tagData.find_last_not_of("\n\t "); + if (wsPos != std::string::npos) + translatedComment += "<" + arg + ">" + tagData.substr(0, wsPos + 1) + "</" + arg + ">" + tagData.substr(wsPos + 1); + else + translatedComment += "<" + arg + ">" + translateSubtree(tag) + "</" + arg + "> "; + } +} + +void JavaDocConverter::handleDoxyHtmlTag(DoxygenEntity &tag, std::string &translatedComment, std::string &arg) { + std::string htmlTagArgs = tag.data; + if (htmlTagArgs == "/") { + // end html tag, for example "</ul> + translatedComment += "</" + arg.substr(1) + ">"; + } else { + translatedComment += arg + htmlTagArgs + ">"; + } +} + +void JavaDocConverter::handleHtmlEntity(DoxygenEntity &, std::string &translatedComment, std::string &arg) { + // html entities can be preserved for Java + translatedComment += arg + ';'; +} + +void JavaDocConverter::handleNewLine(DoxygenEntity &, std::string &translatedComment, std::string &) { + // <br> tag is added, because otherwise to much text is joined + // into same paragraph by javadoc. For example, doxy list: + // - item one + // - item two + // becomes one paragraph with surrounding text without newlines. + // This way we get to many empty lines in javadoc output, but this + // is still better than joined lines. Possibility for improvements + // exists. + translatedComment += "<br>\n * "; +} + +void JavaDocConverter::handleTagChar(DoxygenEntity &tag, std::string &translatedComment, std::string &arg) { + // escape it if we need to, else just print + if (arg.size()) + translatedComment += arg; + else + translatedComment += tag.typeOfEntity; +} + +// handles tags which are the same in Doxygen and Javadoc. +void JavaDocConverter::handleTagSame(DoxygenEntity &tag, std::string &translatedComment, std::string &arg) { + if (arg.size()) + tag.typeOfEntity = arg; + translatedComment += formatCommand(std::string("@" + tag.typeOfEntity + " " + translateSubtree(tag)), 2); +} + +void JavaDocConverter::handleParagraph(DoxygenEntity &tag, std::string &translatedComment, std::string &) { + translatedComment += formatCommand(translateSubtree(tag), 0); +} + +void JavaDocConverter::handlePlainString(DoxygenEntity &tag, std::string &translatedComment, std::string &) { + translatedComment += tag.data; + // if (tag.data.size() && tag.data[tag.data.size()-1] != ' ') + // translatedComment += " "; +} + +void JavaDocConverter::handleTagVerbatim(DoxygenEntity &tag, std::string &translatedComment, std::string &arg) { + translatedComment += arg + " "; + for (DoxygenEntityListCIt it = tag.entityList.begin(); it != tag.entityList.end(); it++) { + translatedComment += it->data; + } +} + +void JavaDocConverter::handleTagExtended(DoxygenEntity &tag, std::string &translatedComment, std::string &arg) { + std::string dummy; + translatedComment += "{@" + arg + " "; + handleParagraph(tag, translatedComment, dummy); + translatedComment += "}"; +} + +void JavaDocConverter::handleTagIf(DoxygenEntity &tag, std::string &translatedComment, std::string &arg) { + std::string dummy; + translatedComment += arg; + if (tag.entityList.size()) { + translatedComment += tag.entityList.begin()->data; + tag.entityList.pop_front(); + translatedComment += " {" + translateSubtree(tag) + "}"; + } +} + +void JavaDocConverter::handleTagMessage(DoxygenEntity &tag, std::string &translatedComment, std::string &arg) { + std::string dummy; + translatedComment += formatCommand(arg, 0); + handleParagraph(tag, translatedComment, dummy); +} + +void JavaDocConverter::handleTagImage(DoxygenEntity &tag, std::string &translatedComment, std::string &) { + if (tag.entityList.size() < 2) + return; + + std::string file; + std::string title; + + std::list<DoxygenEntity>::iterator it = tag.entityList.begin(); + if (it->data != "html") + return; + + it++; + file = it->data; + + it++; + if (it != tag.entityList.end()) + title = it->data; + + translatedComment += "<img src=" + file; + if (title.size()) + translatedComment += " alt=" + title; + + // the size indication is supported for Latex only in Doxygen, see manual + + translatedComment += "/>"; +} + +void JavaDocConverter::handleTagPar(DoxygenEntity &tag, std::string &translatedComment, std::string &) { + std::string dummy; + translatedComment += "<p"; + if (tag.entityList.size()) { + translatedComment += " alt=\"" + tag.entityList.begin()->data + "\""; + translatedComment += ">"; + tag.entityList.pop_front(); + handleParagraph(tag, translatedComment, dummy); + } + translatedComment += "</p>"; +} + + +void JavaDocConverter::handleTagParam(DoxygenEntity &tag, std::string &translatedComment, std::string &) { + std::string dummy; + + if (!tag.entityList.size()) + return; + if (!paramExists(tag.entityList.begin()->data)) + return; + + translatedComment += "@param "; + translatedComment += tag.entityList.begin()->data; + tag.entityList.pop_front(); + handleParagraph(tag, translatedComment, dummy); +} + + +void JavaDocConverter::handleTagRef(DoxygenEntity &tag, std::string &translatedComment, std::string &) { + std::string dummy; + if (!tag.entityList.size()) + return; + + // we translate to link, although \page is not supported in Java, but + // reader at least knows what to look at. Also for \anchor tag on the same + // page this link works. + string anchor = tag.entityList.begin()->data; + tag.entityList.pop_front(); + string anchorText = anchor; + if (!tag.entityList.empty()) { + anchorText = tag.entityList.begin()->data; + } + translatedComment += "<a href=\"#" + anchor + "\">" + anchorText + "</a>"; +} + + +string JavaDocConverter::convertLink(string linkObject) { + if (GetFlag(currentNode, "feature:doxygen:nolinktranslate")) + return linkObject; + // find the params in function in linkObject (if any) + size_t lbracePos = linkObject.find('(', 0); + size_t rbracePos = linkObject.find(')', 0); + if (lbracePos == string::npos || rbracePos == string::npos || lbracePos >= rbracePos) + return ""; + + string paramsStr = linkObject.substr(lbracePos + 1, + rbracePos - lbracePos - 1); + // strip the params, to fill them later + string additionalObject = linkObject.substr(rbracePos + 1, string::npos); + linkObject = linkObject.substr(0, lbracePos); + + // find all the params + vector<string> params; + size_t lastPos = 0, commaPos = 0; + while (true) { + commaPos = paramsStr.find(',', lastPos); + if (commaPos == string::npos) + commaPos = paramsStr.size(); + string param = paramsStr.substr(lastPos, commaPos - lastPos); + // if any param type is empty, we are failed + if (!param.size()) + return ""; + params.push_back(param); + lastPos = commaPos + 1; + if (lastPos >= paramsStr.size()) + break; + } + + linkObject += "("; + for (size_t i = 0; i < params.size(); i++) { + // translate c/c++ type string to swig's type + // i e 'int **arr[100][10]' -> 'a(100).a(10).p.p.int' + // also converting arrays to pointers + string paramStr = params[i]; + String *swigType = NewString(""); + + // handle const qualifier + if (paramStr.find("const") != string::npos) + SwigType_add_qualifier(swigType, "const"); + + // handle pointers, references and arrays + for (int j = (int)params[i].size() - 1; j >= 0; j--) { + // skip all the [...] blocks, write 'p.' for every of it + if (paramStr[j] == ']') { + while (j >= 0 && paramStr[j] != '[') + j--; + // no closing brace + if (j < 0) + return ""; + SwigType_add_pointer(swigType); + continue; + } else if (paramStr[j] == '*') + SwigType_add_pointer(swigType); + else if (paramStr[j] == '&') + SwigType_add_reference(swigType); + else if (isalnum(paramStr[j])) { + size_t typeNameStart = paramStr.find_last_of(' ', j + 1); + if (typeNameStart == string::npos) + typeNameStart = 0; + else + typeNameStart++; + Append(swigType, paramStr.substr(typeNameStart, j - typeNameStart + 1).c_str()); + break; + } + } + + // make dummy param list, to lookup typemaps for it + Parm *dummyParam = NewParm(swigType, "", 0); + Swig_typemap_attach_parms("jstype", dummyParam, NULL); + Language::instance()->replaceSpecialVariables(0, Getattr(dummyParam, "tmap:jstype"), dummyParam); + + //Swig_print(dummyParam, 1); + linkObject += Char(Getattr(dummyParam, "tmap:jstype")); + if (i != params.size() - 1) + linkObject += ","; + + Delete(dummyParam); + Delete(swigType); + } + linkObject += ")"; + + return linkObject + additionalObject; +} + +void JavaDocConverter::handleTagLink(DoxygenEntity &tag, std::string &translatedComment, std::string &) { + std::string dummy; + if (!tag.entityList.size()) + return; + + string linkObject = convertLink(tag.entityList.begin()->data); + if (!linkObject.size()) + linkObject = tag.entityList.begin()->data; + tag.entityList.pop_front(); + + translatedComment += "{@link "; + translatedComment += linkObject + " "; + handleParagraph(tag, translatedComment, dummy); + translatedComment += "}"; +} + +void JavaDocConverter::handleTagSee(DoxygenEntity &tag, std::string &translatedComment, std::string &) { + std::string dummy; + if (!tag.entityList.size()) + return; + + // tag.entity list contains contents of the @see paragraph. It should contain + // one link (references) to method with or without parameters. Doxygen supports + // arbitrary text and types mixed, but this feature is not supported here. + // :: or # may be used as a separator between class name and method name. + list<DoxygenEntity>::iterator it; + string methodRef; + for (it = tag.entityList.begin(); it != tag.entityList.end(); it++) { + if (it->typeOfEntity == "plainstd::endl") { + // handleNewLine(*it, translatedComment, dummy); + continue; + } + // restore entities which may be used in C++ type declaration + if (it->typeOfEntity == "&") { + methodRef += '&'; + } else if (it->typeOfEntity == "<") { + methodRef += '<'; + } else if (it->typeOfEntity == ">") { + methodRef += '>'; + } else { + methodRef += it->data; + } + } + + // replace :: with #, but only if it appears before left brace + size_t lbrace = methodRef.find('('); + size_t dblColon = methodRef.find("::"); + if (dblColon < lbrace) { + methodRef = methodRef.substr(0, dblColon) + '#' + methodRef.substr(dblColon + 2); + } + + translatedComment += "@see "; + string linkObject = convertLink(methodRef); + if (!linkObject.size()) { + linkObject = methodRef; + } + translatedComment += linkObject; +} + +/* This function moves all line endings at the end of child entities + * out of the child entities to the parent. + * For example, entity tree: + + -root + |-param + |-paramText + |-endline + + should be turned to + + -root + |-param + |-paramText + |-endline + * + */ +int JavaDocConverter::shiftEndlinesUpTree(DoxygenEntity &root, int level) { + DoxygenEntityListIt it = root.entityList.begin(); + while (it != root.entityList.end()) { + // remove line endings + int ret = shiftEndlinesUpTree(*it, level + 1); + // insert them after this element + it++; + for (int i = 0; i < ret; i++) { + root.entityList.insert(it, DoxygenEntity("plainstd::endl")); + } + } + + // continue only if we are not root + if (!level) { + return 0; + } + + int removedCount = 0; + while (!root.entityList.empty() + && root.entityList.rbegin()->typeOfEntity == "plainstd::endl") { + root.entityList.pop_back(); + removedCount++; + } + return removedCount; +} + +/** + * This makes sure that all comment lines contain '*'. It is not mandatory in doxygen, + * but highly recommended for Javadoc. '*' in empty lines are indented according + * to indentation of the first line. Indentation of non-empty lines is not + * changed - garbage in garbage out. + */ +std::string JavaDocConverter::indentAndInsertAsterisks(const string &doc) { + + size_t idx = doc.find('\n'); + size_t indent = 0; + // Detect indentation. + // The first line in comment is the one after '/**', which may be + // spaces and '\n' or the text. In any case it is not suitable to detect + // indentation, so we have to skip the first '\n'. + if (idx != string::npos) { + size_t nonspaceIdx = doc.find_first_not_of(" \t", idx + 1); + if (nonspaceIdx != string::npos) { + indent = nonspaceIdx - idx; + } + } + + if (indent == 0) { + // we can't indent the first line less than 0 + indent = 1; + } + // Create the first line of Javadoc comment. + string indentStr(indent - 1, ' '); + string translatedStr = indentStr + "/**"; + if (indent > 1) { + // remove the first space, so that '*' will be aligned + translatedStr = translatedStr.substr(1); + } + + translatedStr += doc; + + // insert '*' before each comment line, if it does not have it + idx = translatedStr.find('\n'); + + while (idx != string::npos) { + + size_t nonspaceIdx = translatedStr.find_first_not_of(" \t", idx + 1); + if (nonspaceIdx != string::npos && translatedStr[nonspaceIdx] != '*') { + // line without '*' found - is it empty? + if (translatedStr[nonspaceIdx] != '\n') { + // add '* ' to each line without it + translatedStr = translatedStr.substr(0, nonspaceIdx) + "* " + translatedStr.substr(nonspaceIdx); + //printf(translatedStr.c_str()); + } else { + // we found empty line, replace it with indented '*' + translatedStr = translatedStr.substr(0, idx + 1) + indentStr + "* " + translatedStr.substr(nonspaceIdx); + } + } + idx = translatedStr.find('\n', nonspaceIdx); + } + + // Add the last comment line properly indented + size_t nonspaceEndIdx = translatedStr.find_last_not_of(" \t"); + if (nonspaceEndIdx != string::npos) { + if (translatedStr[nonspaceEndIdx] != '\n') { + translatedStr += '\n'; + } else { + // remove trailing spaces + translatedStr = translatedStr.substr(0, nonspaceEndIdx + 1); + } + } + translatedStr += indentStr + "*/\n"; + + return translatedStr; +} + +String *JavaDocConverter::makeDocumentation(Node *node) { + + String *documentation = getDoxygenComment(node); + + if (documentation == NULL) { + return NewString(""); + } + + if (GetFlag(node, "feature:doxygen:notranslate")) { + + string doc = Char(documentation); + + string translatedStr = indentAndInsertAsterisks(doc); + + String *comment = NewString(translatedStr.c_str()); + // Append(comment, documentation); Replaceall(comment, "\n", "\n * "); + return comment; + } + + DoxygenEntityList entityList = parser.createTree(node, documentation); + + // entityList.sort(CompareDoxygenEntities()); sorting currently not used, + + if (m_flags & debug_translator) { + std::cout << "---RESORTED LIST---" << std::endl; + printTree(entityList); + } + // store the current node + // (currently just to handle params) + currentNode = node; + + std::string javaDocString = "/**\n * "; + + DoxygenEntity root("root", entityList); + + shiftEndlinesUpTree(root); + + // strip line endings at the beginning + while (!root.entityList.empty() + && root.entityList.begin()->typeOfEntity == "plainstd::endl") { + root.entityList.pop_front(); + } + + // and at the end + while (!root.entityList.empty() + && root.entityList.rbegin()->typeOfEntity == "plainstd::endl") { + root.entityList.pop_back(); + } + + javaDocString += translateSubtree(root); + + javaDocString += "\n */\n"; + + if (m_flags & debug_translator) { + std::cout << "\n---RESULT IN JAVADOC---" << std::endl; + std::cout << javaDocString; + } + + return NewString(javaDocString.c_str()); +} + +void JavaDocConverter::addError(int warningType, const std::string &message) { + Swig_warning(warningType, "", 0, "Doxygen parser warning: %s. \n", message.c_str()); +} diff --git a/Source/Doxygen/javadoc.h b/Source/Doxygen/javadoc.h new file mode 100644 index 000000000..6feff5295 --- /dev/null +++ b/Source/Doxygen/javadoc.h @@ -0,0 +1,169 @@ +/* ----------------------------------------------------------------------------- + * This file is part of SWIG, which is licensed as a whole under version 3 + * (or any later version) of the GNU General Public License. Some additional + * terms also apply to certain portions of SWIG. The full details of the SWIG + * license and copyrights can be found in the LICENSE and COPYRIGHT files + * included with the SWIG source code as distributed by the SWIG developers + * and at http://www.swig.org/legal.html. + * + * javadoc.h + * + * Module to return documentation for nodes formatted for JavaDoc + * ----------------------------------------------------------------------------- */ + +#ifndef JAVADOCCONVERTER_H_ +#define JAVADOCCONVERTER_H_ + +#include "doxytranslator.h" +#include <map> + +/* + * A class to translate doxygen comments into JavaDoc style comments. + */ +class JavaDocConverter : public DoxygenTranslator { +public: + JavaDocConverter(int flags = 0); + String *makeDocumentation(Node *node); + +protected: + /* + * Used to properly format JavaDoc-style command + */ + std::string formatCommand(std::string unformattedLine, int indent); + + /* + * Translate every entity in a tree. + */ + std::string translateSubtree(DoxygenEntity &doxygenEntity); + + /* + * Translate one entity with the appropriate handler, according + * to the tagHandlers + */ + void translateEntity(DoxygenEntity &tag, std::string &translatedComment); + + /* + * Fix all endlines location, etc + */ + int shiftEndlinesUpTree(DoxygenEntity &root, int level = 0); + + /* + * Convert params in link-objects and references + */ + std::string convertLink(std::string linkObject); + + /* + * Typedef for the function that handles one tag + * arg - some string argument to easily pass it through lookup table + */ + typedef void (JavaDocConverter::*tagHandler) (DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /** + * Copies verbatim args of the tag to output, used for commands like \f$, ... + */ + void handleTagVerbatim(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /** Creates anchor link. */ + void handleTagAnchor(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Wrap the command data with the html tag + * arg - html tag, with no braces + */ + void handleTagHtml(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* Handles HTML tags recognized by Doxygen, like <A ...>, <ul>, <table>, ... */ + void handleDoxyHtmlTag(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* Handles HTML entities recognized by Doxygen, like <, ©, ... */ + void handleHtmlEntity(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Just prints new line + */ + void handleNewLine(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Print the name of tag to the output, used for escape-commands + * arg - html-escaped variant, if not provided the command data is used + */ + void handleTagChar(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Do not translate and print as-is + * arg - the new tag name, if it needs to be renamed + */ + void handleTagSame(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Print only the content and strip original tag + */ + void handleParagraph(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Print only data part of code + */ + void handlePlainString(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Print extended Javadoc command, like {@code ...} or {@literal ...} + * arg - command name + */ + void handleTagExtended(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Print the if-elseif-else-endif section + */ + void handleTagIf(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Prints the specified message, than the contents of the tag + * arg - message + */ + void handleTagMessage(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Insert <img src=... /> tag if the 'format' field is specified as 'html' + */ + void handleTagImage(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Insert <p alt='title'>...</p> + */ + void handleTagPar(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Insert \@param command, if it is really a function param + */ + void handleTagParam(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Writes link for \ref tag. + */ + void handleTagRef(DoxygenEntity &tag, std::string &translatedComment, std::string &); + + /* + * Insert {@link...} command, and handle all the <link-object>s correctly + * (like converting types of params, etc) + */ + void handleTagLink(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + + /* + * Insert @see command, and handle all the <link-object>s correctly + * (like converting types of params, etc) + */ + void handleTagSee(DoxygenEntity &tag, std::string &translatedComment, std::string &arg); + +private: + Node *currentNode; + // this contains the handler pointer and one string argument + static std::map<std::string, std::pair<tagHandler, std::string> > tagHandlers; + void fillStaticTables(); + + bool paramExists(std::string param); + std::string indentAndInsertAsterisks(const std::string &doc); + + void addError(int warningType, const std::string &message); +}; + +#endif diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx new file mode 100644 index 000000000..0f8484d6b --- /dev/null +++ b/Source/Doxygen/pydoc.cxx @@ -0,0 +1,843 @@ +/* ----------------------------------------------------------------------------- + * This file is part of SWIG, which is licensed as a whole under version 3 + * (or any later version) of the GNU General Public License. Some additional + * terms also apply to certain portions of SWIG. The full details of the SWIG + * license and copyrights can be found in the LICENSE and COPYRIGHT files + * included with the SWIG source code as distributed by the SWIG developers + * and at http://www.swig.org/legal.html. + * + * pydoc.cxx + * + * Module to return documentation for nodes formatted for PyDoc + * ----------------------------------------------------------------------------- */ + +#include "pydoc.h" +#include "doxyparser.h" +#include <sstream> +#include <string> +#include <vector> +#include <iostream> + +#include "swigmod.h" + +// define static tables, they are filled in PyDocConverter's constructor +PyDocConverter::TagHandlersMap PyDocConverter::tagHandlers; +std::map<std::string, std::string> PyDocConverter::sectionTitles; + +using std::string; + +// Helper class increasing the provided indent string in its ctor and decreasing +// it in its dtor. +class IndentGuard { +public: + // One indent level. + static const char *Level() { + return " "; + } + // Default ctor doesn't do anything and prevents the dtor from doing anything// too and should only be used when the guard needs to be initialized// conditionally as Init() can then be called after checking some condition.// Otherwise, prefer to use the non default ctor below. + IndentGuard() { + m_initialized = false; + } + + // Ctor takes the output to determine the current indent and to remove the + // extra indent added to it in the dtor and the variable containing the indent + // to use, which must be used after every new line by the code actually + // updating the output. + IndentGuard(string &output, string &indent) { + Init(output, indent); + } + + // Really initializes the object created using the default ctor. + void Init(string &output, string &indent) { + m_output = &output; + m_indent = &indent; + + const size_t lastNonSpace = m_output->find_last_not_of(' '); + if (lastNonSpace == string::npos) { + m_firstLineIndent = m_output->length(); + } else if ((*m_output)[lastNonSpace] == '\n') { + m_firstLineIndent = m_output->length() - (lastNonSpace + 1); + } else { + m_firstLineIndent = 0; + } + + // Notice that the indent doesn't include the first line indent because it's + // implicit, i.e. it is present in the input and so is copied into the + // output anyhow. + *m_indent = Level(); + + m_initialized = true; + } + + // Get the indent for the first line of the paragraph, which is smaller than + // the indent for the subsequent lines. + string getFirstLineIndent() const { + return string(m_firstLineIndent, ' '); + } + + ~IndentGuard() { + if (!m_initialized) + return; + + m_indent->clear(); + + // Get rid of possible remaining extra indent, e.g. if there were any trailing + // new lines: we shouldn't add the extra indent level to whatever follows + // this paragraph. + static const size_t lenIndentLevel = strlen(Level()); + if (m_output->length() > lenIndentLevel) { + const size_t start = m_output->length() - lenIndentLevel; + if (m_output->compare(start, string::npos, Level()) == 0) + m_output->erase(start); + } + } + +private: + string *m_output; + string *m_indent; + unsigned m_firstLineIndent; + bool m_initialized; + + IndentGuard(const IndentGuard &); + IndentGuard &operator=(const IndentGuard &); +}; + +// Return the indent of the given multiline string, i.e. the maximal number of +// spaces present in the beginning of all its non-empty lines. +static size_t determineIndent(const string &s) { + size_t minIndent = static_cast<size_t>(-1); + + for (size_t lineStart = 0; lineStart < s.length();) { + const size_t lineEnd = s.find('\n', lineStart); + const size_t firstNonSpace = s.find_first_not_of(' ', lineStart); + + // If inequality doesn't hold, it means that this line contains only spaces + // (notice that this works whether lineEnd is valid or string::npos), in + // which case it doesn't matter when determining the indent. + if (firstNonSpace < lineEnd) { + // Here we can be sure firstNonSpace != string::npos. + const size_t lineIndent = firstNonSpace - lineStart; + if (lineIndent < minIndent) + minIndent = lineIndent; + } + + if (lineEnd == string::npos) + break; + + lineStart = lineEnd + 1; + } + + return minIndent; +} + +static void trimWhitespace(string &s) { + const size_t lastNonSpace = s.find_last_not_of(' '); + if (lastNonSpace == string::npos) + s.clear(); + else + s.erase(lastNonSpace + 1); +} + +/* static */ +PyDocConverter::TagHandlersMap::mapped_type PyDocConverter::make_handler(tagHandler handler) { + return make_pair(handler, std::string()); +} + +/* static */ +PyDocConverter::TagHandlersMap::mapped_type PyDocConverter::make_handler(tagHandler handler, const char *arg) { + return make_pair(handler, arg); +} + +void PyDocConverter::fillStaticTables() { + if (tagHandlers.size()) // fill only once + return; + + // table of section titles, they are printed only once + // for each group of specified doxygen commands + sectionTitles["author"] = "Author: "; + sectionTitles["authors"] = "Authors: "; + sectionTitles["copyright"] = "Copyright: "; + sectionTitles["deprecated"] = "Deprecated: "; + sectionTitles["example"] = "Example: "; + sectionTitles["note"] = "Notes: "; + sectionTitles["remark"] = "Remarks: "; + sectionTitles["remarks"] = "Remarks: "; + sectionTitles["warning"] = "Warning: "; +// sectionTitles["sa"] = "See also: "; +// sectionTitles["see"] = "See also: "; + sectionTitles["since"] = "Since: "; + sectionTitles["todo"] = "TODO: "; + sectionTitles["version"] = "Version: "; + + tagHandlers["a"] = make_handler(&PyDocConverter::handleTagWrap, "*"); + tagHandlers["b"] = make_handler(&PyDocConverter::handleTagWrap, "**"); + // \c command is translated as single quotes around next word + tagHandlers["c"] = make_handler(&PyDocConverter::handleTagWrap, "``"); + tagHandlers["cite"] = make_handler(&PyDocConverter::handleTagWrap, "'"); + tagHandlers["e"] = make_handler(&PyDocConverter::handleTagWrap, "*"); + // these commands insert just a single char, some of them need to be escaped + tagHandlers["$"] = make_handler(&PyDocConverter::handleTagChar); + tagHandlers["@"] = make_handler(&PyDocConverter::handleTagChar); + tagHandlers["\\"] = make_handler(&PyDocConverter::handleTagChar); + tagHandlers["<"] = make_handler(&PyDocConverter::handleTagChar); + tagHandlers[">"] = make_handler(&PyDocConverter::handleTagChar); + tagHandlers["&"] = make_handler(&PyDocConverter::handleTagChar); + tagHandlers["#"] = make_handler(&PyDocConverter::handleTagChar); + tagHandlers["%"] = make_handler(&PyDocConverter::handleTagChar); + tagHandlers["~"] = make_handler(&PyDocConverter::handleTagChar); + tagHandlers["\""] = make_handler(&PyDocConverter::handleTagChar); + tagHandlers["."] = make_handler(&PyDocConverter::handleTagChar); + tagHandlers["::"] = make_handler(&PyDocConverter::handleTagChar); + // these commands are stripped out, and only their content is printed + tagHandlers["attention"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["author"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["authors"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["brief"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["bug"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["code"] = make_handler(&PyDocConverter::handleCode); + tagHandlers["copyright"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["date"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["deprecated"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["details"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["em"] = make_handler(&PyDocConverter::handleParagraph, " "); + tagHandlers["example"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["exception"] = tagHandlers["throw"] = tagHandlers["throws"] = make_handler(&PyDocConverter::handleTagException); + tagHandlers["htmlonly"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["invariant"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["latexonly"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["link"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["manonly"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["note"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["p"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["partofdescription"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["rtfonly"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["remark"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["remarks"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["sa"] = make_handler(&PyDocConverter::handleTagMessage, "See also: "); + tagHandlers["see"] = make_handler(&PyDocConverter::handleTagMessage, "See also: "); + tagHandlers["since"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["short"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["todo"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["version"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["verbatim"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["warning"] = make_handler(&PyDocConverter::handleParagraph); + tagHandlers["xmlonly"] = make_handler(&PyDocConverter::handleParagraph); + // these commands have special handlers + tagHandlers["arg"] = make_handler(&PyDocConverter::handleTagMessage, "* "); + tagHandlers["cond"] = make_handler(&PyDocConverter::handleTagMessage, "Conditional comment: "); + tagHandlers["else"] = make_handler(&PyDocConverter::handleTagIf, "Else: "); + tagHandlers["elseif"] = make_handler(&PyDocConverter::handleTagIf, "Else if: "); + tagHandlers["endcond"] = make_handler(&PyDocConverter::handleTagMessage, "End of conditional comment."); + tagHandlers["if"] = make_handler(&PyDocConverter::handleTagIf, "If: "); + tagHandlers["ifnot"] = make_handler(&PyDocConverter::handleTagIf, "If not: "); + tagHandlers["image"] = make_handler(&PyDocConverter::handleTagImage); + tagHandlers["li"] = make_handler(&PyDocConverter::handleTagMessage, "* "); + tagHandlers["overload"] = make_handler(&PyDocConverter::handleTagMessage, + "This is an overloaded member function, provided for" + " convenience.\nIt differs from the above function only in what" " argument(s) it accepts."); + tagHandlers["par"] = make_handler(&PyDocConverter::handleTagPar); + tagHandlers["param"] = tagHandlers["tparam"] = make_handler(&PyDocConverter::handleTagParam); + tagHandlers["ref"] = make_handler(&PyDocConverter::handleTagRef); + tagHandlers["result"] = tagHandlers["return"] = tagHandlers["returns"] = make_handler(&PyDocConverter::handleTagReturn); + + // this command just prints it's contents + // (it is internal command of swig's parser, contains plain text) + tagHandlers["plainstd::string"] = make_handler(&PyDocConverter::handlePlainString); + tagHandlers["plainstd::endl"] = make_handler(&PyDocConverter::handleNewLine); + tagHandlers["n"] = make_handler(&PyDocConverter::handleNewLine); + + // \f commands output literal Latex formula, which is still better than nothing. + tagHandlers["f$"] = tagHandlers["f["] = tagHandlers["f{"] = make_handler(&PyDocConverter::handleMath); + + // HTML tags + tagHandlers["<a"] = make_handler(&PyDocConverter::handleDoxyHtmlTag_A); + tagHandlers["<b"] = make_handler(&PyDocConverter::handleDoxyHtmlTag2, "**"); + tagHandlers["<blockquote"] = make_handler(&PyDocConverter::handleDoxyHtmlTag_A, "Quote: "); + tagHandlers["<body"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<br"] = make_handler(&PyDocConverter::handleDoxyHtmlTag, "\n"); + + // there is no formatting for this tag as it was deprecated in HTML 4.01 and + // not used in HTML 5 + tagHandlers["<center"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<caption"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<code"] = make_handler(&PyDocConverter::handleDoxyHtmlTag2, "``"); + + tagHandlers["<dl"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<dd"] = make_handler(&PyDocConverter::handleDoxyHtmlTag, " "); + tagHandlers["<dt"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + + tagHandlers["<dfn"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<div"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<em"] = make_handler(&PyDocConverter::handleDoxyHtmlTag2, "**"); + tagHandlers["<form"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<hr"] = make_handler(&PyDocConverter::handleDoxyHtmlTag, "--------------------------------------------------------------------\n"); + tagHandlers["<h1"] = make_handler(&PyDocConverter::handleDoxyHtmlTag, "# "); + tagHandlers["<h2"] = make_handler(&PyDocConverter::handleDoxyHtmlTag, "## "); + tagHandlers["<h3"] = make_handler(&PyDocConverter::handleDoxyHtmlTag, "### "); + tagHandlers["<i"] = make_handler(&PyDocConverter::handleDoxyHtmlTag2, "*"); + tagHandlers["<input"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<img"] = make_handler(&PyDocConverter::handleDoxyHtmlTag, "Image:"); + tagHandlers["<li"] = make_handler(&PyDocConverter::handleDoxyHtmlTag, "* "); + tagHandlers["<meta"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<multicol"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<ol"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<p"] = make_handler(&PyDocConverter::handleDoxyHtmlTag, "\n"); + tagHandlers["<pre"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<small"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<span"] = make_handler(&PyDocConverter::handleDoxyHtmlTag2, "'"); + tagHandlers["<strong"] = make_handler(&PyDocConverter::handleDoxyHtmlTag2, "**"); + + // make a space between text and super/sub script. + tagHandlers["<sub"] = make_handler(&PyDocConverter::handleDoxyHtmlTag, " "); + tagHandlers["<sup"] = make_handler(&PyDocConverter::handleDoxyHtmlTag, " "); + + tagHandlers["<table"] = make_handler(&PyDocConverter::handleDoxyHtmlTagNoParam); + tagHandlers["<td"] = make_handler(&PyDocConverter::handleDoxyHtmlTag_td); + tagHandlers["<th"] = make_handler(&PyDocConverter::handleDoxyHtmlTag_th); + tagHandlers["<tr"] = make_handler(&PyDocConverter::handleDoxyHtmlTag_tr); + tagHandlers["<tt"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<kbd"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<ul"] = make_handler(&PyDocConverter::handleDoxyHtmlTag); + tagHandlers["<var"] = make_handler(&PyDocConverter::handleDoxyHtmlTag2, "*"); + + // HTML entities + tagHandlers["©"] = make_handler(&PyDocConverter::handleHtmlEntity, "(C)"); + tagHandlers["&trade"] = make_handler(&PyDocConverter::handleHtmlEntity, " TM"); + tagHandlers["®"] = make_handler(&PyDocConverter::handleHtmlEntity, "(R)"); + tagHandlers["<"] = make_handler(&PyDocConverter::handleHtmlEntity, "<"); + tagHandlers[">"] = make_handler(&PyDocConverter::handleHtmlEntity, ">"); + tagHandlers["&"] = make_handler(&PyDocConverter::handleHtmlEntity, "&"); + tagHandlers["&apos"] = make_handler(&PyDocConverter::handleHtmlEntity, "'"); + tagHandlers["""] = make_handler(&PyDocConverter::handleHtmlEntity, "\""); + tagHandlers["&lsquo"] = make_handler(&PyDocConverter::handleHtmlEntity, "`"); + tagHandlers["&rsquo"] = make_handler(&PyDocConverter::handleHtmlEntity, "'"); + tagHandlers["&ldquo"] = make_handler(&PyDocConverter::handleHtmlEntity, "\""); + tagHandlers["&rdquo"] = make_handler(&PyDocConverter::handleHtmlEntity, "\""); + tagHandlers["&ndash"] = make_handler(&PyDocConverter::handleHtmlEntity, "-"); + tagHandlers["&mdash"] = make_handler(&PyDocConverter::handleHtmlEntity, "--"); + tagHandlers[" "] = make_handler(&PyDocConverter::handleHtmlEntity, " "); + tagHandlers["×"] = make_handler(&PyDocConverter::handleHtmlEntity, "x"); + tagHandlers["&minus"] = make_handler(&PyDocConverter::handleHtmlEntity, "-"); + tagHandlers["&sdot"] = make_handler(&PyDocConverter::handleHtmlEntity, "."); + tagHandlers["&sim"] = make_handler(&PyDocConverter::handleHtmlEntity, "~"); + tagHandlers["&le"] = make_handler(&PyDocConverter::handleHtmlEntity, "<="); + tagHandlers["&ge"] = make_handler(&PyDocConverter::handleHtmlEntity, ">="); + tagHandlers["&larr"] = make_handler(&PyDocConverter::handleHtmlEntity, "<--"); + tagHandlers["&rarr"] = make_handler(&PyDocConverter::handleHtmlEntity, "-->"); +} + +PyDocConverter::PyDocConverter(int flags): +DoxygenTranslator(flags), m_tableLineLen(0), m_prevRowIsTH(false) { + fillStaticTables(); +} + +// Return the type as it should appear in the output documentation. +static std::string getPyDocType(Node *n, const_String_or_char_ptr lname = "") { + std::string type; + + String *s = Swig_typemap_lookup("doctype", n, lname, 0); + if (!s) + s = SwigType_str(Getattr(n, "type"), ""); + + if (Language::classLookup(s)) { + // In Python C++ namespaces are flattened, so remove all but last component + // of the name. + String *const last = Swig_scopename_last(s); + + // We are not actually sure whether it's a documented class or not, but + // there doesn't seem to be any harm in making it a reference if it isn't, + // while there is a lot of benefit in having a hyperlink if it is. + type = ":py:class:`"; + type += Char(last); + type += "`"; + + Delete(last); + } else { + type = Char(s); + } + + Delete(s); + + return type; +} + +std::string PyDocConverter::getParamType(std::string param) { + std::string type; + + ParmList *plist = CopyParmList(Getattr(currentNode, "parms")); + for (Parm *p = plist; p; p = nextSibling(p)) { + String *pname = Getattr(p, "name"); + if (Char(pname) != param) + continue; + + type = getPyDocType(p, pname); + break; + } + Delete(plist); + return type; +} + +std::string PyDocConverter::translateSubtree(DoxygenEntity &doxygenEntity) { + std::string translatedComment; + + if (doxygenEntity.isLeaf) + return translatedComment; + + std::string currentSection; + std::list<DoxygenEntity>::iterator p = doxygenEntity.entityList.begin(); + while (p != doxygenEntity.entityList.end()) { + std::map<std::string, std::string>::iterator it; + it = sectionTitles.find(p->typeOfEntity); + if (it != sectionTitles.end()) { + if (it->second != currentSection) { + currentSection = it->second; + translatedComment += currentSection; + } + } + translateEntity(*p, translatedComment); + translateSubtree(*p); + p++; + } + + return translatedComment; +} + +void PyDocConverter::translateEntity(DoxygenEntity &doxyEntity, std::string &translatedComment) { + // check if we have needed handler and call it + std::map<std::string, std::pair<tagHandler, std::string> >::iterator it; + it = tagHandlers.find(doxyEntity.typeOfEntity); + if (it != tagHandlers.end()) + (this->*(it->second.first)) (doxyEntity, translatedComment, it->second.second); +} + +void PyDocConverter::handleParagraph(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + translatedComment += translateSubtree(tag); +} + +void PyDocConverter::handleMath(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) { + IndentGuard indent; + + // Only \f$ is translated to inline formulae, \f[ and \f{ are for the block ones. + const bool inlineFormula = tag.typeOfEntity == "f$"; + + string formulaNL; + + if (inlineFormula) { + translatedComment += ":math:`"; + } else { + indent.Init(translatedComment, m_indent); + + trimWhitespace(translatedComment); + translatedComment += '\n'; + + const string formulaIndent = indent.getFirstLineIndent(); + translatedComment += formulaIndent; + translatedComment += ".. math::\n"; + + formulaNL = '\n'; + formulaNL += formulaIndent; + formulaNL += m_indent; + translatedComment += formulaNL; + } + + std::string formula; + handleTagVerbatim(tag, formula, arg); + + // It is important to ensure that we have no spaces around the inline math + // contents, so strip them. + const size_t start = formula.find_first_not_of(" \t\n"); + const size_t end = formula.find_last_not_of(" \t\n"); + if (start != std::string::npos) { + for (size_t n = start; n <= end; n++) { + if (formula[n] == '\n') { + // New lines must be suppressed in inline maths and indented in the block ones. + if (!inlineFormula) + translatedComment += formulaNL; + } else { + // Just copy everything else. + translatedComment += formula[n]; + } + } + } + + if (inlineFormula) { + translatedComment += "`"; + } else { + translatedComment += '\n'; + } +} + +void PyDocConverter::handleCode(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) { + IndentGuard indent(translatedComment, m_indent); + + trimWhitespace(translatedComment); + translatedComment += '\n'; + + // Use the current indent for the code-block line itself. + string codeIndent = indent.getFirstLineIndent(); + translatedComment += codeIndent; + + // Go out on a limb and assume that examples in the C or C++ sources use C++. + // In the worst case, we'll highlight C code using C++ syntax which is not a + // big deal (TODO: handle Doxygen code command language argument). + translatedComment += ".. code-block:: c++\n\n"; + + // For now on, use extra indent level for all the subsequent lines. + codeIndent += m_indent; + + std::string code; + handleTagVerbatim(tag, code, arg); + + translatedComment += codeIndent; + for (size_t n = 0; n < code.length(); n++) { + if (code[n] == '\n') { + // Don't leave trailing white space, this results in PEP8 validation + // errors in Python code (which are performed by our own unit tests). + trimWhitespace(translatedComment); + translatedComment += '\n'; + + // Ensure that we indent all the lines by the code indent. + translatedComment += codeIndent; + } else { + // Just copy everything else. + translatedComment += code[n]; + } + } + + trimWhitespace(translatedComment); + if (*translatedComment.rbegin() != '\n') + translatedComment += '\n'; +} + +void PyDocConverter::handlePlainString(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + translatedComment += tag.data; +} + +void PyDocConverter::handleTagVerbatim(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) { + translatedComment += arg + " "; + for (DoxygenEntityListCIt it = tag.entityList.begin(); it != tag.entityList.end(); it++) { + translatedComment += it->data; + } +} + +void PyDocConverter::handleTagMessage(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) { + translatedComment += arg; + handleParagraph(tag, translatedComment); +} + +void PyDocConverter::handleTagChar(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + translatedComment += tag.typeOfEntity; +} + +void PyDocConverter::handleTagIf(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) { + translatedComment += arg; + if (tag.entityList.size()) { + translatedComment += tag.entityList.begin()->data; + tag.entityList.pop_front(); + translatedComment += " {" + translateSubtree(tag) + "}"; + } +} + +void PyDocConverter::handleTagPar(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + translatedComment += "Title: "; + if (tag.entityList.size()) + translatedComment += tag.entityList.begin()->data; + tag.entityList.pop_front(); + handleParagraph(tag, translatedComment); +} + +void PyDocConverter::handleTagImage(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + if (tag.entityList.size() < 2) + return; + tag.entityList.pop_front(); + translatedComment += "Image: "; + translatedComment += tag.entityList.begin()->data; + tag.entityList.pop_front(); + if (tag.entityList.size()) + translatedComment += "(" + tag.entityList.begin()->data + ")"; +} + +void PyDocConverter::handleTagParam(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + if (tag.entityList.size() < 2) + return; + + IndentGuard indent(translatedComment, m_indent); + + DoxygenEntity paramNameEntity = *tag.entityList.begin(); + tag.entityList.pop_front(); + + const std::string ¶mName = paramNameEntity.data; + + const std::string paramType = getParamType(paramName); + if (!paramType.empty()) { + translatedComment += ":type " + paramName + ": " + paramType + "\n"; + translatedComment += indent.getFirstLineIndent(); + } + + translatedComment += ":param " + paramName + ":"; + + handleParagraph(tag, translatedComment); +} + + +void PyDocConverter::handleTagReturn(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + IndentGuard indent(translatedComment, m_indent); + + const std::string pytype = getPyDocType(currentNode); + if (!pytype.empty()) { + translatedComment += ":rtype: "; + translatedComment += pytype; + translatedComment += "\n"; + translatedComment += indent.getFirstLineIndent(); + } + + translatedComment += ":return: "; + handleParagraph(tag, translatedComment); +} + + +void PyDocConverter::handleTagException(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + IndentGuard indent(translatedComment, m_indent); + + translatedComment += ":raises: "; + handleParagraph(tag, translatedComment); +} + + +void PyDocConverter::handleTagRef(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + if (!tag.entityList.size()) + return; + + string anchor = tag.entityList.begin()->data; + tag.entityList.pop_front(); + string anchorText = anchor; + if (!tag.entityList.empty()) { + anchorText = tag.entityList.begin()->data; + } + translatedComment += "'" + anchorText + "'"; +} + + +void PyDocConverter::handleTagWrap(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) { + if (tag.entityList.size()) { // do not include empty tags + std::string tagData = translateSubtree(tag); + // wrap the thing, ignoring whitespace + size_t wsPos = tagData.find_last_not_of("\n\t "); + if (wsPos != std::string::npos && wsPos != tagData.size() - 1) + translatedComment += arg + tagData.substr(0, wsPos + 1) + arg + tagData.substr(wsPos + 1); + else + translatedComment += arg + tagData + arg; + } +} + +void PyDocConverter::handleDoxyHtmlTag(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) { + std::string htmlTagArgs = tag.data; + if (htmlTagArgs == "/") { + // end html tag, for example "</ul> + // translatedComment += "</" + arg.substr(1) + ">"; + } else { + translatedComment += arg + htmlTagArgs; + } +} + +void PyDocConverter::handleDoxyHtmlTagNoParam(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) { + std::string htmlTagArgs = tag.data; + if (htmlTagArgs == "/") { + // end html tag, for example "</ul> + } else { + translatedComment += arg; + } +} + +void PyDocConverter::handleDoxyHtmlTag_A(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) { + std::string htmlTagArgs = tag.data; + if (htmlTagArgs == "/") { + // end html tag, "</a> + translatedComment += " (" + m_url + ')'; + m_url.clear(); + } else { + m_url.clear(); + size_t pos = htmlTagArgs.find('='); + if (pos != string::npos) { + m_url = htmlTagArgs.substr(pos + 1); + } + translatedComment += arg; + } +} + +void PyDocConverter::handleDoxyHtmlTag2(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg) { + std::string htmlTagArgs = tag.data; + if (htmlTagArgs == "/") { + // end html tag, for example "</em> + translatedComment += arg; + } else { + translatedComment += arg; + } +} + +void PyDocConverter::handleDoxyHtmlTag_tr(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + std::string htmlTagArgs = tag.data; + size_t nlPos = translatedComment.rfind('\n'); + if (htmlTagArgs == "/") { + // end tag, </tr> appends vertical table line '|' + translatedComment += '|'; + if (nlPos != string::npos) { + size_t startOfTableLinePos = translatedComment.find_first_not_of(" \t", nlPos + 1); + if (startOfTableLinePos != string::npos) { + m_tableLineLen = translatedComment.size() - startOfTableLinePos; + } + } + } else { + if (m_prevRowIsTH) { + // if previous row contained <th> tag, add horizontal separator + // but first get leading spaces, because they'll be needed for the next row + size_t numLeadingSpaces = translatedComment.size() - nlPos - 1; + + translatedComment += string(m_tableLineLen, '-') + '\n'; + + if (nlPos != string::npos) { + translatedComment += string(numLeadingSpaces, ' '); + } + m_prevRowIsTH = false; + } + } +} + +void PyDocConverter::handleDoxyHtmlTag_th(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + std::string htmlTagArgs = tag.data; + if (htmlTagArgs == "/") { + // end tag, </th> is ignored + } else { + translatedComment += '|'; + m_prevRowIsTH = true; + } +} + +void PyDocConverter::handleDoxyHtmlTag_td(DoxygenEntity &tag, std::string &translatedComment, const std::string &) { + std::string htmlTagArgs = tag.data; + if (htmlTagArgs == "/") { + // end tag, </td> is ignored + } else { + translatedComment += '|'; + } +} + +void PyDocConverter::handleHtmlEntity(DoxygenEntity &, std::string &translatedComment, const std::string &arg) { + // html entities + translatedComment += arg; +} + +void PyDocConverter::handleNewLine(DoxygenEntity &, std::string &translatedComment, const std::string &) { + trimWhitespace(translatedComment); + + translatedComment += "\n"; + if (!m_indent.empty()) + translatedComment += m_indent; +} + +String *PyDocConverter::makeDocumentation(Node *n) { + String *documentation; + std::string pyDocString; + + // store the node, we may need it later + currentNode = n; + + // for overloaded functions we must concat documentation for underlying overloads + if (Getattr(n, "sym:overloaded")) { + // rewind to the first overload + while (Getattr(n, "sym:previousSibling")) + n = Getattr(n, "sym:previousSibling"); + + std::vector<std::string> allDocumentation; + + // minimal indent of any documentation comments, not initialized yet + size_t minIndent = static_cast<size_t>(-1); + + // for each real method (not a generated overload) append the documentation + string oneDoc; + while (n) { + documentation = getDoxygenComment(n); + if (!Swig_is_generated_overload(n) && documentation) { + currentNode = n; + if (GetFlag(n, "feature:doxygen:notranslate")) { + String *comment = NewString(""); + Append(comment, documentation); + Replaceall(comment, "\n *", "\n"); + oneDoc = Char(comment); + Delete(comment); + } else { + std::list<DoxygenEntity> entityList = parser.createTree(n, documentation); + DoxygenEntity root("root", entityList); + + oneDoc = translateSubtree(root); + } + + // find the minimal indent of this documentation comment, we need to + // ensure that the entire comment is indented by it to avoid the leading + // parts of the other lines being simply discarded later + const size_t oneIndent = determineIndent(oneDoc); + if (oneIndent < minIndent) + minIndent = oneIndent; + + allDocumentation.push_back(oneDoc); + } + n = Getattr(n, "sym:nextSibling"); + } + + // construct final documentation string + if (allDocumentation.size() > 1) { + string indentStr; + if (minIndent != static_cast<size_t>(-1)) + indentStr.assign(minIndent, ' '); + + std::ostringstream concatDocString; + for (size_t realOverloadCount = 0; realOverloadCount < allDocumentation.size(); realOverloadCount++) { + if (realOverloadCount != 0) { + // separate it from the preceding one. + concatDocString << "\n" << indentStr << "|\n\n"; + } + + oneDoc = allDocumentation[realOverloadCount]; + trimWhitespace(oneDoc); + concatDocString << indentStr << "*Overload " << (realOverloadCount + 1) << ":*\n" << oneDoc; + } + pyDocString = concatDocString.str(); + } else if (allDocumentation.size() == 1) { + pyDocString = *(allDocumentation.begin()); + } + } + // for other nodes just process as normal + else { + documentation = getDoxygenComment(n); + if (documentation != NULL) { + if (GetFlag(n, "feature:doxygen:notranslate")) { + String *comment = NewString(""); + Append(comment, documentation); + Replaceall(comment, "\n *", "\n"); + pyDocString = Char(comment); + Delete(comment); + } else { + std::list<DoxygenEntity> entityList = parser.createTree(n, documentation); + DoxygenEntity root("root", entityList); + pyDocString = translateSubtree(root); + } + } + } + + // if we got something log the result + if (!pyDocString.empty()) { + + // remove the last '\n' since additional one is added during writing to file + if (pyDocString[pyDocString.size() - 1] == '\n') { + pyDocString.erase(pyDocString.size() - 1); + } + + if (m_flags & debug_translator) { + std::cout << "\n---RESULT IN PYDOC---" << std::endl; + std::cout << pyDocString; + std::cout << std::endl; + } + } + + return NewString(pyDocString.c_str()); +} diff --git a/Source/Doxygen/pydoc.h b/Source/Doxygen/pydoc.h new file mode 100644 index 000000000..8f432fd18 --- /dev/null +++ b/Source/Doxygen/pydoc.h @@ -0,0 +1,198 @@ +/* ----------------------------------------------------------------------------- + * This file is part of SWIG, which is licensed as a whole under version 3 + * (or any later version) of the GNU General Public License. Some additional + * terms also apply to certain portions of SWIG. The full details of the SWIG + * license and copyrights can be found in the LICENSE and COPYRIGHT files + * included with the SWIG source code as distributed by the SWIG developers + * and at http://www.swig.org/legal.html. + * + * pydoc.h + * + * Module to return documentation for nodes formatted for PyDoc + * ----------------------------------------------------------------------------- */ + +#ifndef PYDOCCONVERTER_H_ +#define PYDOCCONVERTER_H_ + +#include <list> +#include <string> +#include "swig.h" +#include "doxyentity.h" +#include "doxytranslator.h" + +#define DOC_STRING_LENGTH 64 // characters per line allowed +#define DOC_PARAM_STRING_LENGTH 30 // characters reserved for param name / type + +class PyDocConverter : public DoxygenTranslator { +public: + PyDocConverter(int flags = 0); + String *makeDocumentation(Node *node); + +protected: + + size_t m_tableLineLen; + bool m_prevRowIsTH; + std::string m_url; + + /* + * Translate every entity in a tree, also manages sections + * display. Prints title for every group of tags that have + * a section title associated with them + */ + std::string translateSubtree(DoxygenEntity &doxygenEntity); + + /* + * Translate one entity with the appropriate handler, according + * to the tagHandlers + */ + void translateEntity(DoxygenEntity &doxyEntity, std::string &translatedComment); + + /* + * Typedef for the function that handles one tag + * arg - some string argument to easily pass it through lookup table + */ + typedef void (PyDocConverter::*tagHandler) (DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Wrap the command data with the some string + * arg - string to wrap with, like '_' or '*' + */ + void handleTagWrap(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Just prints new line + */ + void handleNewLine(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Print the name of tag to the output, used for escape-commands + */ + void handleTagChar(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Format the contents of the \exception tag or its synonyms. + */ + void handleTagException(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Print only the content and strip original tag + */ + void handleParagraph(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg = std::string()); + + /* + * Handle one of the Doxygen formula-related tags. + */ + void handleMath(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Handle a code snippet. + */ + void handleCode(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Print only data part of code + */ + void handlePlainString(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /** + * Copies verbatim args of the tag to output, used for commands like \f$, ... + */ + void handleTagVerbatim(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Print the if-elseif-else-endif section + */ + void handleTagIf(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Prints the specified message, than the contents of the tag + * arg - message + */ + void handleTagMessage(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Insert 'Title: ...' + */ + void handleTagPar(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Insert 'Image: ...' + */ + void handleTagImage(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Format nice param description with type information + */ + void handleTagParam(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Format the contents of the \return tag or its synonyms. + */ + void handleTagReturn(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Writes text for \ref tag. + */ + void handleTagRef(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* Handles HTML tags recognized by Doxygen, like <A ...>, <ul>, <table>, ... */ + + void handleDoxyHtmlTag(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /** Does not output params of HTML tag, for example in <table border='1'> + * 'border=1' is not written to output. + */ + void handleDoxyHtmlTagNoParam(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /** Translates tag <a href = "url">text</a> to: text ("url"). */ + void handleDoxyHtmlTag_A(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* + * Handles HTML tags, which are translated to markdown-like syntax, for example + * <i>text</i> --> _text_. Appends arg for start HTML tag and end HTML tag. + */ + void handleDoxyHtmlTag2(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* Handles HTML table, tag <tr> */ + void handleDoxyHtmlTag_tr(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* Handles HTML table, tag <th> */ + void handleDoxyHtmlTag_th(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* Handles HTML table, tag <td> */ + void handleDoxyHtmlTag_td(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg); + + /* Handles HTML entities recognized by Doxygen, like <, ©, ... */ + void handleHtmlEntity(DoxygenEntity &, std::string &translatedComment, const std::string &arg); + + + /* + * Simple helper function that calculates correct parameter type + * of the node stored in 'currentNode' + * If param with specified name is not found, empty string is returned + */ + std::string getParamType(std::string name); + +private: + // temporary thing, should be refactored somehow + Node *currentNode; + + // Extra indent for the current paragraph, must be output after each new line. + std::string m_indent; + + + // this contains the handler pointer and one string argument + typedef std::map<std::string, std::pair<tagHandler, std::string> >TagHandlersMap; + static TagHandlersMap tagHandlers; + + // this contains the sections tittles, like 'Arguments:' or 'Notes:', that are printed only once + static std::map<std::string, std::string> sectionTitles; + + // Helper functions for fillStaticTables(): make a new tag handler object. + TagHandlersMap::mapped_type make_handler(tagHandler handler); + TagHandlersMap::mapped_type make_handler(tagHandler handler, const char *arg); + + void fillStaticTables(); +}; + +#endif diff --git a/Source/Include/swigwarn.h b/Source/Include/swigwarn.h index dd32aef3a..9f863f194 100644 --- a/Source/Include/swigwarn.h +++ b/Source/Include/swigwarn.h @@ -209,6 +209,15 @@ #define WARN_LANG_EXTEND_CONSTRUCTOR 522 #define WARN_LANG_EXTEND_DESTRUCTOR 523 +/* -- Doxygen comments -- */ + +#define WARN_DOXYGEN_UNKNOWN_COMMAND 560 +#define WARN_DOXYGEN_UNEXPECTED_END_OF_COMMENT 561 +#define WARN_DOXYGEN_COMMAND_EXPECTED 562 +#define WARN_DOXYGEN_HTML_ERROR 563 +#define WARN_DOXYGEN_COMMAND_ERROR 564 +#define WARN_DOXYGEN_UNKNOWN_CHARACTER 565 + /* -- Reserved (600-799) -- */ /* -- Language module specific warnings (700 - 899) -- */ diff --git a/Source/Makefile.am b/Source/Makefile.am index b04e3542f..74aff08c9 100644 --- a/Source/Makefile.am +++ b/Source/Makefile.am @@ -13,6 +13,7 @@ AM_CPPFLAGS = -I$(BUILD_SOURCE_DIR)/Include \ -I$(SOURCE_DIR)/Include \ -I$(SOURCE_DIR)/DOH \ -I$(SOURCE_DIR)/CParse \ + -I$(SOURCE_DIR)/Doxygen \ -I$(SOURCE_DIR)/Preprocessor \ -I$(SOURCE_DIR)/Swig \ -I$(SOURCE_DIR)/Modules @@ -34,6 +35,16 @@ eswig_SOURCES = CParse/cscanner.c \ DOH/memory.c \ DOH/string.c \ DOH/void.c \ + Doxygen/doxyentity.cxx \ + Doxygen/doxyentity.h \ + Doxygen/doxyparser.cxx \ + Doxygen/doxyparser.h \ + Doxygen/doxytranslator.cxx \ + Doxygen/doxytranslator.h \ + Doxygen/javadoc.cxx \ + Doxygen/javadoc.h \ + Doxygen/pydoc.cxx \ + Doxygen/pydoc.h \ Modules/allegrocl.cxx \ Modules/allocate.cxx \ Modules/browser.cxx \ @@ -90,8 +101,8 @@ eswig_SOURCES = CParse/cscanner.c \ Swig/stype.c \ Swig/symbol.c \ Swig/tree.c \ - Swig/typeobj.c \ Swig/typemap.c \ + Swig/typeobj.c \ Swig/typesys.c \ Swig/wrapfunc.c diff --git a/Source/Modules/java.cxx b/Source/Modules/java.cxx index 06daccf4a..69abf6a80 100644 --- a/Source/Modules/java.cxx +++ b/Source/Modules/java.cxx @@ -15,6 +15,7 @@ #include <limits.h> // for INT_MAX #include "cparse.h" #include <ctype.h> +#include "javadoc.h" /* Hash type used for upcalls from C/C++ */ typedef DOH UpcallData; @@ -46,7 +47,9 @@ class JAVA:public Language { bool global_variable_flag; // Flag for when wrapping a global variable bool old_variable_names; // Flag for old style variable names in the intermediary class bool member_func_flag; // flag set when wrapping a member function - + bool doxygen; //flag for converting found doxygen to javadoc + bool comment_creation_chatter; //flag for getting information about where comments were created in java.cxx + String *imclass_name; // intermediary class name String *module_class_name; // module class name String *constants_interface_name; // constants interface name @@ -120,6 +123,8 @@ public: global_variable_flag(false), old_variable_names(false), member_func_flag(false), + doxygen(false), + comment_creation_chatter(false), imclass_name(NULL), module_class_name(NULL), constants_interface_name(NULL), @@ -164,6 +169,10 @@ public: director_multiple_inheritance = 0; director_language = 1; } + + ~JAVA() { + delete doxygenTranslator; + } /* ----------------------------------------------------------------------------- * constructIntermediateClassName() @@ -256,6 +265,8 @@ public: SWIG_library_directory("java"); + int doxygen_translator_flags = 0; + // Look for certain command line options for (int i = 1; i < argc; i++) { if (argv[i]) { @@ -277,6 +288,16 @@ public: Printf(stderr, "Deprecated command line option: %s. Proxy classes are now generated by default.\n", argv[i]); Swig_mark_arg(i); proxy_flag = true; + } else if ((strcmp(argv[i], "-doxygen") == 0)) { + Swig_mark_arg(i); + doxygen = true; + scan_doxygen_comments = true; + } else if ((strcmp(argv[i], "-debug-doxygen-translator") == 0)) { + Swig_mark_arg(i); + doxygen_translator_flags |= DoxygenTranslator::debug_translator; + } else if ((strcmp(argv[i], "-debug-doxygen-parser") == 0)) { + Swig_mark_arg(i); + doxygen_translator_flags |= DoxygenTranslator::debug_parser; } else if ((strcmp(argv[i], "-noproxy") == 0)) { Swig_mark_arg(i); proxy_flag = false; @@ -300,6 +321,9 @@ public: } } } + + if (doxygen) + doxygenTranslator = new JavaDocConverter(doxygen_translator_flags); // Add a symbol to the parser for conditional compilation Preprocessor_define("SWIGJAVA 1", 0); @@ -567,6 +591,13 @@ public: if (module_imports) Printf(f_module, "%s\n", module_imports); + if (doxygen && doxygenTranslator->hasDocumentation(n)) { + String *doxygen_comments = doxygenTranslator->getDocumentation(n); + if (comment_creation_chatter) + Printf(f_module, "/* This was generated from top() */"); + Printv(f_module, Char(doxygen_comments), NIL); + Delete(doxygen_comments); + } if (Len(module_class_modifiers) > 0) Printf(f_module, "%s ", module_class_modifiers); Printf(f_module, "%s ", module_class_name); @@ -1243,6 +1274,15 @@ public: EnumFeature enum_feature = decodeEnumFeature(n); String *typemap_lookup_type = Getattr(n, "name"); + if (doxygen && doxygenTranslator->hasDocumentation(n)) { + String *doxygen_comments = doxygenTranslator->getDocumentation(n); + if (comment_creation_chatter) { + Printf(enum_code, "/* This was generated from enumDeclaration() */"); + } + Printv(enum_code, Char(doxygen_comments), NIL); + Delete(doxygen_comments); + } + if ((enum_feature != SimpleEnum) && symname && typemap_lookup_type) { // Wrap (non-anonymous) C/C++ enum within a typesafe, typeunsafe or proper Java enum @@ -1265,8 +1305,16 @@ public: Replaceall(enum_code, "$static ", ""); Delete(scope); } else { - // Wrap C++ enum with integers - just indicate start of enum with a comment, no comment for anonymous enums of any sort - if (symname && !Getattr(n, "unnamedinstance")) + // Translate and write javadoc comment for the enum itself if flagged + if (doxygen && doxygenTranslator->hasDocumentation(n)) { + String *doxygen_comments = doxygenTranslator->getDocumentation(n); + if (comment_creation_chatter) + Printf(constants_code, "/* This was generated from enumDeclaration() */"); + Printf(constants_code, "/* Comment for enum %s */\n", Getattr(n, "unnamedinstance") ? "" : symname); + Printf(constants_code, Char(doxygen_comments)); + Printf(constants_code, "\n"); + Delete(doxygen_comments); + } else if (symname && !Getattr(n, "unnamedinstance")) Printf(constants_code, " // %s \n", symname); } @@ -1418,12 +1466,24 @@ public: } if (!addSymbol(symname, n, scope)) return SWIG_ERROR; + + if ((enum_feature == ProperEnum) && parent_name && !unnamedinstance) { + if (!GetFlag(n, "firstenumitem")) + Printf(enum_code, ",\n"); + } + + // Translate and write javadoc comment if flagged + if (doxygen && doxygenTranslator->hasDocumentation(n)) { + String *doxygen_comments = doxygenTranslator->getDocumentation(n); + if (comment_creation_chatter) + Printf(enum_code, "/* This was generated from enumvalueDeclaration() */"); + Printv(enum_code, Char(doxygen_comments), NIL); + Delete(doxygen_comments); + } if ((enum_feature == ProperEnum) && parent_name && !unnamedinstance) { // Wrap (non-anonymous) C/C++ enum with a proper Java enum // Emit the enum item. - if (!GetFlag(n, "firstenumitem")) - Printf(enum_code, ",\n"); Printf(enum_code, " %s", symname); if (Getattr(n, "enumvalue")) { String *value = enumValue(n); @@ -1497,6 +1557,15 @@ public: String *constants_code = NewString(""); Swig_save("constantWrapper", n, "value", NIL); + // Translate and write javadoc comment if flagged + if (doxygen && doxygenTranslator->hasDocumentation(n)) { + String *doxygen_comments = doxygenTranslator->getDocumentation(n); + if (comment_creation_chatter) + Printf(constants_code, "/* This was generated from constantWrapper() */"); + Printv(constants_code, Char(doxygen_comments), NIL); + Delete(doxygen_comments); + } + bool is_enum_item = (Cmp(nodeType(n), "enumitem") == 0); const String *itemname = (proxy_flag && wrapping_member_flag) ? variable_name : symname; @@ -1936,6 +2005,16 @@ public: // Pure Java interfaces const String *pure_interfaces = typemapLookup(n, "javainterfaces", typemap_lookup_type, WARN_NONE); + + // Translate and write javadoc comment if flagged + if (doxygen && doxygenTranslator->hasDocumentation(n)) { + String *doxygen_comments = doxygenTranslator->getDocumentation(n); + if (comment_creation_chatter) + Printf(proxy_class_def, "/* This was generated from emitProxyClassDefAndCPPCasts() */"); + Printv(proxy_class_def, Char(doxygen_comments), NIL); + Delete(doxygen_comments); + } + if (*Char(interface_list) && *Char(pure_interfaces)) Append(interface_list, ", "); Append(interface_list, pure_interfaces); @@ -2424,6 +2503,15 @@ public: setter_flag = (Cmp(Getattr(n, "sym:name"), Swig_name_set(getNSpace(), Swig_name_member(0, getClassPrefix(), variable_name))) == 0); } + // Translate and write javadoc comment if flagged + if (doxygen && doxygenTranslator->hasDocumentation(n)) { + String *doxygen_comments = doxygenTranslator->getDocumentation(n); + if (comment_creation_chatter) + Printf(function_code, "/* This was generated from proxyclassfunctionhandler() */"); + Printv(function_code, Char(doxygen_comments), NIL); + Delete(doxygen_comments); + } + /* Start generating the proxy function */ const String *methodmods = Getattr(n, "feature:java:methodmodifiers"); methodmods = methodmods ? methodmods : (is_public(n) ? public_string : protected_string); @@ -2614,7 +2702,7 @@ public: Printf(interface_class_code, ";\n"); } generateThrowsClause(n, function_code); - Printf(function_code, " %s\n\n", tm ? (const String *) tm : empty_string); + Printf(function_code, " %s\n\n", tm ? tm : empty_string); Printv(proxy_class_code, function_code, NIL); Delete(pre_code); @@ -2659,6 +2747,15 @@ public: tm = Getattr(n, "tmap:jtype"); // typemaps were attached earlier to the node Printf(im_return_type, "%s", tm); + // Translate and write javadoc comment if flagged + if (doxygen && doxygenTranslator->hasDocumentation(n)) { + String *doxygen_comments = doxygenTranslator->getDocumentation(n); + if (comment_creation_chatter) + Printf(function_code, "/* This was generated from constructionhandler() */"); + Printv(function_code, Char(doxygen_comments), NIL); + Delete(doxygen_comments); + } + Printf(function_code, " %s %s(", methodmods, proxy_class_name); Printf(helper_code, " static private %s SwigConstruct%s(", im_return_type, proxy_class_name); @@ -2924,6 +3021,15 @@ public: String *pre_code = NewString(""); String *post_code = NewString(""); + // Translate and write javadoc comment if flagged + if (doxygen && doxygenTranslator->hasDocumentation(n)) { + String *doxygen_comments = doxygenTranslator->getDocumentation(n); + if (comment_creation_chatter) + Printf(function_code, "/* This was generated from moduleClassFunctionHandler() */"); + Printv(function_code, doxygen_comments, NIL); + Delete(doxygen_comments); + } + if (l) { if (SwigType_type(Getattr(l, "type")) == T_VOID) { l = nextSibling(l); @@ -3076,7 +3182,7 @@ public: } generateThrowsClause(n, function_code); - Printf(function_code, " %s\n\n", tm ? (const String *) tm : empty_string); + Printf(function_code, " %s\n\n", tm ? tm : empty_string); Printv(module_class_code, function_code, NIL); Delete(pre_code); @@ -4873,6 +4979,9 @@ extern "C" Language *swig_java(void) { const char *JAVA::usage = "\ Java Options (available with -java)\n\ + -doxygen - Convert C++ doxygen comments to JavaDoc comments in proxy classes\n\ + -debug-doxygen-parser - Display doxygen parser module debugging information\n\ + -debug-doxygen-translator - Display doxygen translator module debugging information\n\ -nopgcpp - Suppress premature garbage collection prevention parameter\n\ -noproxy - Generate the low-level functional interface instead\n\ of proxy classes\n\ diff --git a/Source/Modules/lang.cxx b/Source/Modules/lang.cxx index 37ce54a75..96588dcc3 100644 --- a/Source/Modules/lang.cxx +++ b/Source/Modules/lang.cxx @@ -307,15 +307,12 @@ int Dispatcher::namespaceDeclaration(Node *n) { return defaultHandler(n); } - /* Allocators */ Language::Language(): none_comparison(NewString("$arg != 0")), director_ctor_code(NewString("")), director_prot_ctor_code(0), symtabs(NewHash()), -classtypes(NewHash()), -enumtypes(NewHash()), overloading(0), multiinput(0), cplus_runtime(0), @@ -336,12 +333,12 @@ directors(0) { director_language = 0; assert(!this_); this_ = this; + + doxygenTranslator = NULL; } Language::~Language() { Delete(symtabs); - Delete(classtypes); - Delete(enumtypes); Delete(director_ctor_code); Delete(none_comparison); this_ = 0; @@ -3264,11 +3261,13 @@ Node *Language::symbolLookup(const String *s, const_String_or_char_ptr scope) { * Tries to locate a class from a type definition * ----------------------------------------------------------------------------- */ -Node *Language::classLookup(const SwigType *s) const { +Node *Language::classLookup(const SwigType *s) { + static Hash *classtypes = 0; + Node *n = 0; /* Look in hash of cached values */ - n = Getattr(classtypes, s); + n = classtypes ? Getattr(classtypes, s) : 0; if (!n) { Symtab *stab = 0; SwigType *ty1 = SwigType_typedef_resolve_all(s); @@ -3331,6 +3330,8 @@ Node *Language::classLookup(const SwigType *s) const { } if (acceptable_prefix) { SwigType *cs = Copy(s); + if (!classtypes) + classtypes = NewHash(); Setattr(classtypes, cs, n); Delete(cs); } else { @@ -3357,10 +3358,12 @@ Node *Language::classLookup(const SwigType *s) const { * ----------------------------------------------------------------------------- */ Node *Language::enumLookup(SwigType *s) { + static Hash *enumtypes = 0; + Node *n = 0; /* Look in hash of cached values */ - n = Getattr(enumtypes, s); + n = enumtypes ? Getattr(enumtypes, s) : 0; if (!n) { Symtab *stab = 0; SwigType *lt = SwigType_ltype(s); @@ -3401,6 +3404,8 @@ Node *Language::enumLookup(SwigType *s) { if (n) { /* Found a match. Look at the prefix. We only allow simple types. */ if (Len(prefix) == 0) { /* Simple type */ + if (!enumtypes) + enumtypes = NewHash(); Setattr(enumtypes, Copy(s), n); } else { n = 0; diff --git a/Source/Modules/python.cxx b/Source/Modules/python.cxx index c745b95f2..33893f8fc 100644 --- a/Source/Modules/python.cxx +++ b/Source/Modules/python.cxx @@ -17,6 +17,7 @@ #include <ctype.h> #include <errno.h> #include <stdlib.h> +#include "pydoc.h" #include <iostream> #include <stdint.h> @@ -90,6 +91,7 @@ static int buildnone = 0; static int nobuildnone = 0; static int safecstrings = 0; static int dirvtable = 0; +static int doxygen = 0; static int proxydel = 1; static int fastunpack = 0; static int fastproxy = 0; @@ -111,7 +113,8 @@ enum autodoc_t { AUTODOC_DTOR, AUTODOC_STATICFUNC, AUTODOC_FUNC, - AUTODOC_METHOD + AUTODOC_METHOD, + AUTODOC_CONST }; @@ -125,6 +128,9 @@ Python Options (available with -python)\n\ -classptr - Generate shadow 'ClassPtr' as in older swig versions\n\ -cppcast - Enable C++ casting operators (default) \n\ -dirvtable - Generate a pseudo virtual table for directors for faster dispatch \n\ + -doxygen - Convert C++ doxygen comments to pydoc comments in proxy classes \n\ + -debug-doxygen-parser - Display doxygen parser module debugging information\n\ + -debug-doxygen-translator - Display doxygen translator module debugging information\n\ -extranative - Return extra native C++ wraps for std containers when possible \n\ -fastinit - Use fast init mechanism for classes (default)\n\ -fastunpack - Use fast unpack mechanism to parse the argument functions \n\ @@ -261,6 +267,11 @@ public: director_multiple_inheritance = 1; director_language = 1; } + + ~PYTHON() { + delete doxygenTranslator; + } + /* ------------------------------------------------------------ * Thread Implementation * ------------------------------------------------------------ */ @@ -336,6 +347,8 @@ public: SWIG_library_directory("python"); + int doxygen_translator_flags = 0; + for (int i = 1; i < argc; i++) { if (argv[i]) { if (strcmp(argv[i], "-interface") == 0) { @@ -426,6 +439,16 @@ public: } else if (strcmp(argv[i], "-nodirvtable") == 0) { dirvtable = 0; Swig_mark_arg(i); + } else if (strcmp(argv[i], "-doxygen") == 0) { + doxygen = 1; + scan_doxygen_comments = 1; + Swig_mark_arg(i); + } else if (strcmp(argv[i], "-debug-doxygen-translator") == 0) { + doxygen_translator_flags |= DoxygenTranslator::debug_translator; + Swig_mark_arg(i); + } else if (strcmp(argv[i], "-debug-doxygen-parser") == 0) { + doxygen_translator_flags |= DoxygenTranslator::debug_parser; + Swig_mark_arg(i); } else if (strcmp(argv[i], "-fastunpack") == 0) { fastunpack = 1; Swig_mark_arg(i); @@ -547,6 +570,9 @@ public: if (cppcast) { Preprocessor_define((DOH *) "SWIG_CPLUSPLUS_CAST", 0); } + + if (doxygen) + doxygenTranslator = new PyDocConverter(doxygen_translator_flags); if (!global_name) global_name = NewString("cvar"); @@ -1654,37 +1680,71 @@ public: bool have_docstring(Node *n) { String *str = Getattr(n, "feature:docstring"); - return (str && Len(str) > 0) || (Getattr(n, "feature:autodoc") && !GetFlag(n, "feature:noautodoc")); + return ((str && Len(str) > 0) + || (Getattr(n, "feature:autodoc") && !GetFlag(n, "feature:noautodoc")) + || (doxygen && doxygenTranslator->hasDocumentation(n)) + ); } /* ------------------------------------------------------------ - * docstring() + * build_combined_docstring() * - * Get the docstring text, stripping off {} if necessary, - * and enclose in triple double quotes. If autodoc is also - * set then it will build a combined docstring. + * Build the full docstring which may be a combination of the + * explicit docstring and autodoc string or, if none of them + * is specified, obtained by translating Doxygen comment to + * Python. + * + * Return new string to be deleted by caller (never NIL but + * may be empty if there is no docstring). * ------------------------------------------------------------ */ - String *docstring(Node *n, autodoc_t ad_type, const String *indent, bool use_triple = true) { - String *str = Getattr(n, "feature:docstring"); - bool have_ds = (str && Len(str) > 0); - bool have_auto = (Getattr(n, "feature:autodoc") && !GetFlag(n, "feature:noautodoc")); - const char *triple_double = use_triple ? "\"\"\"" : ""; - String *autodoc = NULL; - String *doc = NULL; - - if (have_ds) { - char *t = Char(str); + String *build_combined_docstring(Node *n, autodoc_t ad_type, const String *indent = "") { + String *docstr = Getattr(n, "feature:docstring"); + if (docstr && Len(docstr)) { + docstr = Copy(docstr); + char *t = Char(docstr); if (*t == '{') { - Delitem(str, 0); - Delitem(str, DOH_END); + Delitem(docstr, 0); + Delitem(docstr, DOH_END); } } - if (have_auto) { - autodoc = make_autodoc(n, ad_type); - have_auto = (autodoc && Len(autodoc) > 0); + if (Getattr(n, "feature:autodoc") && !GetFlag(n, "feature:noautodoc")) { + String *autodoc = make_autodoc(n, ad_type); + if (autodoc && Len(autodoc) > 0) { + if (docstr && Len(docstr)) { + Append(autodoc, "\n"); + Append(autodoc, docstr); + } + + String *tmp = autodoc; + autodoc = docstr; + docstr = tmp; + } + + Delete(autodoc); } + + if (!docstr || !Len(docstr)) { + if (doxygen) { + docstr = Getattr(n, "python:docstring"); + if (!docstr && doxygenTranslator->hasDocumentation(n)) { + docstr = doxygenTranslator->getDocumentation(n); + + // Avoid rebuilding it again the next time: notice that we can't do + // this for the combined doc string as autodoc part of it depends on + // the sym:name of the node and it is changed while handling it, so + // the cached results become incorrect. But Doxygen docstring only + // depends on the comment which is not going to change, so we can + // safely cache it. + Setattr(n, "python:docstring", Copy(docstr)); + } + } + } + + if (!docstr) + docstr = NewString(""); + // If there is more than one line then make docstrings like this: // // """ @@ -1693,46 +1753,59 @@ public: // """ // // otherwise, put it all on a single line + if (Strchr(docstr, '\n')) { + String *tmp = NewString(""); + Append(tmp, "\n"); + Append(tmp, indent_docstring(docstr, indent)); + Append(tmp, indent); + Delete(docstr); + docstr = tmp; + } + + return docstr; + } + + /* ------------------------------------------------------------ + * docstring() + * + * Get the docstring text, stripping off {} if necessary, + * and enclose in triple double quotes. If autodoc is also + * set then it will build a combined docstring. + * ------------------------------------------------------------ */ + + String *docstring(Node *n, autodoc_t ad_type, const String *indent) { + String *docstr = build_combined_docstring(n, ad_type, indent); + if (!Len(docstr)) + return docstr; + + // Notice that all comments are created as raw strings (prefix "r"), + // because '\' is used often in comments, but may break Python module from + // loading. For example, in doxy comment one may write path in quotes: // - if (have_auto && have_ds) { // Both autodoc and docstring are present - doc = NewString(""); - Printv(doc, triple_double, "\n", - indent_docstring(autodoc, indent), "\n", - indent_docstring(str, indent), indent, triple_double, NIL); - } else if (!have_auto && have_ds) { // only docstring - if (Strchr(str, '\n') == 0) { - doc = NewStringf("%s%s%s", triple_double, str, triple_double); - } else { - doc = NewString(""); - Printv(doc, triple_double, "\n", indent_docstring(str, indent), indent, triple_double, NIL); - } - } else if (have_auto && !have_ds) { // only autodoc - if (Strchr(autodoc, '\n') == 0) { - doc = NewStringf("%s%s%s", triple_double, autodoc, triple_double); - } else { - doc = NewString(""); - Printv(doc, triple_double, "\n", indent_docstring(autodoc, indent), indent, triple_double, NIL); - } - } else - doc = NewString(""); + // This is path to file "C:\x\file.txt" + // + // Python will not load the module with such comment because of illegal + // escape '\x'. '\' may additionally appear in verbatim or htmlonly sections + // of doxygen doc, Latex expressions, ... + String *doc = NewString(""); + Append(doc, "r\"\"\""); + Append(doc, docstr); + Append(doc, "\"\"\""); + Delete(docstr); - // Save the generated strings in the parse tree in case they are used later - // by post processing tools - Setattr(n, "python:docstring", doc); - Setattr(n, "python:autodoc", autodoc); return doc; - } + } /* ------------------------------------------------------------ * cdocstring() * * Get the docstring text as it would appear in C-language - * source code. + * source code (but without quotes around it). * ------------------------------------------------------------ */ String *cdocstring(Node *n, autodoc_t ad_type) { - String *ds = docstring(n, ad_type, "", false); + String *ds = build_combined_docstring(n, ad_type); Replaceall(ds, "\\", "\\\\"); Replaceall(ds, "\"", "\\\""); Replaceall(ds, "\n", "\\n\"\n\t\t\""); @@ -2008,17 +2081,24 @@ public: break; case AUTODOC_METHOD: - String *paramList = make_autodocParmList(n, showTypes); - Printf(doc, "%s(", symname); - if (showTypes) - Printf(doc, "%s ", class_name); - if (Len(paramList)) - Printf(doc, "self, %s)", paramList); - else - Printf(doc, "self)"); - if (type_str) - Printf(doc, " -> %s", type_str); + { + String *paramList = make_autodocParmList(n, showTypes); + Printf(doc, "%s(", symname); + if (showTypes) + Printf(doc, "%s ", class_name); + if (Len(paramList)) + Printf(doc, "self, %s)", paramList); + else + Printf(doc, "self)"); + if (type_str) + Printf(doc, " -> %s", type_str); + } break; + + case AUTODOC_CONST: + // There is no autodoc support for constants currently, this enum + // element only exists to allow calling docstring() with it. + return NULL; } Delete(type_str); } @@ -3641,20 +3721,21 @@ public: } if (!builtin && (shadow) && (!(shadow & PYSHADOW_MEMBER))) { + String *f_s; if (!in_class) { - if(needs_swigconstant(n)) { - Printv(f_shadow, "\n",NIL); - Printv(f_shadow, module, ".", iname, "_swigconstant(",module,")\n", NIL); - } - Printv(f_shadow, iname, " = ", module, ".", iname, "\n", NIL); + f_s = f_shadow; } else { - if (!(Getattr(n, "feature:python:callback"))) { - if(needs_swigconstant(n)) { - Printv(f_shadow_stubs, "\n",NIL); - Printv(f_shadow_stubs, module, ".", iname, "_swigconstant(", module, ")\n", NIL); - } - Printv(f_shadow_stubs, iname, " = ", module, ".", iname, "\n", NIL); + f_s = Getattr(n, "feature:python:callback") ? NIL : f_shadow_stubs; + } + + if (f_s) { + if (needs_swigconstant(n)) { + Printv(f_s, "\n",NIL); + Printv(f_s, module, ".", iname, "_swigconstant(",module,")\n", NIL); } + Printv(f_s, iname, " = ", module, ".", iname, "\n", NIL); + if (have_docstring(n)) + Printv(f_s, docstring(n, AUTODOC_CONST, tab4), "\n", NIL); } } return SWIG_OK; @@ -4137,7 +4218,16 @@ public: Printv(f, "#else\n", NIL); printSlot(f, getSlot(n, "feature:python:tp_flags", tp_flags), "tp_flags"); Printv(f, "#endif\n", NIL); - printSlot(f, quoted_tp_doc_str, "tp_doc"); + if (have_docstring(n)) { + String *ds = cdocstring(n, AUTODOC_CLASS); + String *tp_doc = NewString(""); + Printf(tp_doc, "\"%s\"", ds); + Delete(ds); + printSlot(f, tp_doc, "tp_doc"); + Delete(tp_doc); + } else { + printSlot(f, quoted_tp_doc_str, "tp_doc"); + } printSlot(f, getSlot(n, "feature:python:tp_traverse"), "tp_traverse", "traverseproc"); printSlot(f, getSlot(n, "feature:python:tp_clear"), "tp_clear", "inquiry"); printSlot(f, getSlot(n, "feature:python:tp_richcompare", richcompare_func), "tp_richcompare", "richcmpfunc"); @@ -4473,6 +4563,8 @@ public: } Printf(f_shadow, ":\n"); + + // write docstrings if requested if (have_docstring(n)) { String *str = docstring(n, AUTODOC_CLASS, tab4); if (str && Len(str)) @@ -4703,7 +4795,7 @@ public: String *wname = Swig_name_wrapper(fullname); Setattr(class_members, symname, n); int argcount = Getattr(n, "python:argcount") ? atoi(Char(Getattr(n, "python:argcount"))) : 2; - String *ds = have_docstring(n) ? cdocstring(n, AUTODOC_FUNC) : NewString(""); + String *ds = have_docstring(n) ? cdocstring(n, AUTODOC_METHOD) : NewString(""); if (check_kwargs(n)) { Printf(builtin_methods, " { \"%s\", (PyCFunction) %s, METH_VARARGS|METH_KEYWORDS, (char *) \"%s\" },\n", symname, wname, ds); } else if (argcount == 0) { @@ -5218,6 +5310,8 @@ public: Swig_restore(n); } else if (shadow) { Printv(f_shadow, tab4, symname, " = ", module, ".", Swig_name_member(NSPACE_TODO, class_name, symname), "\n", NIL); + if (have_docstring(n)) + Printv(f_shadow, tab4, docstring(n, AUTODOC_CONST, tab4), "\n", NIL); } return SWIG_OK; } diff --git a/Source/Modules/swigmod.h b/Source/Modules/swigmod.h index 31b506f77..1e49993bf 100644 --- a/Source/Modules/swigmod.h +++ b/Source/Modules/swigmod.h @@ -214,8 +214,8 @@ public: virtual Hash* symbolAddScope(const_String_or_char_ptr scope); virtual Hash* symbolScopeLookup(const_String_or_char_ptr scope); virtual Hash* symbolScopePseudoSymbolLookup(const_String_or_char_ptr scope); - virtual Node *classLookup(const SwigType *s) const; /* Class lookup */ - virtual Node *enumLookup(SwigType *s); /* Enum lookup */ + static Node *classLookup(const SwigType *s); /* Class lookup */ + static Node *enumLookup(SwigType *s); /* Enum lookup */ virtual int abstractClassTest(Node *n); /* Is class really abstract? */ virtual int is_assignable(Node *n); /* Is variable assignable? */ virtual String *runtimeCode(); /* returns the language specific runtime code */ @@ -342,10 +342,11 @@ protected: /* Director language module */ int director_language; + /* Used to translate Doxygen comments to target documentation format */ + class DoxygenTranslator *doxygenTranslator; + private: Hash *symtabs; /* symbol tables */ - Hash *classtypes; - Hash *enumtypes; int overloading; int multiinput; int cplus_runtime; diff --git a/Source/Swig/extend.c b/Source/Swig/extend.c index 30097b434..70355a245 100644 --- a/Source/Swig/extend.c +++ b/Source/Swig/extend.c @@ -106,10 +106,10 @@ void Swig_extend_append_previous(Node *cls, Node *am) { set_nextSibling(n,0); /* typemaps and fragments need to be prepended */ if (((Cmp(nodeType(n),"typemap") == 0) || (Cmp(nodeType(n),"fragment") == 0))) { - if (!pe) pe = new_node("extend"); + if (!pe) pe = Swig_cparse_new_node("extend"); appendChild(pe, n); } else { - if (!ae) ae = new_node("extend"); + if (!ae) ae = Swig_cparse_new_node("extend"); appendChild(ae, n); } n = ne; diff --git a/Source/Swig/misc.c b/Source/Swig/misc.c index a872628ef..6b071185b 100644 --- a/Source/Swig/misc.c +++ b/Source/Swig/misc.c @@ -1484,6 +1484,17 @@ String *Swig_pcre_version(void) { #endif +/* ------------------------------------------------------------ + * Swig_is_generated_overload() + * Check if the function is an automatically generated + * overload created because a method has default parameters. + * ------------------------------------------------------------ */ +int Swig_is_generated_overload(Node *n) { + Node *base_method = Getattr(n, "sym:overloaded"); + Node *default_args = Getattr(n, "defaultargs"); + return ((base_method != NULL) && (default_args != NULL) && (base_method == default_args)); +} + /* ----------------------------------------------------------------------------- * Swig_init() * diff --git a/Source/Swig/swig.h b/Source/Swig/swig.h index 5fb9edbf7..1acd32d5d 100644 --- a/Source/Swig/swig.h +++ b/Source/Swig/swig.h @@ -335,7 +335,9 @@ extern int ParmList_is_compactdefargs(ParmList *p); extern void Swig_offset_string(String *s, int number); extern String *Swig_pcre_version(void); extern void Swig_init(void); + extern int Swig_value_wrapper_mode(int mode); + extern int Swig_is_generated_overload(Node *n); typedef enum { EMF_STANDARD, EMF_MICROSOFT } ErrorMessageFormat; diff --git a/configure.ac b/configure.ac index 12f1c1591..c9e6afe68 100644 --- a/configure.ac +++ b/configure.ac @@ -1244,11 +1244,14 @@ case $host in if test -n "$JAVA_HOME"; then JAVA_HOME=`cygpath --mixed "$JAVA_HOME"` fi + dnl Java uses semicolons and not colons as separators in its classes search path under Windows. + JAVA_CLASSPATH_SEP=";" ;; *-*-mingw*) if test -n "$JAVA_HOME"; then JAVA_HOME=`${srcdir}/Tools/convertpath -u "$JAVA_HOME"` fi + JAVA_CLASSPATH_SEP=";" ;; *-*-darwin*) dnl Under OS X JAVA_HOME is not set by default, try to use the system default JRE. @@ -1261,6 +1264,11 @@ case $host in if test -r "$JAVA_OSX_STD_INCDIR/jni.h"; then JAVA_HOME_INCDIR=$JAVA_OSX_STD_INCDIR fi + JAVA_CLASSPATH_SEP=":" + ;; + *) + dnl Assume generic Unix. + JAVA_CLASSPATH_SEP=":" ;; esac @@ -1429,9 +1437,11 @@ fi # Turned off due to spurious warnings in later versions of openjdk-1.8 # JAVAFLAGS=-Xcheck:jni +AC_SUBST(JAVA_HOME) AC_SUBST(JAVA) AC_SUBST(JAVAC) AC_SUBST(JAVAINC) +AC_SUBST(JAVA_CLASSPATH_SEP) AC_SUBST(JAVADYNAMICLINKING) AC_SUBST(JAVALIBRARYPREFIX) AC_SUBST(JAVASO) |