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 diff --git a/COPYRIGHT b/COPYRIGHT index c3fbbdebd..baf15a5db 100644 --- a/COPYRIGHT +++ b/COPYRIGHT @@ -62,7 +62,8 @@ Past SWIG developers and major contributors include: John Lenz (Guile, MzScheme updates, Chicken module, runtime system) Baozeng Ding (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 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 - in JD, surrounded with __ in PD + \brief - ignored + \bug - ignored + \c - translated to 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 in JD, single quotes in PD + \class - ignored (structural command) + \code - translated to {@code ...} in JD, ignored in PD + \cond - translated to 'Conditional comment: '. 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: '. 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 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
  • 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

    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 @@ -

    19 SWIG and Allegro Common Lisp

    +

    20 SWIG and Allegro Common Lisp

    -

    19.2.2 Foreign Wrappers

    +

    20.2.2 Foreign Wrappers

    @@ -512,7 +512,7 @@ interested in generating an interface to C++. typemap.

    -

    19.2.3 FFI Wrappers

    +

    20.2.3 FFI Wrappers

    @@ -593,7 +593,7 @@ char *xxx(); ff:def-foreign-call's.

    -

    19.2.4 Non-overloaded Defuns

    +

    20.2.4 Non-overloaded Defuns

    @@ -606,7 +606,7 @@ char *xxx(); this function can be manipulated via the lout typemap.

    -

    19.2.5 Overloaded Defuns

    +

    20.2.5 Overloaded Defuns

    @@ -622,7 +622,7 @@ char *xxx(); can be manipulated via the lout typemap.

    -

    19.2.6 What about constant and variable access?

    +

    20.2.6 What about constant and variable access?

    @@ -635,7 +635,7 @@ char *xxx(); into the foreign module.

    -

    19.2.7 Object Wrapping

    +

    20.2.7 Object Wrapping

    @@ -657,7 +657,7 @@ char *xxx(); foreign function interface.

    -

    19.3 Wrapping Details

    +

    20.3 Wrapping Details

    @@ -665,7 +665,7 @@ char *xxx(); translated into lisp.

    -

    19.3.1 Namespaces

    +

    20.3.1 Namespaces

    @@ -742,7 +742,7 @@ namespace car { function such as (car '(1 2 3).

    -

    19.3.2 Constants

    +

    20.3.2 Constants

    @@ -803,7 +803,7 @@ namespace car { not use the -nocwrap command-line option.

    -

    19.3.3 Variables

    +

    20.3.3 Variables

    @@ -881,7 +881,7 @@ globalvar> (globalvar.nnn::glob_float) -

    19.3.4 Enumerations

    +

    20.3.4 Enumerations

    @@ -957,7 +957,7 @@ EXPORT const int ACL_ENUM___FOO3__SWIG_0 = FOO3; -

    19.3.5 Arrays

    +

    20.3.5 Arrays

    @@ -1105,10 +1105,10 @@ namespace BAR { -

    19.3.6 Classes and Structs and Unions (oh my!)

    +

    20.3.6 Classes and Structs and Unions (oh my!)

    -

    19.3.6.1 CLOS wrapping of

    +

    20.3.6.1 CLOS wrapping of

    @@ -1123,7 +1123,7 @@ namespace BAR { integer values.

    -

    19.3.6.2 CLOS Inheritance

    +

    20.3.6.2 CLOS Inheritance

    @@ -1136,7 +1136,7 @@ namespace BAR { parameter.

    -

    19.3.6.3 Member fields and functions

    +

    20.3.6.3 Member fields and functions

    @@ -1152,7 +1152,7 @@ namespace BAR { the interface does nothing for friend directives,

    -

    19.3.6.4 Why not directly access C++ classes using foreign types?

    +

    20.3.6.4 Why not directly access C++ classes using foreign types?

    @@ -1170,11 +1170,11 @@ namespace BAR { use the more robust wrapper functions.

    -

    19.3.7 Templates

    +

    20.3.7 Templates

    -

    19.3.7.1 Generating wrapper code for templates

    +

    20.3.7.1 Generating wrapper code for templates

    @@ -1187,7 +1187,7 @@ them. This is done via the directive.

    -

    19.3.7.2 Implicit Template instantiation

    +

    20.3.7.2 Implicit Template instantiation

    @@ -1197,7 +1197,7 @@ to include these templated classes in the foreign-type and CLOS class schema.

    -

    19.3.8 Typedef, Templates, and Synonym Types

    +

    20.3.8 Typedef, Templates, and Synonym Types

    @@ -1277,7 +1277,7 @@ synonym> -

    19.3.8.1 Choosing a primary type

    +

    20.3.8.1 Choosing a primary type

    @@ -1298,7 +1298,7 @@ synonym> -

    19.3.9 Function overloading/Parameter defaulting

    +

    20.3.9 Function overloading/Parameter defaulting

    @@ -1461,7 +1461,7 @@ overload> -

    19.3.10 Operator wrapping and Operator overloading

    +

    20.3.10 Operator wrapping and Operator overloading

    @@ -1607,7 +1607,7 @@ opoverload> -

    19.3.11 Varargs

    +

    20.3.11 Varargs

    @@ -1628,7 +1628,7 @@ opoverload> with other ways such functions can be wrapped.

    -

    19.3.12 C++ Exceptions

    +

    20.3.12 C++ Exceptions

    @@ -1640,7 +1640,7 @@ opoverload> implemented.

    -

    19.3.13 Pass by value, pass by reference

    +

    20.3.13 Pass by value, pass by reference

    @@ -1652,7 +1652,7 @@ opoverload> newly defined types.

    -

    19.4 Typemaps

    +

    20.4 Typemaps

    @@ -1663,7 +1663,7 @@ opoverload> on Typemaps for more information.

    -

    19.4.1 Code Generation in the C++ Wrapper

    +

    20.4.1 Code Generation in the C++ Wrapper

    @@ -1693,7 +1693,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -

    19.4.1.1 IN Typemap

    +

    20.4.1.1 IN Typemap

    @@ -1728,7 +1728,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -

    19.4.1.2 OUT Typemap

    +

    20.4.1.2 OUT Typemap

    @@ -1752,7 +1752,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -

    19.4.1.3 CTYPE Typemap

    +

    20.4.1.3 CTYPE Typemap

    @@ -1784,7 +1784,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) these common typemaps here.

    -

    19.4.2 Code generation in Lisp wrappers

    +

    20.4.2 Code generation in Lisp wrappers

    @@ -1803,7 +1803,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) 16.3.1 Namespaces for details.

    -

    19.4.2.1 LIN Typemap

    +

    20.4.2.1 LIN Typemap

    @@ -1846,7 +1846,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -

    19.4.2.2 LOUT Typemap

    +

    20.4.2.2 LOUT Typemap

    @@ -1889,7 +1889,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -

    19.4.2.3 FFITYPE Typemap

    +

    20.4.2.3 FFITYPE Typemap

    @@ -1939,7 +1939,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -

    19.4.2.4 LISPTYPE Typemap

    +

    20.4.2.4 LISPTYPE Typemap

    @@ -1959,7 +1959,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -

    19.4.2.5 LISPCLASS Typemap

    +

    20.4.2.5 LISPCLASS Typemap

    @@ -1983,7 +1983,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -

    19.4.3 Modifying SWIG behavior using typemaps

    +

    20.4.3 Modifying SWIG behavior using typemaps

    @@ -2017,10 +2017,10 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -

    19.5 Identifier Converter functions

    +

    20.5 Identifier Converter functions

    -

    19.5.1 Creating symbols in the lisp environment

    +

    20.5.1 Creating symbols in the lisp environment

    @@ -2041,11 +2041,11 @@ return-val wrapper-name(parm0, parm1, ..., parmN) of arguments.

    -

    19.5.2 Existing identifier-converter functions

    +

    20.5.2 Existing identifier-converter functions

    Two basic identifier routines have been defined. -

    19.5.2.1 identifier-convert-null

    +

    20.5.2.1 identifier-convert-null

    @@ -2054,7 +2054,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) strings, from which a symbol will be created.

    -

    19.5.2.2 identifier-convert-lispify

    +

    20.5.2.2 identifier-convert-lispify

    @@ -2063,7 +2063,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) same symbol transformations.

    -

    19.5.2.3 Default identifier to symbol conversions

    +

    20.5.2.3 Default identifier to symbol conversions

    @@ -2072,7 +2072,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) default naming conventions.

    -

    19.5.3 Defining your own identifier-converter

    +

    20.5.3 Defining your own identifier-converter

    @@ -2128,7 +2128,7 @@ indicating the number of arguments passed to the routine indicated by this identifier.

    -

    19.5.4 Instructing SWIG to use a particular identifier-converter

    +

    20.5.4 Instructing SWIG to use a particular identifier-converter

    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 @@ -

    20 SWIG and Android

    +

    21 SWIG and Android

    -

    18.16 CREDITS

    +

    19.16 CREDITS

    @@ -453,7 +453,7 @@ Thanks to the following people for their contributions to ccache

  • Paul Russell for many suggestions and the debian packaging

    -

    18.17 AUTHOR

    +

    19.17 AUTHOR

    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 @@ -

    21 SWIG and C#

    +

    22 SWIG and C#

    -

    21.4 C# Arrays

    +

    22.4 C# Arrays

    @@ -586,7 +586,7 @@ with one of the following three approaches; namely the SWIG C arrays library, P/ pinned arrays.

    -

    21.4.1 The SWIG C arrays library

    +

    22.4.1 The SWIG C arrays library

    @@ -623,7 +623,7 @@ example.print_array(c.cast()); // Pass to C

    • -

    21.4.2 Managed arrays using P/Invoke default array marshalling

    +

    22.4.2 Managed arrays using P/Invoke default array marshalling

    @@ -750,7 +750,7 @@ and intermediary class method -

    21.4.3 Managed arrays using pinning

    +

    22.4.3 Managed arrays using pinning

    @@ -845,7 +845,7 @@ public static extern void myArrayCopy(global::System.IntPtr jarg1, global::Syste -

    21.5 C# Exceptions

    +

    22.5 C# Exceptions

    @@ -942,7 +942,7 @@ set so should only be used when a C# exception is not created.

    -

    21.5.1 C# exception example using "check" typemap

    +

    22.5.1 C# exception example using "check" typemap

    @@ -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 SWIG_CSharpSetPendingException.

    -

    21.5.2 C# exception example using %exception

    +

    22.5.2 C# exception example using %exception

    @@ -1189,7 +1189,7 @@ The managed code generated does check for the pending exception as mentioned ear -

    21.5.3 C# exception example using exception specifications

    +

    22.5.3 C# exception example using exception specifications

    @@ -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.

    -

    21.5.4 Custom C# ApplicationException example

    +

    22.5.4 Custom C# ApplicationException example

    @@ -1379,7 +1379,7 @@ try { -

    21.6 C# Directors

    +

    22.6 C# Directors

    @@ -1392,7 +1392,7 @@ The following sections provide information on the C# director implementation and However, the Java directors section should also be read in order to gain more insight into directors.

    -

    21.6.1 Directors example

    +

    22.6.1 Directors example

    @@ -1513,7 +1513,7 @@ CSharpDerived - UIntMethod(123) -

    21.6.2 Directors implementation

    +

    22.6.2 Directors implementation

    @@ -1721,7 +1721,7 @@ before SWIG parses the Base class will change all the delegates to internal< -

    21.6.3 Director caveats

    +

    22.6.3 Director caveats

    @@ -1769,7 +1769,7 @@ However, a call from C# to CSharpDefaults.DefaultMethod() will of cours should pass the call on to CSharpDefaults.DefaultMethod(int)using the C++ default value, as shown above.

    -

    21.7 Multiple modules

    +

    22.7 Multiple modules

    @@ -1804,7 +1804,7 @@ the [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrows if you don't want users to easily stumble upon these so called 'internal workings' of the wrappers.

    -

    21.8 C# Typemap examples

    +

    22.8 C# Typemap examples

    This section includes a few examples of typemaps. For more examples, you @@ -1812,7 +1812,7 @@ might look at the files "csharp.swg" and "typemaps.i" in the SWIG library. -

    21.8.1 Memory management when returning references to member variables

    +

    22.8.1 Memory management when returning references to member variables

    @@ -1936,7 +1936,7 @@ public class Bike : global::System.IDisposable { Note the addReference call.

    -

    21.8.2 Memory management for objects passed to the C++ layer

    +

    22.8.2 Memory management for objects passed to the C++ layer

    @@ -2068,7 +2068,7 @@ as mentioned earlier, setElement is actually: -

    21.8.3 Date marshalling using the csin typemap and associated attributes

    +

    22.8.3 Date marshalling using the csin typemap and associated attributes

    @@ -2354,7 +2354,7 @@ public class example { -

    21.8.4 A date example demonstrating marshalling of C# properties

    +

    22.8.4 A date example demonstrating marshalling of C# properties

    @@ -2454,7 +2454,7 @@ Some points to note:

  • 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 temp$csinput variable is such an example; it is identical to what is in the 'pre' attribute. -

    21.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors

    +

    22.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors

    @@ -2516,7 +2516,7 @@ Pay special attention to the memory management issues, using these attributes.

    -

    21.8.6 Turning proxy classes into partial classes

    +

    22.8.6 Turning proxy classes into partial classes

    @@ -2616,7 +2616,7 @@ demonstrating that the class contains methods calling both unmanaged code - The following example is an alternative approach to adding managed code to the generated proxy class.

    -

    21.8.7 Turning proxy classes into sealed classes

    +

    22.8.7 Turning proxy classes into sealed classes

    @@ -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.

    -

    21.8.8 Extending proxy classes with additional C# code

    +

    22.8.8 Extending proxy classes with additional C# code

    @@ -2745,7 +2745,7 @@ public class ExtendMe : global::System.IDisposable { -

    21.8.9 Underlying type for enums

    +

    22.8.9 Underlying type for enums

    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 @@ -

    22 SWIG and Chicken

    +

    23 SWIG and Chicken

    -

    22.3 TinyCLOS

    +

    23.3 TinyCLOS

    @@ -333,7 +333,7 @@

    -

    22.4 Linkage

    +

    23.4 Linkage

    @@ -354,7 +354,7 @@

    -

    22.4.1 Static binary or shared library linked at compile time

    +

    23.4.1 Static binary or shared library linked at compile time

    We can easily use csc to build a static binary.

    @@ -395,7 +395,7 @@ in which case the test script does not need to be linked with example.so. The t be run with csi.

    -

    22.4.2 Building chicken extension libraries

    +

    23.4.2 Building chicken extension libraries

    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.

    See the Examples/chicken/egg directory in the SWIG source for an example that builds two eggs, one using the first method and one using the second method.

    -

    22.4.3 Linking multiple SWIG modules with TinyCLOS

    +

    23.4.3 Linking multiple SWIG modules with TinyCLOS

    Linking together multiple modules that share type information using the %import @@ -477,7 +477,7 @@ with (declare (uses ...)). To create an extension library or an egg, just create a module_load.scm file that (declare (uses ...)) all the modules.

    -

    22.5 Typemaps

    +

    23.5 Typemaps

    @@ -486,7 +486,7 @@ all the modules.

    Lib/chicken/chicken.swg.

    -

    22.6 Pointers

    +

    23.6 Pointers

    @@ -519,7 +519,7 @@ all the modules.

    type. flags is either zero or SWIG_POINTER_DISOWN (see below).

    -

    22.6.1 Garbage collection

    +

    23.6.1 Garbage collection

    If the owner flag passed to SWIG_NewPointerObj is 1, NewPointerObj will add a @@ -550,7 +550,7 @@ all the modules.

    must be called manually.

    -

    22.7 Unsupported features and known problems

    +

    23.7 Unsupported features and known problems

    -

    22.7.1 TinyCLOS problems with Chicken version <= 1.92

    +

    23.7.1 TinyCLOS problems with Chicken version <= 1.92

    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 @@ -

    16 Warning Messages

    +

    16 SWIG and Doxygen Translation

    + + +
    + +
    + + +

    17 Warning Messages

    @@ -619,7 +663,7 @@
    -

    17 Working with Modules

    +

    18 Working with Modules

    @@ -635,7 +679,7 @@
    -

    18 Using SWIG with ccache - ccache-swig(1) manpage

    +

    19 Using SWIG with ccache - ccache-swig(1) manpage

    @@ -661,7 +705,7 @@
    -

    19 SWIG and Allegro Common Lisp

    +

    20 SWIG and Allegro Common Lisp

    @@ -745,7 +789,7 @@
    -

    20 SWIG and Android

    +

    21 SWIG and Android

    @@ -763,7 +807,7 @@
    -

    21 SWIG and C#

    +

    22 SWIG and C#

    @@ -811,7 +855,7 @@
    -

    22 SWIG and Chicken

    +

    23 SWIG and Chicken

    @@ -849,7 +893,7 @@
    -

    23 SWIG and D

    +

    24 SWIG and D

    @@ -883,7 +927,7 @@
    -

    24 SWIG and Go

    +

    25 SWIG and Go

    @@ -927,7 +971,7 @@
    -

    25 SWIG and Guile

    +

    26 SWIG and Guile

    @@ -963,7 +1007,7 @@
    -

    26 SWIG and Java

    +

    27 SWIG and Java

    @@ -1117,7 +1161,7 @@
    -

    27 SWIG and Javascript

    +

    28 SWIG and Javascript

    @@ -1159,7 +1203,7 @@
    -

    28 SWIG and Common Lisp

    +

    29 SWIG and Common Lisp

    @@ -1182,7 +1226,7 @@
    -

    29 SWIG and Lua

    +

    30 SWIG and Lua

    @@ -1250,7 +1294,7 @@
    -

    30 SWIG and Modula-3

    +

    31 SWIG and Modula-3

    @@ -1288,7 +1332,7 @@
    -

    31 SWIG and MzScheme/Racket

    +

    32 SWIG and MzScheme/Racket

    @@ -1300,7 +1344,7 @@
    -

    32 SWIG and Ocaml

    +

    33 SWIG and Ocaml

    @@ -1351,7 +1395,7 @@
    -

    33 SWIG and Octave

    +

    34 SWIG and Octave

    @@ -1391,7 +1435,7 @@
    -

    34 SWIG and Perl5

    +

    35 SWIG and Perl5

    @@ -1467,7 +1511,7 @@
    -

    35 SWIG and PHP

    +

    36 SWIG and PHP

    @@ -1508,7 +1552,7 @@
    -

    36 SWIG and Pike

    +

    37 SWIG and Pike

    @@ -1532,7 +1576,7 @@
    -

    37 SWIG and Python

    +

    38 SWIG and Python

    @@ -1668,7 +1712,7 @@
    -

    38 SWIG and R

    +

    39 SWIG and R

    @@ -1684,7 +1728,7 @@
    -

    39 SWIG and Ruby

    +

    40 SWIG and Ruby

    @@ -1822,7 +1866,7 @@
    -

    40 SWIG and Scilab

    +

    41 SWIG and Scilab

    @@ -1891,7 +1935,7 @@
    -

    41 SWIG and Tcl

    +

    42 SWIG and Tcl

    @@ -1957,7 +2001,7 @@
    -

    42 Extending SWIG to support new languages

    +

    43 Extending SWIG to support new languages

    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 @@ -

    23 SWIG and D

    +

    24 SWIG and D

      @@ -41,7 +41,7 @@ -

      23.1 Introduction

      +

      24.1 Introduction

      From the D Programming Language web site: 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. As such, it is not very surprising that D is able to directly interface with C libraries. Why would a SWIG module for D be needed then in the first place?

      @@ -53,7 +53,7 @@

      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 C# (and also on Java, since the C# module was in turn forked from it).

      -

      23.2 Command line invocation

      +

      24.2 Command line invocation

      To activate the D module, pass the -d 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:

      @@ -83,10 +83,10 @@ -

      23.3 Typemaps

      +

      24.3 Typemaps

      -

      23.3.1 C# <-> D name comparison

      +

      24.3.1 C# <-> D name comparison

      If you already know the SWIG C# module, you might find the following name comparison table useful:

      @@ -112,7 +112,7 @@
    -

    23.3.2 ctype, imtype, dtype

    +

    24.3.2 ctype, imtype, dtype

    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.

    @@ -120,7 +120,7 @@

    The ctype typemap is used to determine the types to use in the C wrapper functions. The types from the imtype typemap are used in the extern(C) declarations of these functions in the intermediary D module. The dtype typemap contains the D types used in the D proxy module/class.

    -

    23.3.3 in, out, directorin, directorout

    +

    24.3.3 in, out, directorin, directorout

    Used for converting between the types for C/C++ and D when generating the code for the wrapper functions (on the C++ side).

    @@ -130,7 +130,7 @@

    The directorin typemap is used to convert parameters to the type used in the D director callback function, its return value is processed by directorout (see below).

    -

    23.3.4 din, dout, ddirectorin, ddirectorout

    +

    24.3.4 din, dout, ddirectorin, ddirectorout

    Typemaps for code generation in D proxy and type wrapper classes.

    @@ -157,13 +157,13 @@ dtype DClass.method(dtype a)
    -

    23.3.5 typecheck typemaps

    +

    24.3.5 typecheck typemaps

    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).

    -

    23.3.6 Code injection typemaps

    +

    24.3.6 Code injection typemaps

    These typemaps are used for generating the skeleton of proxy classes for C++ types.

    @@ -178,7 +178,7 @@ Code can also be injected into the D proxy class using %proxycode.

    -

    23.3.7 Special variable macros

    +

    24.3.7 Special variable macros

    The standard SWIG special variables are available for use within typemaps as described in the Typemaps documentation, for example $1, $input, $result etc.

    @@ -299,7 +299,7 @@ $importtype(AnotherInterface) -

    23.4 D and %feature

    +

    24.4 D and %feature

    The D module defines a number of directives which modify the SWIG features set globally or for a specific declaration:

    @@ -329,7 +329,7 @@ struct A { -

    23.5 Pragmas

    +

    24.5 Pragmas

    There are a few SWIG pragmas specific to the D module, which you can use to influence the D code SWIG generates:

    @@ -368,7 +368,7 @@ struct A { -

    23.6 D Exceptions

    +

    24.6 D Exceptions

    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.

    @@ -378,7 +378,7 @@ struct A {

    As this feature is implemented in exactly the same way it is for C#, please see the C# documentation for a more detailed explanation.

    -

    23.7 D Directors

    +

    24.7 D Directors

    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++.

    @@ -387,16 +387,16 @@ struct A {

    -

    23.8 Other features

    +

    24.8 Other features

    -

    23.8.1 Extended namespace support (nspace)

    +

    24.8.1 Extended namespace support (nspace)

    By default, SWIG flattens all C++ namespaces into a single target language namespace, but as for Java and C#, the nspace 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, free variables and functions are not supported yet; currently, they are all allows written to the main proxy D module.

    -

    23.8.2 Native pointer support

    +

    24.8.2 Native pointer support

    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 primitive type below.

    @@ -408,7 +408,7 @@ struct A {

    To determine if a type should be considered primitive, the cprimitive attribute on its dtype attribute is used. For example, the dtype typemap for float has cprimitive="1", so the code from the nativepointer attribute is taken into account e.g. for float ** or the function pointer float (*)(float *).

    -

    23.8.3 Operator overloading

    +

    24.8.3 Operator overloading

    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:

    @@ -420,7 +420,7 @@ struct A {

    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, [], in combination with assignments - while operator [] in C++ simply returns a reference which is then written to, D resorts to a separate opIndexAssign method -, or implicit casting (which was introduced in D2 via alias this). Despite the lack of automatic support, manually handling these cases should be perfectly possible.

    -

    23.8.4 Running the test-suite

    +

    24.8.4 Running the test-suite

    As with any other language, the SWIG test-suite can be built for D using the *-d-test-suite targets of the top-level Makefile. By default, D1 is targeted, to build it with D2, use the optional D_VERSION variable, e.g. make check-d-test-suite D_VERSION=2.

    @@ -428,14 +428,14 @@ struct A {

    Note: If you want to use GDC on Linux or another platform which requires you to link libdl for dynamically loading the shared library, you might have to add -ldl manually to the d_compile target in Examples/Makefile, because GDC does not currently honor the pragma(lib, ...) statement.

    -

    23.9 D Typemap examples

    +

    24.9 D Typemap examples

    There are no D-specific typemap examples yet. However, with the above name comparison table, you should be able to get an idea what can be done by looking at the corresponding C# section.

    -

    23.10 Work in progress and planned features

    +

    24.10 Work in progress and planned features

    There are a couple of features which are not implemented yet, but would be very useful and might be added in the near future:

    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 @@ + + + +SWIG and Doxygen Translation + + + +

    16 SWIG and Doxygen Translation

    + +
    + +
    + + + + +

    +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. +

    + +

    16.1 Doxygen translation overview

    + + +

    +The Doxygen Translation module of SWIG adds an extra layer of +functionality to SWIG, allowing automated translation of Doxygen 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 Google Summer of +Code proposal from Summer 2008. +

    + +

    16.2 Preparations

    + + +

    +To make use of the comment translation system, your documentation +comments must be in properly formatted Doxygen. 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 Documenting the +code 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). +

    + +

    +Currently, the whole subset of Doxygen comment styles is supported +(See +Documenting the code). Here they are: +

    + +
    +/**
+ * Javadoc style comment, multiline
+ */
+/*!
+ * QT-style comment, multiline
+ */
+/**
+ Any of the above, but without intermediate *'s
+ */
+/// Single-line comment
+//! Another single-line comment
+
    + +

    +Also any of the above with '<' added after comment-starting symbol, +like /**<, /*!<, ///<, or //!< 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 /*********/ or //////////. +

    + +

    +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. +

    +

    +Comments can be placed before C/C++ expressions on separate lines: +

    + +
    +/**
+ * Some comment
+ */
+void someOtherFunction();
+/**
+ * Some comment
+ */
+void someFunction();
+
+class Shape {
+  /*
+   * Calculate the area in cm^2
+   */
+  int getArea();
+}
+
    + +

    +After C/C++ expressions at the end of the line: +

    + +
    +int someVariable = 9; ///< This is a var holding magic number 9
+void doNothing(); ///< This does nothing, nop
+
    + +

    +and in some special cases, like function parameter comments: +

    + +
    +void someFunction(
+         int a ///< Some parameter 
+     );
+
    + +

    +or enum element comments: +

    + +
    +enum E_NUMBERS
+{
+    EN_ZERO, ///< The first enum item, gets zero as it's value
+    EN_ONE, ///< The second, EN_ONE=1
+    EN_THREE
+};
+
    + +

    +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. +

    + +

    16.2.1 Enabling Doxygen translation

    + + +

    +Doxygen comments translation is disabled by default and needs to be explicitly +enabled using the command line -doxygen switch for the languages that +do support it (currently Java and Python). +

    + +

    16.2.2 Doxygen-specific %feature directives

    + + +

    +Translation of Doxygen comments is influenced by the following %feature directives: +

    + +

    16.2.2.1 doxygen:notranslate

    + + +

    +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 (javadoc, sphinx, +...). +

    + + +

    16.2.2.2 doxygen:alias:<command-name>

    + + +

    +Specify an alias for a Doxygen command with the given name. This can be useful +for custom Doxygen commands which can be defined using ALIASES option +for Doxygen itself but which are unknown to SWIG. "command-name" is the +name of the command in the Doxyfile, e.g. if it contains +

    + +
    +ALIASES = "sideeffect=\par Side Effects:\n"
+
    + +

    +Then you could also specify the same expansion for SWIG with: +

    + +
    +%feature("doxygen:alias:sideeffect") "\par Side Effects:\n"
+
    + +

    +Please note that command arguments are not currently supported with this +feature. +

    + +

    +Notice that it is perfectly possible and potentially useful to define the alias +expansion differently depending on the target language, e.g. with +

    + +
    +#ifdef SWIGJAVA
+%feature("doxygen:alias:not_for_java") "This functionality is not available for Java"
+#else
+%feature("doxygen:alias:not_for_java") ""
+#endif
+
    + +

    +you could use @not_for_java in the documentation comments of all +functions which can't, for whatever reason, be currently exposed in Java +wrappers of the C++ API. +

    + + +

    16.2.2.3 doxygen:ignore:<command-name>

    + + +

    +This feature makes it possible to just ignore an unknown Doxygen command, instead of +replacing it with the predefined text that doxygen:alias does. +For example, you could use +

    + +
    +%feature("doxygen:ignore:transferfull") Fantastic();
+/**
+    A fantastic function.
+
+    @transferfull Command ignored, but anything here is still included.
+ */
+int * Fantastic() { }
+
    + +

    +if you use a custom Doxygen transferfull 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. +

    + +

    +Doxygen syntax is rather rich and, in addition to simple commands such as +@transferfull, it is also possible to define commands with arguments. +As explained in Doxygen documentation, +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 range="line" argument of the +feature directive: +

    + +
    +// 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();
+
+
    + +

    +In addition, it is also possible to have custom pairs of begin/end tags, +similarly to the standard Doxygen @code/@endcode, for example. Such +tags can also be ignored using the special value of range starting with +end to indicate that the range is an interval, for example: +

    + +
    +%feature("doxygen:ignore:forcpponly", range="end"); // same as "end:endforcpponly"
+/**
+    An incredible function.
+
+    @forcpponly
+    This is C++-specific.
+    @endforcpponly
+ */
+void Incredible();
+
    + +

    +would ignore everything between @forcpponly and @endforcpponly +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. +

    +

    +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 +contents="parse" can be used for this: +

    + +
    +%feature("doxygen:ignore:beginPythonOnly", range="end:endPythonOnly", contents="parse");
+/**
+    A splendid function.
+
+    @beginPythonOnly
+    This is specific to @b Python.
+    @endPythonOnly
+ */
+void Splendid();
+
+
    + +

    +Putting everything together, if these directives are in effect: +

    + +
    +%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");
+
    + +

    +then the following C++ Doxygen comment: +

    + +
    +/**
+    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();
+
    + +

    +would be translated to this comment in Python: +

    + +
    +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.
+    """
+    ...
+
    + + +

    16.2.2.4 doxygen:nolinktranslate

    + + +

    +Turn off automatic link-objects translation. +This is only applicable to Java at the moment. +

    + + +

    16.2.2.5 doxygen:nostripparams

    + + +

    +Turn off stripping of @param and @tparam +Doxygen commands if the parameter is not found in the function signature. +This is only applicable to Java at the moment. +

    + + +

    16.2.3 Additional command line options

    + + +

    +ALSO TO BE ADDED (Javadoc auto brief?) +

    + +

    16.3 Doxygen to Javadoc

    + + +

    +If translation is enabled, Javadoc formatted comments should be +automatically placed in the correct locations in the resulting module +and proxy files. +

    + +

    16.3.1 Basic example

    + + +

    +Here is an example segment from an included header file +

    +
    +/*! 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;
+};
+
    + +

    +Simply running SWIG should result in the following code being present in Shapes.java +

    + +
    +
+/**
+ * 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);
+  }
+}
+
+
    + +

    +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. +

    + +

    +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. +

    + +

    +Javadoc translator features summary +(see %feature +directives): +

    + +

    16.3.2 Javadoc tags

    + + +

    +Here is the list of all Doxygen tags and the description of how they are translated to Javadoc +

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Doxygen tags
    \awrapped with <i> html tag
    \argwrapped with <li> html tag
    \authortranslated to @author
    \authorstranslated to @author
    \bwrapped with <b> html tag
    \cwrapped with <code> html tag
    \citewrapped with <i> html tag
    \codetranslated to {@code ...}
    \condtranslated to 'Conditional comment: <condition>'
    \copyrightreplaced with 'Copyright:'
    \deprecatedtranslated to @deprecated
    \ewrapped with <i> html tag
    \elsereplaced with '}Else:{'
    \elseifreplaced with '}Else if: <condition>{'
    \emwrapped with <i> html tag
    \endcodesee note for \code
    \endcondreplaced with 'End of conditional comment.'
    \endifreplaced with '}'
    \endlinksee note for \link
    \endverbatimsee note for \verbatim
    \exceptiontranslated to @exception
    \f$, \f[, \f], \f{, \f}LateX formulas are left unchanged
    \ifreplaced with 'If: <condition> {'
    \ifnotreplaced with 'If not: <condition> {'
    \imagetranslated to <img/> html tag only if target=HTML
    \liwrapped with <li> html tag
    \linktranslated to {@link ...}
    \nreplaced with new line char
    \notereplaced with 'Note:'
    \overloadprints 'This is an overloaded ...' according to Doxygen docs
    \pwrapped with <code> html tag
    \parreplaced with <p alt='title'>...</p>
    \paramtranslated to @param
    \remarkreplaced with 'Remarks:'
    \remarksreplaced with 'Remarks:'
    \resulttranslated to @return
    \returntranslated to @return
    \returnstranslated to @return
    \satranslated to @see
    \seetranslated to @see
    \sincetranslated to @since
    \throwtranslated to @throws
    \throwstranslated to @throws
    \todoreplaced with 'TODO:'
    \tparamtranslated to @param
    \verbatimtranslated to {@literal ...}
    \versiontranslated to @version
    \warningtranslated to 'Warning:'
    \$prints $ char
    \@prints @ char
    \\prints \ char
    \&prints & char
    \~prints ~ char
    \<prints < char
    \>prints > char
    \#prints # char
    \%prints % char
    \"prints " char
    \.prints . char
    \::prints ::
    +
    + +

    16.3.3 Unsupported tags

    + + +

    +Doxygen has a wealth of tags such as @latexonly that have no +equivalent in Javadoc (all supported tags are listed in +Javadoc documentation). +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: +

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Unsupported Doxygen tags
    \addindex\addtogroup\anchor\attention
    \brief\bug\callgraph\callergraph
    \class\copybrief\copydetails\copydoc
    \date\def\defgroup\details
    \dir\dontinclude\dot\dotfile
    \enddot\endhtmlonly\endinternal\endlatexonly
    \endmanonly\endmsc\endrtfonly\endxmlonly
    \enum\example\extends
    \file\fn\headerfile\hideinitializer
    \htmlinclude\htmlonly\implements\include
    \includelineno\ingroup\internal\invariant
    \interface\latexonly\line\mainpage
    \manonly\memberof\msc\mscfile
    \name\namespace\nosubgrouping\package
    \page\paragraph\post\pre
    \private\privatesection\property\protected
    \protectedsection\protocol\public\publicsection
    \ref\related\relates\relatedalso
    \relatesalso\retval\rtfonly\section
    \short\showinitializer\skip\skipline
    \snippet\struct\subpage\subsection
    \subsubsection\tableofcontents\test\typedef
    \union\until\var\verbinclude
    \weakgroup\xmlonly\xrefitem\category
    +
    + +

    + +If one of the following Doxygen tags appears as the first tag in a +comment, the whole comment block is ignored: + + +

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Ignored Doxygen tags
    \addtogroup\callgraph\callergraph\category
    \class\def\defgroup\dir
    \enum\example\file\fn
    \headerfile\hideinitializer\interface\internal
    \mainpage\name\namespace\nosubgrouping
    \overload\package\page\property
    \protocol\relates\relatesalso\showinitializer
    \struct\name\namespace\nosubgrouping
    \typedef\union\var\weakgroup
    +
    + + + +

    16.3.4 Further details

    + + +

    +TO BE ADDED. +

    + +

    16.4 Doxygen to Pydoc

    + + +

    +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. +

    + +

    16.4.1 Basic example

    + + +

    +Here is an example segment from an included header file +

    +
    +/*! 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;
+};
+
    + +

    +Simply running SWIG should result in the following code being present in Shapes.py +

    + +
    +
+...
+
+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)
+
    + +

    +If any parameters of a function or a method are documented in the Doxygen comment, +their description is copied into the generated output using +Sphinx documentation conventions. For example +

    +
    +/**
+    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);
+
    + +

    +would be translated to +

    + +
    +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.
+    """
+
    +

    +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. std::string and +shared_ptr<T>) but for non-primitive types is taken to be just the C++ +name of the type with namespace scope delimiters (::) replaced with a dot. To +change this, you can define your own typemaps for the custom types, e.g: +

    +
    +%typemap(doctype) MyDate "datetime.date";
+
    + +

    +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. +

    + +

    + Whitespace and tables + 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: + +

    +/**
+ * <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>
+ */
+
    +

    +translates to Python as: +

    +
    +  Animals
+  | Column 1 | Column 2 |
+  -----------------------
+  | cow      | dog      |
+  | cat      | mouse    |
+  | horse    | parrot   |
+
    + +

    + Overloaded functions +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. +

    +

    +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 Doxygen +docs), you may want to use some tool like doxypy +(http://code.foosel.org/doxypy) +to do the work. +

    + +

    16.4.2 Pydoc translator

    + + +

    +Here is the list of all Doxygen tags and the description of how they are translated to Pydoc +

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Doxygen tags
    \awrapped with '_'
    \argprepended with ' --'
    \authorprints 'Author:'
    \authorsprints 'Author:'
    \bwrapped with '__'
    \citewrapped with single quotes
    \condtranslated to 'Conditional comment: <condition>'
    \copyrightprints 'Copyright:'
    \deprecatedprints 'Deprecated:'
    \ewrapped with '_'
    \elsereplaced with '}Else:{'
    \elseifreplaced with '}Else if: <condition>{'
    \emwrapped with '_'
    \endcondreplaced with 'End of conditional comment.'
    \endifreplaced with '}'
    \exceptionreplaced with 'Throws:'
    \ifreplaced with 'If: <condition> {'
    \ifnotreplaced with 'If not: <condition> {'
    \liprepended with ' --'
    \nreplaced with new line char
    \notereplaced with 'Note:'
    \overloadprints 'This is an overloaded ...' according to Doxygen docs
    \parreplaced with 'Title: ...'
    \paramtranslated to 'Arguments:\n param(type) --description'
    \remarkreplaced with 'Remarks:'
    \remarksreplaced with 'Remarks:'
    \resultreplaced with 'Result:'
    \returnreplaced with 'Result:'
    \returnsreplaced with 'Result:'
    \sareplaced with 'See also:'
    \seereplaced with 'See also:'
    \sincereplaced with 'Since:'
    \throwreplaced with 'Throws:'
    \throwsreplaced wih 'Throws:'
    \todoreplaced with 'TODO:'
    \tparamtranslated to 'Arguments:\n param(type) --description'
    \versionreplaced with 'Version:'
    \warningtranslated to 'Warning:'
    \$prints $ char
    \@prints @ char
    \\prints \ char
    \&prints & char
    \~prints ~ char
    \<prints < char
    \>prints > char
    \#prints # char
    \%prints % char
    \"prints " char
    \.prints . character
    \::prints ::
    +
    + +

    16.4.3 Unsupported tags

    + + +

    +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: +

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Unsupported Doxygen tags
    \addindex\addtogroup\anchor\attention
    \brief\bug\callgraph\callergraph
    \class\copybrief\copydetails\copydoc
    \date\def\defgroup\details
    \dir\dontinclude\dot\dotfile
    \code\endcode\endverbatim\endlink
    \enddot\endhtmlonly\endinternal\endlatexonly
    \endmanonly\endmsc\endrtfonly\endxmlonly
    \enum\example\extends\f$
    \f[\f]\f{\f}
    \file\fn\headerfile\hideinitializer
    \htmlinclude\htmlonly\implements\include
    \image\link\verbatim\p
    \includelineno\ingroup\internal\invariant
    \interface\latexonly\line\mainpage
    \manonly\memberof\msc\mscfile
    \name\namespace\nosubgrouping\package
    \page\paragraph\post\pre
    \private\privatesection\property\protected
    \protectedsection\protocol\public\publicsection
    \ref\related\relates\relatedalso
    \relatesalso\retval\rtfonly\section
    \short\showinitializer\skip\skipline
    \snippet\struct\subpage\subsection
    \subsubsection\tableofcontents\test\typedef
    \union\until\var\verbinclude
    \weakgroup\xmlonly\xrefitem\category
    \c
    +
    + +

    16.4.4 Further details

    + + +

    +TO BE ADDED. +

    + +

    16.5 Developer information

    + + +

    +This section contains information for developers enhancing the Doxygen translator. +

    + +

    16.5.1 Doxygen translator design

    + + +

    +If this functionality is turned on, SWIG places all comments found +into the SWIG parse tree. Nodes contain an additional attribute +called doxygen 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 : +

    +
    +/*! This is describing function Foo
+ \param x some random variable
+ \author Bob
+ \return Foo
+ */
+
    + +

    +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, JavaDocConverter is the Javadoc module class. +

    + +

    16.5.2 Debugging the Doxygen parser and translator

    + + +

    +There are two handy command line switches, that enable lots of +detailed debug information printing. +

    + +
    +  -debug-doxygen-parser     - Display Doxygen parser module debugging information
+  -debug-doxygen-translator - Display Doxygen translator module debugging information
+
    + +

    16.5.3 Tests

    + + +

    +Doxygen tests have been added to the regular SWIG test-suite. +There are a number of tests beginning doxygen_ in the Examples/test-suite sub-directory. +

    + +

    +Like any other SWIG test case, the tests are included in Examples/test-suite/common.mk and can be tested with +commands like make check-test-suite or make check-python-test-suite. +To run them individually, type +make -s <testname>.cpptest in the language-specific sub-directory in +Examples/test-suite directory. For example: +

    + +
    +  Examples/test-suite/java $ make -s doxygen_parsing.cpptest
+
    + +

    +If the test fails, both expected and translated comments are printed to +std out, but also written to files expected.txt +and got.txt. Since it is often difficult to find a single +character difference in several lines of text, we can use some diff +tool, for example: +

    + +
    +  Examples/test-suite/java $ kdiff3 expected.txt got.txt
+
    + + +

    +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. +

    +

    +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 java commentParser <some java package>, +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. +

    +

    +Runtime tests in Python are just plain string comparisons of the __doc__ +properties. +

    + +

    16.6 Extending to other languages

    + + +

    +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. +

    +

    + What is given to the Doxygen Translator +

    +
    +/*! This is describing function Foo
+ \param x some random variable
+ \author Bob
+ \return Foo
+ */
+
    +

    + What is received back by java.cxx +

    +
    +/** This is describing function Foo
+ *
+ * @param x some random variable
+ * @author Bob
+ * @return Foo
+ */
+
    +

    Development of the comment translator itself is simplified by the fact that the Doxygen Translator module can easily include a main function and thus be developed, compiled, and tested independently of SWIG. +

    + + + 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 @@ -

    42 Extending SWIG to support new languages

    +

    43 Extending SWIG to support new languages

    -

    42.4.4 Attribute namespaces

    +

    43.4.4 Attribute namespaces

    @@ -660,7 +660,7 @@ that matches the name of the target language. For example, python:foo perl:foo.

    -

    42.4.5 Symbol Tables

    +

    43.4.5 Symbol Tables

    @@ -751,7 +751,7 @@ example.i:5. Previous declaration is foo_i(int ) -

    42.4.6 The %feature directive

    +

    43.4.6 The %feature directive

    @@ -807,7 +807,7 @@ For example, the exception code above is simply stored without any modifications.

    -

    42.4.7 Code Generation

    +

    43.4.7 Code Generation

    @@ -929,7 +929,7 @@ public : The role of these functions is described shortly.

    -

    42.4.8 SWIG and XML

    +

    43.4.8 SWIG and XML

    @@ -942,7 +942,7 @@ internal data structures, it may be useful to keep XML in the back of your mind as a model.

    -

    42.5 Primitive Data Structures

    +

    43.5 Primitive Data Structures

    @@ -988,7 +988,7 @@ typedef Hash Typetab; -

    42.5.1 Strings

    +

    43.5.1 Strings

    @@ -1129,7 +1129,7 @@ Returns the number of replacements made (if any). -

    42.5.2 Hashes

    +

    43.5.2 Hashes

    @@ -1206,7 +1206,7 @@ Returns the list of hash table keys. -

    42.5.3 Lists

    +

    43.5.3 Lists

    @@ -1295,7 +1295,7 @@ If t is not a standard object, it is assumed to be a char * and is used to create a String object. -

    42.5.4 Common operations

    +

    43.5.4 Common operations

    The following operations are applicable to all datatypes. @@ -1350,7 +1350,7 @@ objects and report errors. Gets the line number associated with x. -

    42.5.5 Iterating over Lists and Hashes

    +

    43.5.5 Iterating over Lists and Hashes

    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)) { -

    42.5.6 I/O

    +

    43.5.6 I/O

    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.

    -

    42.6 Navigating and manipulating parse trees

    +

    43.6 Navigating and manipulating parse trees

    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. -

    42.7 Working with attributes

    +

    43.7 Working with attributes

    @@ -1780,7 +1780,7 @@ the attribute is optional. Swig_restore() must always be called after function. -

    42.8 Type system

    +

    43.8 Type system

    @@ -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.

    -

    42.8.1 String encoding of types

    +

    43.8.1 String encoding of types

    @@ -1890,7 +1890,7 @@ make the final type, the two parts are just joined together using string concatenation.

    -

    42.8.2 Type construction

    +

    43.8.2 Type construction

    @@ -2059,7 +2059,7 @@ Returns the prefix of a type. For example, if ty is ty is unmodified. -

    42.8.3 Type tests

    +

    43.8.3 Type tests

    @@ -2146,7 +2146,7 @@ Checks if ty is a varargs type. Checks if ty is a templatized type. -

    42.8.4 Typedef and inheritance

    +

    43.8.4 Typedef and inheritance

    @@ -2248,7 +2248,7 @@ Fully reduces ty according to typedef rules. Resulting datatype will consist only of primitive typenames. -

    42.8.5 Lvalues

    +

    43.8.5 Lvalues

    @@ -2285,7 +2285,7 @@ Literal y; // type = 'Literal', ltype='p.char' -

    42.8.6 Output functions

    +

    43.8.6 Output functions

    @@ -2347,7 +2347,7 @@ SWIG, but is most commonly associated with type-descriptor objects that appear in wrappers (e.g., SWIGTYPE_p_double). -

    42.9 Parameters

    +

    43.9 Parameters

    @@ -2446,7 +2446,7 @@ included. Used to emit prototypes. Returns the number of required (non-optional) arguments in p. -

    42.10 Writing a Language Module

    +

    43.10 Writing a Language Module

    @@ -2461,7 +2461,7 @@ describes the creation of a minimal Python module. You should be able to extra this to other languages.

    -

    42.10.1 Execution model

    +

    43.10.1 Execution model

    @@ -2471,7 +2471,7 @@ the parsing of command line options, all aspects of code generation are controll different methods of the Language that must be defined by your module.

    -

    42.10.2 Starting out

    +

    43.10.2 Starting out

    @@ -2579,7 +2579,7 @@ that activates your module. For example, swig -python foo.i. The messages from your new module should appear.

    -

    42.10.3 Command line options

    +

    43.10.3 Command line options

    @@ -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.

    -

    42.10.4 Configuration and preprocessing

    +

    43.10.4 Configuration and preprocessing

    @@ -2687,7 +2687,7 @@ an implementation file python.cxx and a configuration file python.swg.

    -

    42.10.5 Entry point to code generation

    +

    43.10.5 Entry point to code generation

    @@ -2745,7 +2745,7 @@ int Python::top(Node *n) { -

    42.10.6 Module I/O and wrapper skeleton

    +

    43.10.6 Module I/O and wrapper skeleton

    @@ -2893,7 +2893,7 @@ functionWrapper : void Shape_y_set(Shape *self, double y) -

    42.10.7 Low-level code generators

    +

    43.10.7 Low-level code generators

    @@ -3047,7 +3047,7 @@ but without the typemaps, there is still work to do.

    -

    42.10.8 Configuration files

    +

    43.10.8 Configuration files

    @@ -3191,7 +3191,7 @@ politely displays the ignoring language message. -

    42.10.9 Runtime support

    +

    43.10.9 Runtime support

    @@ -3200,7 +3200,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g. the SWIG files that implement those functions.

    -

    42.10.10 Standard library files

    +

    43.10.10 Standard library files

    @@ -3219,7 +3219,7 @@ The following are the minimum that are usually supported: Please copy these and modify for any new language.

    -

    42.10.11 User examples

    +

    43.10.11 User examples

    @@ -3248,7 +3248,7 @@ during this process, see the section on .

    -

    42.10.12 Test driven development and the test-suite

    +

    43.10.12 Test driven development and the test-suite

    @@ -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.

    -

    42.10.12.1 Running the test-suite

    +

    43.10.12.1 Running the test-suite

    @@ -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 Examples/test-suite/errors/Makefile.in.

    -

    42.10.13 Documentation

    +

    43.10.13 Documentation

    @@ -3531,7 +3531,7 @@ Some topics that you'll want to be sure to address include: if available. -

    42.10.14 Prerequisites for adding a new language module to the SWIG distribution

    +

    43.10.14 Prerequisites for adding a new language module to the SWIG distribution

    @@ -3588,7 +3588,7 @@ should be added should there be an area not already covered by the existing tests.

    -

    42.10.15 Coding style guidelines

    +

    43.10.15 Coding style guidelines

    @@ -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.

    -

    42.11 Debugging Options

    +

    43.11 Debugging Options

    @@ -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 swig -help.

    -

    42.12 Guide to parse tree nodes

    +

    43.12 Guide to parse tree nodes

    @@ -4047,7 +4047,7 @@ extern "X" { ... } declaration. -

    42.13 Further Development Information

    +

    43.13 Further Development Information

    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 @@ -

    24 SWIG and Go

    +

    25 SWIG and Go

    -

    24.3.1 Go-specific Commandline Options

    +

    25.3.1 Go-specific Commandline Options

    @@ -264,7 +264,7 @@ swig -go -help -

    24.3.2 Generated Wrapper Files

    +

    25.3.2 Generated Wrapper Files

    There are two different approaches to generating wrapper files, @@ -308,7 +308,7 @@ combined with the compiled MODULE.go using go tool pack. -

    24.4 A tour of basic C/C++ wrapping

    +

    25.4 A tour of basic C/C++ wrapping

    @@ -318,7 +318,7 @@ modifications have to occur. This section briefly covers the essential aspects of this wrapping.

    -

    24.4.1 Go Package Name

    +

    25.4.1 Go Package Name

    @@ -328,7 +328,7 @@ directive. You may override this by using SWIG's -package command line option.

    -

    24.4.2 Go Names

    +

    25.4.2 Go Names

    @@ -360,7 +360,7 @@ followed by that name, and the destructor will be named Delete followed by that name.

    -

    24.4.3 Go Constants

    +

    25.4.3 Go Constants

    @@ -368,7 +368,7 @@ C/C++ constants created via #define or the %constant directive become Go constants, declared with a const declaration. -

    24.4.4 Go Enumerations

    +

    25.4.4 Go Enumerations

    @@ -378,7 +378,7 @@ usual). The values of the enumeration will become variables in Go; code should avoid modifying those variables.

    -

    24.4.5 Go Classes

    +

    25.4.5 Go Classes

    @@ -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.

    -

    24.4.5.1 Go Class Memory Management

    +

    25.4.5.1 Go Class Memory Management

    @@ -578,7 +578,7 @@ func (o *GoClassName) Close() { -

    24.4.5.2 Go Class Inheritance

    +

    25.4.5.2 Go Class Inheritance

    @@ -590,7 +590,7 @@ Doing the reverse will require an explicit type assertion, which will be checked dynamically.

    -

    24.4.6 Go Templates

    +

    25.4.6 Go Templates

    @@ -599,7 +599,7 @@ wrappers for a particular template instantation. To do this, use the %template directive. -

    24.4.7 Go Director Classes

    +

    25.4.7 Go Director Classes

    @@ -617,7 +617,7 @@ completely to avoid common pitfalls with directors in Go.

    -

    24.4.7.1 Example C++ code

    +

    25.4.7.1 Example C++ code

    @@ -689,7 +689,7 @@ be found in the end of the guide.

    -

    24.4.7.2 Enable director feature

    +

    25.4.7.2 Enable director feature

    @@ -724,7 +724,7 @@ documentation on directors.

    -

    24.4.7.3 Constructor and destructor

    +

    25.4.7.3 Constructor and destructor

    @@ -777,7 +777,7 @@ embedding.

    -

    24.4.7.4 Override virtual methods

    +

    25.4.7.4 Override virtual methods

    @@ -843,7 +843,7 @@ the Go methods.

    -

    24.4.7.5 Call base methods

    +

    25.4.7.5 Call base methods

    @@ -880,7 +880,7 @@ be found in the end of the guide.

    -

    24.4.7.6 Subclass via embedding

    +

    25.4.7.6 Subclass via embedding

    @@ -948,7 +948,7 @@ class.

    -

    24.4.7.7 Memory management with runtime.SetFinalizer

    +

    25.4.7.7 Memory management with runtime.SetFinalizer

    @@ -1013,7 +1013,7 @@ before using runtime.SetFinalizer to know all of its gotchas.

    -

    24.4.7.8 Complete FooBarGo example class

    +

    25.4.7.8 Complete FooBarGo example class

    @@ -1142,7 +1142,7 @@ SWIG/Examples/go/director/.

    -

    24.4.8 Default Go primitive type mappings

    +

    25.4.8 Default Go primitive type mappings

    @@ -1249,7 +1249,7 @@ that typemap, or add new values, to control how C/C++ types are mapped into Go types.

    -

    24.4.9 Output arguments

    +

    25.4.9 Output arguments

    Because of limitations in the way output arguments are processed in swig, @@ -1302,7 +1302,7 @@ void f(char *output); -

    24.4.10 Adding additional go code

    +

    25.4.10 Adding additional go code

    Often the APIs generated by swig are not very natural in go, especially if @@ -1397,7 +1397,7 @@ func bar() { -

    24.4.11 Go typemaps

    +

    25.4.11 Go typemaps

    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 @@ -

    25 SWIG and Guile

    +

    26 SWIG and Guile

      @@ -48,7 +48,7 @@

      This section details guile-specific support in SWIG. -

      25.1 Supported Guile Versions

      +

      26.1 Supported Guile Versions

      @@ -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. -

      25.2 Meaning of "Module"

      +

      26.2 Meaning of "Module"

      @@ -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". -

      25.3 Old GH Guile API

      +

      26.3 Old GH Guile API

      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. -

      25.4 Linkage

      +

      26.4 Linkage

      @@ -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 linkage. -

      25.4.1 Simple Linkage

      +

      26.4.1 Simple Linkage

      @@ -194,7 +194,7 @@ placed between the define-module form and the SWIG_init via a preprocessor define to avoid symbol clashes. For this case, however, passive linkage is available. -

      25.4.2 Passive Linkage

      +

      26.4.2 Passive Linkage

      Passive linkage is just like simple linkage, but it generates an @@ -204,7 +204,7 @@ package name (see below).

      You should use passive linkage rather than simple linkage when you are using multiple modules. -

      25.4.3 Native Guile Module Linkage

      +

      26.4.3 Native Guile Module Linkage

      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:

    -

    25.4.4 Old Auto-Loading Guile Module Linkage

    +

    26.4.4 Old Auto-Loading Guile Module Linkage

    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. -

    25.4.5 Hobbit4D Linkage

    +

    26.4.5 Hobbit4D Linkage

    @@ -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.

    -

    25.5 Underscore Folding

    +

    26.5 Underscore Folding

    @@ -308,7 +308,7 @@ complained so far. %rename to specify the Guile name of the wrapped functions and variables (see CHANGES). -

    25.6 Typemaps

    +

    26.6 Typemaps

    @@ -400,7 +400,7 @@ constant will appear as a scheme variable. See Features and the %feature directive for info on how to apply the %feature.

    -

    25.7 Representation of pointers as smobs

    +

    26.7 Representation of pointers as smobs

    @@ -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 wrong-type-arg exception is raised. -

    25.7.1 Smobs

    +

    26.7.1 Smobs

    @@ -440,7 +440,7 @@ structure describing this type. If a generated GOOPS module has been loaded, sm the corresponding GOOPS class.

    -

    25.7.2 Garbage Collection

    +

    26.7.2 Garbage Collection

    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 25.8 Native Guile pointers +

    26.8 Native Guile pointers

    In addition to SWIG smob pointers, Guile's native pointer type are accepted as arguments to wrapped SWIG functions. This can be useful for passing pointers to bytevector data to wrapped functions.

    -

    25.9 Exception Handling

    +

    26.9 Exception Handling

    @@ -487,7 +487,7 @@ mapping: The default when not specified here is to use "swig-error". See Lib/exception.i for details. -

    25.10 Procedure documentation

    +

    26.10 Procedure documentation

    If invoked with the command-line option -procdoc @@ -522,7 +522,7 @@ like this: typemap argument doc. See Lib/guile/typemaps.i for details. -

    25.11 Procedures with setters

    +

    26.11 Procedures with setters

    For global variables, SWIG creates a single wrapper procedure @@ -550,7 +550,7 @@ struct members, the procedures (struct-member-get pointer) and (struct-member-set pointer value) are not generated. -

    25.12 GOOPS Proxy Classes

    +

    26.12 GOOPS Proxy Classes

    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 %import "foo.h" before the %inline block.

    -

    25.12.1 Naming Issues

    +

    26.12.1 Naming Issues

    As you can see in the example above, there are potential naming conflicts. The default exported @@ -733,7 +733,7 @@ guile-modules. For example,

    (use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:))) -

    25.12.2 Linking

    +

    26.12.2 Linking

    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 @@ -

    26 SWIG and Java

    +

    27 SWIG and Java

    -

    26.3.3 Global variables

    +

    27.3.3 Global variables

    @@ -816,7 +816,7 @@ extern char *path; // Read-only (due to %immutable) -

    26.3.4 Constants

    +

    27.3.4 Constants

    @@ -956,7 +956,7 @@ Or if you decide this practice isn't so bad and your own class implements ex

    -

    26.3.5 Enumerations

    +

    27.3.5 Enumerations

    @@ -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.

    -

    26.3.5.1 Anonymous enums

    +

    27.3.5.1 Anonymous enums

    @@ -1033,7 +1033,7 @@ As in the case of constants, you can access them through either the module class

    -

    26.3.5.2 Typesafe enums

    +

    27.3.5.2 Typesafe enums

    @@ -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.

    -

    26.3.5.3 Proper Java enums

    +

    27.3.5.3 Proper Java enums

    @@ -1180,7 +1180,7 @@ The additional support methods need not be generated if none of the enum items h Simpler Java enums for enums without initializers section.

    -

    26.3.5.4 Type unsafe enums

    +

    27.3.5.4 Type unsafe enums

    @@ -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.

    -

    26.3.5.5 Simple enums

    +

    27.3.5.5 Simple enums

    @@ -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.

    -

    26.3.6 Pointers

    +

    27.3.6 Pointers

    @@ -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.

    -

    26.3.7 Structures

    +

    27.3.7 Structures

    @@ -1503,7 +1503,7 @@ x.setA(3); // Modify x.a - this is the same as b.f.a -

    26.3.8 C++ classes

    +

    27.3.8 C++ classes

    @@ -1566,7 +1566,7 @@ int bar = Spam.getBar(); -

    26.3.9 C++ inheritance

    +

    27.3.9 C++ inheritance

    @@ -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.

    -

    26.3.10 Pointers, references, arrays and pass by value

    +

    27.3.10 Pointers, references, arrays and pass by value

    @@ -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).

    -

    26.3.10.1 Null pointers

    +

    27.3.10.1 Null pointers

    @@ -1706,7 +1706,7 @@ For spam1 and spam4 above the Java null gets translat The converse also occurs, that is, NULL pointers are translated into null Java objects when returned from a C/C++ function.

    -

    26.3.11 C++ overloaded functions

    +

    27.3.11 C++ overloaded functions

    @@ -1821,7 +1821,7 @@ void spam(unsigned short); // Ignored -

    26.3.12 C++ default arguments

    +

    27.3.12 C++ default arguments

    @@ -1864,7 +1864,7 @@ Further details on default arguments and how to restore this approach are given

    -

    26.3.13 C++ namespaces

    +

    27.3.13 C++ namespaces

    @@ -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 getCPtr method from the default 'protected' to 'public' with the SWIG_JAVABODY_PROXY macro. See Java code typemaps.

    -

    26.3.14 C++ templates

    +

    27.3.14 C++ templates

    @@ -2003,10 +2003,10 @@ Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter.

    -

    26.3.15 C++ Smart Pointers

    +

    27.3.15 C++ Smart Pointers

    -

    26.3.15.1 The shared_ptr Smart Pointer

    +

    27.3.15.1 The shared_ptr Smart Pointer

    @@ -2017,7 +2017,7 @@ in the shared_ptr smart pointer -

    26.3.15.2 Generic Smart Pointers

    +

    27.3.15.2 Generic Smart Pointers

    @@ -2101,7 +2101,7 @@ Foo f = p.__deref__(); // Returns underlying Foo * -

    26.4 Further details on the generated Java classes

    +

    27.4 Further details on the generated Java classes

    @@ -2116,7 +2116,7 @@ Finally enum classes are covered. First, the crucial intermediary JNI class is considered.

    -

    26.4.1 The intermediary JNI class

    +

    27.4.1 The intermediary JNI class

    @@ -2236,7 +2236,7 @@ If name is the same as modulename then the module class name g from modulename to modulenameModule.

    -

    26.4.1.1 The intermediary JNI class pragmas

    +

    27.4.1.1 The intermediary JNI class pragmas

    @@ -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.

    -

    26.4.2 The Java module class

    +

    27.4.2 The Java module class

    @@ -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 Foo can be passed to the egg function, whereas any long can be passed to the egg function in the intermediary JNI class.

    -

    26.4.2.1 The Java module class pragmas

    +

    27.4.2.1 The Java module class pragmas

    @@ -2400,7 +2400,7 @@ See The intermediary JNI class pragmas secti

    -

    26.4.3 Java proxy classes

    +

    27.4.3 Java proxy classes

    @@ -2476,7 +2476,7 @@ int y = f.spam(5, new Foo()); -

    26.4.3.1 Memory management

    +

    27.4.3.1 Memory management

    @@ -2638,7 +2638,7 @@ and

    -

    26.4.3.2 Inheritance

    +

    27.4.3.2 Inheritance

    @@ -2754,7 +2754,7 @@ However, true cross language polymorphism can be achieved using the 26.4.3.3 Proxy classes and garbage collection +

    27.4.3.3 Proxy classes and garbage collection

    @@ -2837,7 +2837,7 @@ The section on Java typemaps details how to specify See the How to Handle Java Finalization's Memory-Retention Issues article for alternative approaches to managing memory by avoiding finalizers altogether.

    -

    26.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling

    +

    27.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling

    @@ -2959,7 +2959,7 @@ For example: Compatibility note: The generation of this additional parameter did not occur in versions prior to SWIG-1.3.30.

    -

    26.4.3.5 Single threaded applications and thread safety

    +

    27.4.3.5 Single threaded applications and thread safety

    @@ -3047,7 +3047,7 @@ for (int i=0; i<100000; i++) { -

    26.4.4 Type wrapper classes

    +

    27.4.4 Type wrapper classes

    @@ -3134,7 +3134,7 @@ public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... } -

    26.4.5 Enum classes

    +

    27.4.5 Enum classes

    @@ -3143,7 +3143,7 @@ The Enumerations section discussed these but om The following sub-sections detail the various types of enum classes that can be generated.

    -

    26.4.5.1 Typesafe enum classes

    +

    27.4.5.1 Typesafe enum classes

    @@ -3227,7 +3227,7 @@ The swigValue method is used for marshalling in the other direction. The toString method is overridden so that the enum name is available.

    -

    26.4.5.2 Proper Java enum classes

    +

    27.4.5.2 Proper Java enum classes

    @@ -3305,7 +3305,7 @@ These needn't be generated if the enum being wrapped does not have any initializ Simpler Java enums for enums without initializers section describes how typemaps can be used to achieve this.

    -

    26.4.5.3 Type unsafe enum classes

    +

    27.4.5.3 Type unsafe enum classes

    @@ -3336,7 +3336,7 @@ public final class Beverage { -

    26.4.6 Interfaces

    +

    27.4.6 Interfaces

    @@ -3581,7 +3581,7 @@ typemap which is only used when a class is marked with the interface fe See Java code typemaps for details.

    -

    26.5 Cross language polymorphism using directors

    +

    27.5 Cross language polymorphism using directors

    @@ -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.

    -

    26.5.1 Enabling directors

    +

    27.5.1 Enabling directors

    @@ -3671,7 +3671,7 @@ public: -

    26.5.2 Director classes

    +

    27.5.2 Director classes

    @@ -3698,7 +3698,7 @@ If the correct implementation is in Java, the Java API is used to call the metho

    -

    26.5.3 Overhead and code bloat

    +

    27.5.3 Overhead and code bloat

    @@ -3716,7 +3716,7 @@ This situation can be optimized by selectively enabling director methods (using

    -

    26.5.4 Simple directors example

    +

    27.5.4 Simple directors example

    @@ -3779,7 +3779,7 @@ DirectorDerived.upcall_method() invoked. -

    26.5.5 Director threading issues

    +

    27.5.5 Director threading issues

    @@ -3799,7 +3799,7 @@ Macros can be defined on the commandline when compiling your C++ code, or altern -

    26.5.6 Director performance tuning

    +

    27.5.6 Director performance tuning

    @@ -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.

    -

    26.5.7 Java exceptions from directors

    +

    27.5.7 Java exceptions from directors

    @@ -3896,7 +3896,7 @@ Exception in thread "main" java.lang.RuntimeException: There was a problem! More on the Swig::DirectorException class can be found in the next section which details how to customize the handling of director exceptions.

    -

    26.5.7.1 Customizing director exceptions

    +

    27.5.7.1 Customizing director exceptions

    @@ -4454,7 +4454,7 @@ Exception in thread "main" java.lang.IndexOutOfBoundsException: Index is negativ -

    26.6 Accessing protected members

    +

    27.6 Accessing protected members

    @@ -4550,7 +4550,7 @@ class MyProtectedBase extends ProtectedBase -

    26.7 Common customization features

    +

    27.7 Common customization features

    @@ -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.

    -

    26.7.1 C/C++ helper functions

    +

    27.7.1 C/C++ helper functions

    @@ -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.

    -

    26.7.2 Class extension with %extend

    +

    27.7.2 Class extension with %extend

    @@ -4691,7 +4691,7 @@ Vector(2, 3, 4) in any way---the extensions only show up in the Java interface.

    -

    26.7.3 Class extension with %proxycode

    +

    27.7.3 Class extension with %proxycode

    @@ -4828,7 +4828,7 @@ public class ValueUnsignedInt { -

    26.7.4 Exception handling with %exception and %javaexception

    +

    27.7.4 Exception handling with %exception and %javaexception

    @@ -4987,7 +4987,7 @@ to raise exceptions. See the SWIG Library ch The typemap example Handling C++ exception specifications as Java exceptions provides further exception handling capabilities.

    -

    26.7.5 Method access with %javamethodmodifiers

    +

    27.7.5 Method access with %javamethodmodifiers

    @@ -5013,7 +5013,7 @@ protected static void protect_me() { -

    26.8 Tips and techniques

    +

    27.8 Tips and techniques

    @@ -5023,7 +5023,7 @@ strings and arrays. This chapter discusses the common techniques for solving these problems.

    -

    26.8.1 Input and output parameters using primitive pointers and references

    +

    27.8.1 Input and output parameters using primitive pointers and references

    @@ -5197,7 +5197,7 @@ void foo(Bar *OUTPUT); will not have the intended effect since typemaps.i does not define an OUTPUT rule for Bar.

    -

    26.8.2 Simple pointers

    +

    27.8.2 Simple pointers

    @@ -5263,7 +5263,7 @@ System.out.println("3 + 4 = " + result); See the SWIG Library chapter for further details.

    -

    26.8.3 Wrapping C arrays with Java arrays

    +

    27.8.3 Wrapping C arrays with Java arrays

    @@ -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.

    -

    26.8.4 Unbounded C Arrays

    +

    27.8.4 Unbounded C Arrays

    @@ -5475,7 +5475,7 @@ well suited for applications in which you need to create buffers, package binary data, etc.

    -

    26.8.5 Binary data vs Strings

    +

    27.8.5 Binary data vs Strings

    @@ -5519,7 +5519,7 @@ len: 5 data: 68 69 0 6a 6b -

    26.8.6 Overriding new and delete to allocate from Java heap

    +

    27.8.6 Overriding new and delete to allocate from Java heap

    @@ -5636,7 +5636,7 @@ model and use these functions in place of malloc and free in your own code.

    -

    26.9 Java typemaps

    +

    27.9 Java typemaps

    @@ -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. -

    26.9.1 Default primitive type mappings

    +

    27.9.1 Default primitive type mappings

    @@ -5809,7 +5809,7 @@ However, the mappings allow the full range of values for each C type from Java.

    -

    26.9.2 Default typemaps for non-primitive types

    +

    27.9.2 Default typemaps for non-primitive types

    @@ -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.

    -

    26.9.3 Sixty four bit JVMs

    +

    27.9.3 Sixty four bit JVMs

    @@ -5837,7 +5837,7 @@ Unfortunately it won't of course hold true for JNI code.

    -

    26.9.4 What is a typemap?

    +

    27.9.4 What is a typemap?

    @@ -5960,7 +5960,7 @@ int c = example.count('e', "Hello World"); -

    26.9.5 Typemaps for mapping C/C++ types to Java types

    +

    27.9.5 Typemaps for mapping C/C++ types to Java types

    @@ -6240,7 +6240,7 @@ These are listed below: -

    26.9.6 Java typemap attributes

    +

    27.9.6 Java typemap attributes

    @@ -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 this call. In Java the this 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 Date marshalling example showing 'pre', 'post' and 'pgcppname' attributes in action.

    -

    26.9.7 Java special variables

    +

    27.9.7 Java special variables

    @@ -6468,7 +6468,7 @@ in that it is not fully qualified with the package name when using the nspace feature.

    -

    26.9.8 Typemaps for both C and C++ compilation

    +

    27.9.8 Typemaps for both C and C++ compilation

    @@ -6505,7 +6505,7 @@ If you do not intend your code to be targeting both C and C++ then your typemaps

    -

    26.9.9 Java code typemaps

    +

    27.9.9 Java code typemaps

    @@ -6801,7 +6801,7 @@ to make the method and constructor public: -

    26.9.10 Director specific typemaps

    +

    27.9.10 Director specific typemaps

    @@ -7078,7 +7078,7 @@ The basic strategy here is to provide a default package typemap for the majority -

    26.10 Typemap Examples

    +

    27.10 Typemap Examples

    @@ -7088,7 +7088,7 @@ the SWIG library.

    -

    26.10.1 Simpler Java enums for enums without initializers

    +

    27.10.1 Simpler Java enums for enums without initializers

    @@ -7167,7 +7167,7 @@ This would be done by using the original versions of these typemaps in "enums.sw

    -

    26.10.2 Handling C++ exception specifications as Java exceptions

    +

    27.10.2 Handling C++ exception specifications as Java exceptions

    @@ -7292,7 +7292,7 @@ We could alternatively have used %rename to rename what() into

    -

    26.10.3 NaN Exception - exception handling for a particular type

    +

    27.10.3 NaN Exception - exception handling for a particular type

    @@ -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.

    -

    26.10.4 Converting Java String arrays to char **

    +

    27.10.4 Converting Java String arrays to char **

    @@ -7591,7 +7591,7 @@ Lastly the "jni", "jtype" and "jstype" typemaps are also required to specify what Java types to use.

    -

    26.10.5 Expanding a Java object to multiple arguments

    +

    27.10.5 Expanding a Java object to multiple arguments

    @@ -7673,7 +7673,7 @@ example.foo(new String[]{"red", "green", "blue", "white"}); -

    26.10.6 Using typemaps to return arguments

    +

    27.10.6 Using typemaps to return arguments

    @@ -7791,7 +7791,7 @@ $ java runme 1 12.0 340.0 -

    26.10.7 Adding Java downcasts to polymorphic return types

    +

    27.10.7 Adding Java downcasts to polymorphic return types

    @@ -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.

    -

    26.10.8 Adding an equals method to the Java classes

    +

    27.10.8 Adding an equals method to the Java classes

    @@ -8041,7 +8041,7 @@ System.out.println("foo1? " + foo1.equals(foo2)); -

    26.10.9 Void pointers and a common Java base class

    +

    27.10.9 Void pointers and a common Java base class

    @@ -8100,7 +8100,7 @@ This example contains some useful functionality which you may want in your code.

  • 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. -

    26.10.10 Struct pointer to pointer

    +

    27.10.10 Struct pointer to pointer

    @@ -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.

    -

    26.10.11 Memory management when returning references to member variables

    +

    27.10.11 Memory management when returning references to member variables

    @@ -8403,7 +8403,7 @@ public class Bike { Note the addReference call.

    -

    26.10.12 Memory management for objects passed to the C++ layer

    +

    27.10.12 Memory management for objects passed to the C++ layer

    @@ -8531,7 +8531,7 @@ as mentioned earlier, setElement is actually: -

    26.10.13 Date marshalling using the javain typemap and associated attributes

    +

    27.10.13 Date marshalling using the javain typemap and associated attributes

    @@ -8708,7 +8708,7 @@ A few things to note: -

    26.11 Living with Java Directors

    +

    27.11 Living with Java Directors

    @@ -8887,10 +8887,10 @@ public abstract class UserVisibleFoo extends Foo {

    • -

    26.12 Odds and ends

    +

    27.12 Odds and ends

    -

    26.12.1 JavaDoc comments

    +

    27.12.1 JavaDoc comments

    @@ -8946,7 +8946,7 @@ public class Barmy { -

    26.12.2 Functional interface without proxy classes

    +

    27.12.2 Functional interface without proxy classes

    @@ -9007,7 +9007,7 @@ All destructors have to be called manually for example the delete_Foo(foo) -

    26.12.3 Using your own JNI functions

    +

    27.12.3 Using your own JNI functions

    @@ -9057,7 +9057,7 @@ This directive is only really useful if you want to mix your own hand crafted JN

    -

    26.12.4 Performance concerns and hints

    +

    27.12.4 Performance concerns and hints

    @@ -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 free() for C code.

    -

    26.12.5 Debugging

    +

    27.12.5 Debugging

    @@ -9100,7 +9100,7 @@ The -verbose:jni and -verbose:gc are also useful options for monitoring code beh

    -

    26.13 Java Examples

    +

    27.13 Java Examples

    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 @@ -

    27 SWIG and Javascript

    +

    28 SWIG and Javascript

      @@ -52,7 +52,7 @@

      This chapter describes SWIG's support of Javascript. It does not cover SWIG basics, but only information that is specific to this module.

      -

      27.1 Overview

      +

      28.1 Overview

      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 node-webkit there is a platform which uses Google's Chromium as Web-Browser widget and node.js for javascript extensions.

      -

      27.2 Preliminaries

      +

      28.2 Preliminaries

      -

      27.2.1 Running SWIG

      +

      28.2.1 Running SWIG

      Suppose that you defined a SWIG module such as the following:

      @@ -121,7 +121,7 @@ void example_initialize(v8::Handle<v8::Object> exports) Note: be aware that v8 has a C++ API, and thus, the generated modules must be compiled as C++.

      -

      27.2.2 Running Tests and Examples

      +

      28.2.2 Running Tests and Examples

      The configuration for tests and examples currently supports Linux and Mac only and not MinGW (Windows) yet.

      @@ -153,7 +153,7 @@ $ make check-javascript-test-suite ENGINE=jsc $ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8
    -

    27.2.3 Known Issues

    +

    28.2.3 Known Issues

    At the moment, the Javascript generators pass all tests syntactically, i.e., the generated source code compiles. However, there are still remaining runtime issues.

    @@ -170,12 +170,12 @@ $ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8

    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.

    -

    27.3 Integration

    +

    28.3 Integration

    This chapter gives a short introduction how to use a native Javascript extension: as a node.js module, and as an extension for an embedded Webkit.

    -

    27.3.1 Creating node.js Extensions

    +

    28.3.1 Creating node.js Extensions

    To install node.js you can download an installer from their web-site for Mac OS X and Windows. For Linux you can either build the source yourself and run sudo checkinstall or keep to the (probably stone-age) packaged version. For Ubuntu there is a PPA available.

    @@ -221,7 +221,7 @@ require("./build/Release/example")

    A more detailed explanation is given in the Examples section.

    -

    27.3.1.1 Troubleshooting

    +

    28.3.1.1 Troubleshooting

      @@ -233,12 +233,12 @@ require("./build/Release/example") $ sudo apt-get remove gyp -

      27.3.2 Embedded Webkit

      +

      28.3.2 Embedded Webkit

      Webkit is pre-installed on Mac OS X and available as a library for GTK.

      -

      27.3.2.1 Mac OS X

      +

      28.3.2.1 Mac OS X

      There is general information about programming with WebKit on Apple Developer Documentation. Details about Cocoa programming are not covered here.

      @@ -286,7 +286,7 @@ extern bool example_initialize(JSGlobalContextRef context, JSObjectRef* exports) @end -

      27.3.2.2 GTK

      +

      28.3.2.2 GTK

      There is general information about programming GTK at GTK documentation and in the GTK tutorial, and for Webkit there is a Webkit GTK+ API Reference.

      @@ -331,7 +331,7 @@ int main(int argc, char* argv[]) } -

      27.3.3 Creating Applications with node-webkit

      +

      28.3.3 Creating Applications with node-webkit

      To get started with node-webkit there is a very informative set of wiki pages.

      @@ -422,12 +422,12 @@ open new windows, and many more things. }; -

      27.4 Examples

      +

      28.4 Examples

      Some basic examples are shown here in more detail.

      -

      27.4.1 Simple

      +

      28.4.1 Simple

      The common example simple looks like this:

      @@ -477,7 +477,7 @@ example.Foo = 3.1415926;

      Note: ECMAScript 5, the currently implemented Javascript standard, does not have modules. node.js and other implementations provide this mechanism defined by the CommonJS group. For browsers this is provided by Browserify, for instance.

      -

      27.4.2 Class

      +

      28.4.2 Class

      The common example class defines three classes, Shape, Circle, and Square:

      @@ -607,12 +607,12 @@ at emitKey (readline.js:1095:12) Note: 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 prototype 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 Inheritance and the prototype chain, for instance.

      -

      27.5 Implementation

      +

      28.5 Implementation

      The Javascript Module implementation has taken a very different approach compared to other language modules in order to support different Javascript interpreters.

      -

      27.5.1 Source Code

      +

      28.5.1 Source Code

      The Javascript module is implemented in Source/Modules/javascript.cxx. It dispatches the code generation to a JSEmitter instance, V8Emitter or JSCEmitter. Additionally there are some helpers: Template, for templated code generation, and JSEmitterState, 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:

      @@ -713,7 +713,7 @@ Template::Template(const String *code_) { ... } ... -

      27.5.2 Code Templates

      +

      28.5.2 Code Templates

      All generated code is created on the basis of code templates. The templates for JavascriptCore can be found in Lib/javascript/jsc/javascriptcode.swg, for v8 in Lib/javascript/v8/javascriptcode.swg.

      @@ -752,7 +752,7 @@ t_register.replace("$jsparent", state.clazz(NAME_MANGLED))

      Template creates a copy of that string and Template::replace uses Swig's Replaceall to replace variables in the template. Template::trim can be used to eliminate leading and trailing whitespaces. Template::print is used to write the final template string to a Swig DOH (based on Printv). All methods allow chaining.

      -

      27.5.3 Emitter

      +

      28.5.3 Emitter

      The Javascript module delegates code generation to a JSEmitter instance. The following extract shows the essential interface:

      @@ -871,7 +871,7 @@ int JAVASCRIPT::classHandler(Node *n) {

      In enterClass the emitter stores state information that is necessary when processing class members. In exitClass the wrapper code for the whole class is generated.

      -

      27.5.4 Emitter states

      +

      28.5.4 Emitter states

      For storing information during the AST traversal the emitter provides a JSEmitterState with different slots to store data representing the scopes global, class, function, and variable.

      @@ -915,7 +915,7 @@ state.clazz(NAME, Getattr(n, "sym:name"));

      State information can be retrieved using state.clazz(NAME) or with Getattr on state.clazz() which actually returns a Hash instance.

      -

      27.5.5 Handling Exceptions in JavascriptCore

      +

      28.5.5 Handling Exceptions in JavascriptCore

      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.

      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 @@ -

      28 SWIG and Common Lisp

      +

      29 SWIG and Common Lisp

      -

      28.2.3 Generating CFFI bindings for C++ code

      +

      29.2.3 Generating CFFI bindings for C++ code

      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. -

      28.2.4 Inserting user code into generated files

      +

      29.2.4 Inserting user code into generated files

      @@ -622,7 +622,7 @@ Note that the block %{ ... %} is effectively a shortcut for

      -

      28.3 CLISP

      +

      29.3 CLISP

      @@ -652,7 +652,7 @@ swig -clisp -module module-name file-name interface file for the CLISP module. The CLISP module tries to produce code which is both human readable and easily modifiable.

      -

      28.3.1 Additional Commandline Options

      +

      29.3.1 Additional Commandline Options

      @@ -685,7 +685,7 @@ shortcuts according to the typedefs in the input. -

      28.3.2 Details on CLISP bindings

      +

      29.3.2 Details on CLISP bindings

      @@ -809,7 +809,7 @@ struct bar { -

      28.4 UFFI

      +

      29.4 UFFI

      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 @@ -

      29 SWIG and Lua

      +

      30 SWIG and Lua

        @@ -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: http://www.eluaproject.net

        -

        29.1 Preliminaries

        +

        30.1 Preliminaries

        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'.

        -

        29.2 Running SWIG

        +

        30.2 Running SWIG

        @@ -138,7 +138,7 @@ $ swig -lua -eluac example.i The -elua 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 -eluac 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 -eluac. To access any value from eLua, one must directly call the wrapper function associated with that value.

        -

        29.2.1 Additional command line options

        +

        30.2.1 Additional command line options

        @@ -179,7 +179,7 @@ swig -lua -help -

        29.2.2 Compiling and Linking and Interpreter

        +

        30.2.2 Compiling and Linking and Interpreter

        @@ -250,7 +250,7 @@ LUALIB_API int ( luaopen_mod )(lua_State *L ); More information on building and configuring eLua can be found here: http://www.eluaproject.net/doc/v0.8/en_building.html

        -

        29.2.3 Compiling a dynamic module

        +

        30.2.3 Compiling a dynamic module

        @@ -318,7 +318,7 @@ Is quite obvious (Go back and consult the Lua documents on how to enable loadlib -

        29.2.4 Using your module

        +

        30.2.4 Using your module

        @@ -336,19 +336,19 @@ $ ./my_lua >

      -

      29.3 A tour of basic C/C++ wrapping

      +

      30.3 A tour of basic C/C++ wrapping

      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.

      -

      29.3.1 Modules

      +

      30.3.1 Modules

      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.

      -

      29.3.2 Functions

      +

      30.3.2 Functions

      @@ -389,7 +389,7 @@ It is also possible to rename the module with an assignment. 24 -

      29.3.3 Global variables

      +

      30.3.3 Global variables

      @@ -477,7 +477,7 @@ If you have used the -eluac option for your eLua module, you will have In general, functions of the form "variable_get()" and "variable_set()" are automatically generated by SWIG for use with -eluac.

      -

      29.3.4 Constants and enums

      +

      30.3.4 Constants and enums

      @@ -512,7 +512,7 @@ If you're using eLua and have used -elua or -eluac to generate Hello World -

      29.3.4.1 Constants/enums and classes/structures

      +

      30.3.4.1 Constants/enums and classes/structures

      @@ -568,7 +568,7 @@ If the -no-old-metatable-bindings option is used, then these old-style It is worth mentioning, that example.Test.TEST1 and example.Test_TEST1 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.

      -

      29.3.5 Pointers

      +

      30.3.5 Pointers

      @@ -606,7 +606,7 @@ Lua enforces the integrity of its userdata, so it is virtually impossible to cor nil -

      29.3.6 Structures

      +

      30.3.6 Structures

      @@ -710,7 +710,7 @@ For eLua with the -eluac option, structure manipulation has to be perfo In general, functions of the form "new_struct()", "struct_member_get()", "struct_member_set()" and "free_struct()" are automatically generated by SWIG for each structure defined in C. (Please note: This doesn't apply for modules generated with the -elua option)

      -

      29.3.7 C++ classes

      +

      30.3.7 C++ classes

      @@ -785,7 +785,7 @@ Both style names are generated by default now. However, if the -no-old-metatable-bindings option is used, then the backward compatible names are not generated in addition to ordinary ones.

      -

      29.3.8 C++ inheritance

      +

      30.3.8 C++ inheritance

      @@ -810,7 +810,7 @@ then the function spam() accepts a Foo pointer or a pointer to any clas

      It is safe to use multiple inheritance with SWIG.

      -

      29.3.9 Pointers, references, values, and arrays

      +

      30.3.9 Pointers, references, values, and arrays

      @@ -841,7 +841,7 @@ Foo spam7();

      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.

      -

      29.3.10 C++ overloaded functions

      +

      30.3.10 C++ overloaded functions

      @@ -927,7 +927,7 @@ Please refer to the "SWIG and C++" chapter for more information about overloadin

      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.

      -

      29.3.11 C++ operators

      +

      30.3.11 C++ operators

      @@ -1059,7 +1059,7 @@ operators and pseudo-operators):

    No other lua metafunction is inherited. For example, __gc is not inherited and must be redefined in every class. __tostring is subject to a special handling. If absent in class and in class bases, a default one will be provided by SWIG.

    -

    29.3.12 Class extension with %extend

    +

    30.3.12 Class extension with %extend

    @@ -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).

    -

    29.3.13 Using %newobject to release memory

    +

    30.3.13 Using %newobject to release memory

    If you have a function that allocates memory like this,

    @@ -1140,7 +1140,7 @@ char *foo();

    This will release the allocated memory.

    -

    29.3.14 C++ templates

    +

    30.3.14 C++ templates

    @@ -1175,7 +1175,7 @@ In Lua:

    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.

    -

    29.3.15 C++ Smart Pointers

    +

    30.3.15 C++ Smart Pointers

    @@ -1227,7 +1227,7 @@ If you ever need to access the underlying pointer returned by operator->( > f = p:__deref__() -- Returns underlying Foo * -

    29.3.16 C++ Exceptions

    +

    30.3.16 C++ Exceptions

    @@ -1370,7 +1370,7 @@ and the "Exception handling add exception specification to functions or globally (respectively).

    -

    29.3.17 Namespaces

    +

    30.3.17 Namespaces

    @@ -1421,7 +1421,7 @@ Now, from Lua usage is as follows: 19 > -

    29.3.17.1 Compatibility Note

    +

    30.3.17.1 Compatibility Note

    @@ -1437,7 +1437,7 @@ If SWIG is running in a backwards compatible way, i.e. without the -no-old-m -

    29.3.17.2 Names

    +

    30.3.17.2 Names

    If SWIG is launched without -no-old-metatable-bindings 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 > -

    29.3.17.3 Inheritance

    +

    30.3.17.3 Inheritance

    The internal organization of inheritance has changed. @@ -1522,12 +1522,12 @@ function > -

    29.4 Typemaps

    +

    30.4 Typemaps

    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

    -

    29.4.1 What is a typemap?

    +

    30.4.1 What is a typemap?

    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:

    @@ -1555,7 +1555,7 @@ Received an integer : 6 720 -

    29.4.2 Using typemaps

    +

    30.4.2 Using typemaps

    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.

    @@ -1608,7 +1608,7 @@ void swap(int *sx, int *sy);

    Note: C++ references must be handled exactly the same way. However SWIG will automatically wrap a const int& as an input parameter (since that it obviously input).

    -

    29.4.3 Typemaps and arrays

    +

    30.4.3 Typemaps and arrays

    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

    Note: SWIG also can support arrays of pointers in a similar manner.

    -

    29.4.4 Typemaps and pointer-pointer functions

    +

    30.4.4 Typemaps and pointer-pointer functions

    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:

    @@ -1706,7 +1706,7 @@ int Create_Math(iMath** pptr); // its creator (assume it mallocs) ptr=nil -- the iMath* will be GC'ed as normal -

    29.5 Writing typemaps

    +

    30.5 Writing typemaps

    This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the %typemap directive. This is an advanced topic that assumes familiarity with the Lua C API as well as the material in the "Typemaps" chapter.

    @@ -1715,7 +1715,7 @@ ptr=nil -- the iMath* will be GC'ed as normal

    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).

    -

    29.5.1 Typemaps you can write

    +

    30.5.1 Typemaps you can write

    There are many different types of typemap that can be written, the full list can be found in the "Typemaps" chapter. However the following are the most commonly used ones.

    @@ -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). -

    29.5.2 SWIG's Lua-C API

    +

    30.5.2 SWIG's Lua-C API

    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.

    @@ -1777,7 +1777,7 @@ This macro, when called within the context of a SWIG wrapped function, will disp
    Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.
    -

    29.6 Customization of your Bindings

    +

    30.6 Customization of your Bindings

    @@ -1786,7 +1786,7 @@ This section covers adding of some small extra bits to your module to add the la -

    29.6.1 Writing your own custom wrappers

    +

    30.6.1 Writing your own custom wrappers

    @@ -1805,7 +1805,7 @@ int native_function(lua_State*L) // my native code The %native directive in the above example, tells SWIG that there is a function int native_function(lua_State*L); which is to be added into the module under the name 'my_func'. 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.

    -

    29.6.2 Adding additional Lua code

    +

    30.6.2 Adding additional Lua code

    @@ -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.

    -

    29.7 Details on the Lua binding

    +

    30.7 Details on the Lua binding

    @@ -1854,7 +1854,7 @@ See Examples/lua/arrays for an example of this code.

    -

    29.7.1 Binding global data into the module.

    +

    30.7.1 Binding global data into the module.

    @@ -1914,7 +1914,7 @@ end

    That way when you call 'a=example.Foo', 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 'example.Foo=10', 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)'.

    -

    29.7.2 Userdata and Metatables

    +

    30.7.2 Userdata and Metatables

    @@ -1994,7 +1994,7 @@ Note: Both the opaque structures (like the FILE*) and normal wrapped classes/str

    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.

    -

    29.7.3 Memory management

    +

    30.7.3 Memory management

    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 @@ -

    30 SWIG and Modula-3

    +

    31 SWIG and Modula-3

    -

    30.4.5 Exceptions

    +

    31.4.5 Exceptions

    @@ -817,7 +817,7 @@ you should declare %typemap("m3wrapinconv:throws") blah * %{OSError.E%}.

    -

    30.4.6 Example

    +

    31.4.6 Example

    @@ -864,10 +864,10 @@ where almost everything is generated by a typemap: -

    30.5 More hints to the generator

    +

    31.5 More hints to the generator

    -

    30.5.1 Features

    +

    31.5.1 Features

    @@ -904,7 +904,7 @@ where almost everything is generated by a typemap:
    -

    30.5.2 Pragmas

    +

    31.5.2 Pragmas

    @@ -927,7 +927,7 @@ where almost everything is generated by a typemap:
    -

    30.6 Remarks

    +

    31.6 Remarks

    -

    40.4.5 STL

    +

    41.4.5 STL

    @@ -1982,7 +1982,7 @@ ans = --> delete_PersonPtrSet(p); -

    40.5 Module initialization

    +

    41.5 Module initialization

    @@ -2006,7 +2006,7 @@ For example, to initialize the module example: --> example_Init(); -

    40.6 Building modes

    +

    41.6 Building modes

    @@ -2021,7 +2021,7 @@ To produce a dynamic module, when generating the wrapper, there are two possibil

  • the builder mode. In this mode, Scilab is responsible of building. -

    40.6.1 No-builder mode

    +

    41.6.1 No-builder mode

    @@ -2034,7 +2034,7 @@ This mode is the best option to use when you have to integrate the module build

    -

    40.6.2 Builder mode

    +

    41.6.2 Builder mode

    @@ -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 -

    40.7 Generated scripts

    +

    41.7 Generated scripts

    In this part we give some details about the generated Scilab scripts.

    -

    40.7.1 Builder script

    +

    41.7.1 Builder script

    @@ -2106,7 +2106,7 @@ ilib_build(ilib_name, table, files, libs);

  • table: two column string matrix containing a table of pairs of 'scilab function name', 'C function name'.
    • -

    40.7.2 Loader script

    +

    41.7.2 Loader script

    @@ -2145,7 +2145,7 @@ clear get_file_path; -

    40.8 Other resources

    +

    41.8 Other resources