update docs

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@6977 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Doc/Manual/Python.html

@@ -239,8 +239,8 @@ using comands like this (shown for Linux):
 
 <blockquote><pre>
 $ swig -python example.i
-$ gcc -c example.c
+$ gcc -c -fPIC example.c
-$ gcc -c example_wrap.c -I/usr/local/include/python2.0
+$ gcc -c -fPIC example_wrap.c -I/usr/local/include/python2.0
 $ gcc -shared example.o example_wrap.o -o _example.so
 </pre></blockquote>
 
@@ -1502,6 +1502,8 @@ public:
   Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { }
   Complex(const Complex &amp;c) : rpart(c.rpart), ipart(c.ipart) { }
   Complex &amp;operator=(const Complex &amp;c);
+
+  Complex operator+=(const Complex &amp;c) const;
   Complex operator+(const Complex &amp;c) const;
   Complex operator-(const Complex &amp;c) const;
   Complex operator*(const Complex &amp;c) const;
@@ -1524,6 +1526,12 @@ When wrapped, it works like you expect:
 10.0
 &gt;&gt;&gt; e.im()
 12.0
+&gt;&gt;&gt; c += d
+&gt;&gt;&gt; c.re()
+10.0
+&gt;&gt;&gt; c.im()
+12.0
+
 </pre>
 </blockquote>
 
@@ -1541,15 +1549,12 @@ friend Complex operator+(double, const Complex &amp;c);
 </pre>
 </blockquote>
 
-then SWIG doesn't know what to do with the friend function--in fact,
+then SWIG ignores it and issues a warning.   You can still wrap the operator,
-it simply ignores it and issues a warning.   You can still wrap the operator,
 but you may have to encapsulate it in a special function.  For example:
 
 <blockquote>
 <pre>
 %rename(Complex_add_dc) operator+(double, const Complex &amp;);
-...
-Complex operator+(double, const Complex &amp;c);
 </pre>
 </blockquote>
 
@@ -2376,29 +2381,67 @@ Python.
 Typemaps for input and output of most of the basic types from director
 classes have been written. These are roughly the reverse of the usual
 input and output typemaps used by the wrapper code. The typemap
-operation names are 'directorin', 'directorout', and 'directorargout'. The director code does
+operation names are 'directorin', 'directorout', and 'directorargout'.
-not use any of the other kinds of typemaps yet. It is not clear at this
+The director code does not use any of the other kinds of typemaps
-point which kinds are appropriate and need to be supported. 
+yet. It is not clear at this point which kinds are appropriate and
+need to be supported.
+</p>
+
+
+<H3><a name="Python_nn39"></a>26.5.7 Miscellaneous</H3>
+
+<p>
+Director typemaps for STL classes are in place, and hence you should
+be able to use std::vector, std::string, etc., as any other raw type.
 </p>
 
 <p>
-Typemaps for STL classes are under construction. So far there is support
+<b>Note:</b> The director typemaps for return types based in const
-for std::string, std::vector, and std::complex, although there's no
+references, such as 
-guarantee these are fully functional yet. 
-</p>
 
-<H3><a name="Python_nn39"></a>26.5.7 Miscellaneous</H3>
+<blockquote>
+<pre>
+class Foo {
+&hellip;
+    virtual const int& bar();
+&hellip;
+};
+</pre>
+</blockquote>
+
+will work only for simple call scenarios. Usually the resulting code
+is neither thread or reentrant safe. Hence, the user is adviced to
+avoid returning const reference in director methods. For example,
+the user could modify the method interface to use a lvalue return
+types, when possible, i.e.
+
+<blockquote>
+<pre>
+class Foo {
+&hellip;
+    virtual int bar();
+&hellip;
+};
+</pre>
+</blockquote>
+
+If that is not possible, the user should avoid to enable the
+director feature for reentrant, recursive or threaded member
+methods that return const references.
+
+</p>
 
 
 <H2><a name="Python_nn40"></a>26.6 Common customization features</H2>
 
 
-The last section presented the absolute basics of C/C++ wrapping. If you do nothing
+The last section presented the absolute basics of C/C++ wrapping. If
-but feed SWIG a header file, you will get an interface that mimics the behavior
+you do nothing but feed SWIG a header file, you will get an interface
-described.  However, sometimes this isn't enough to produce a nice module.  Certain
+that mimics the behavior described.  However, sometimes this isn't
-types of functionality might be missing or the interface to certain functions might
+enough to produce a nice module.  Certain types of functionality might
-be awkward.  This section describes some common SWIG features that are used
+be missing or the interface to certain functions might be awkward.
-to improve your the interface to an extension module.
+This section describes some common SWIG features that are used to
+improve your the interface to an extension module.
 
 <H3><a name="Python_nn41"></a>26.6.1 C/C++ helper functions</H3>
 
@@ -3220,21 +3263,22 @@ like this:
 </pre>
 </blockquote>
 
-A detailed list of available methods can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.
+A detailed list of available methods can be found in the "<a
-However, the best source of typemap information (and examples) is probably the Python module
+href="Typemaps.html#Typemaps">Typemaps</a>" chapter.  
-itself.  In fact, all of SWIG's default type handling is defined by typemaps.  You can view
-these typemaps by looking at the <tt>python.swg</tt> file in the SWIG library.  Just issue
-these commands:
 
-<blockquote>
+However, the best source of typemap information (and examples) is
-<pre>
+probably the Python module itself.  In fact, all of SWIG's default
-$ swig -python -co python.swg
+type handling is defined by typemaps.  You can view these typemaps by
-'python.swg' checked out from the SWIG library.
+looking at the files in the SWIG library. Just take into account that
-$ cat python.swg
+in the latest versions of swig (1.3.22+), the library files are not
-</pre>
+very pristine clear for the casual reader, as they used to be. The
-</blockquote>
+extensive use of macros and other ugly techniques in the latest
+version produce a very powerful and consistent python typemap library,
+but at the cost of simplicity and pedagogic value.
+
+To learn how to write a simple or your first typemap, you better take
+a look at the SWIG library version 1.3.20 or so.
 
-Additional typemap examples can also be found in the <tt>typemaps.i</tt> file.
 
 <H3><a name="Python_nn56"></a>26.8.3 Typemap variables</H3>
 

Doc/Manual/SWIGPlus.html

@@ -767,7 +767,8 @@ Members declared as <tt>const</tt> are wrapped as read-only members and do not c
 <H2><a name="SWIGPlus_nn17"></a>6.9 Friends</H2>
 
 
-Friend declarations are ignored by SWIG.   For example, if you have this code:
+Friend declarations are not longer ignored by SWIG. For example, if
+you have this code:
 
 <blockquote>
 <pre>
@@ -780,26 +781,41 @@ public:
 </pre>
 </blockquote>
 
-then the <tt>friend</tt> declaration does not result in any wrapper code.   On the other hand,
+then the <tt>friend</tt> declaration does result in a wrapper code
-a declaration of the function itself will work fine.  For instance:
+equivalent to one generated for the following declaration
 
 <blockquote>
 <pre>
 class Foo {
 public:
     ...
-    friend void blah(Foo *f);       // Ignored
-    ...
 };
 
-void blah(Foo *f);       // Generates wrappers
+void blah(Foo *f);    
 </pre>
 </blockquote>
 
-Unlike normal member functions or static member functions, a friend
+A friend declaration, as in C++, is understood to be in the same scope
-declaration does not define a method that operates on an instance of
+where the class is declared, hence, you can do
-an object nor does it define a declaration in the scope of the class.  
+
-Therefore, it would make no sense for SWIG to create wrappers as such.
+<blockquote>
+<pre>
+
+%ignore bar::blah(Foo *f);
+
+namespace bar {
+
+  class Foo {
+  public:
+     ...
+     friend void blah(Foo *f);
+     ...
+  };
+}
+</pre>
+</blockquote>
+
+and a wrapper for the method 'blah' will not be generated.
 
 <H2><a name="SWIGPlus_nn18"></a>6.10 References and pointers</H2>
 
@@ -879,12 +895,15 @@ Don't return references to objects allocated as local variables on the
 stack.  SWIG doesn't make a copy of the objects so this will probably
 cause your program to crash.
 
+
+
 <p>
 <b>Note:</b> The special treatment for references to primitive datatypes is necessary to provide
 more seamless integration with more advanced C++ wrapping applications---especially related to 
 templates and the STL.  This was first added in SWIG-1.3.12.
 </p>
 
+
 <H2><a name="SWIGPlus_nn19"></a>6.11 Pass and return by value</H2>
 
 
@@ -1134,9 +1153,12 @@ This behavior resulted in huge amounts of replicated code for large
 class hierarchies and made it awkward to build applications spread
 across multiple modules (since accessor functions are duplicated in
 every single module).   It is also unnecessary to have such wrappers
-when advanced features like proxy classes are used.  Future versions
+when advanced features like proxy classes are used.  
-of SWIG may apply further optimizations such as not regenerating 
+
-wrapper functions for virtual members that are already defined in a base class.
+<b>Note:</b> Further optimizations are enabled when using the
+<tt>-fvirtual</tt> option, which avoids the regenerating of wrapper
+functions for virtual members that are already defined in a base
+class.
 </p>
 
 <H2><a name="SWIGPlus_nn21"></a>6.13 A brief discussion of multiple inheritance, pointers,  and type checking</H2>
@@ -2140,7 +2162,7 @@ public:
 	%extend {
 		char *__str__() {
 			static char temp[256];
-			sprintf(temp,"[ %g, %g, %g ]", v-&gt;x,v-&gt;y,v-&gt;z);
+			sprintf(temp,"[ %g, %g, %g ]", self-&gt;x,self-&gt;y,self-&gt;z);
 			return &amp;temp[0];
 		}
 	}
@@ -2604,6 +2626,23 @@ public:
 </pre>
 </blockquote>
 
+or simply
+
+<blockquote>
+<pre>
+class Foo {
+public:
+     template&lt;class T&gt; void bar(T x, T y) { ... };
+     ...
+};
+...
+
+%template(barint)    Foo::bar&lt;int&gt;;
+%template(bardouble) Foo::bar&lt;double&gt;;
+</pre>
+</blockquote>
+
+
 Note: because of the way that templates are handled, the <tt>%template</tt> directive
 must always appear <em>after</em> the definition of the template to be expanded.
 
@@ -2637,7 +2676,8 @@ Miraculously, you will find that each expansion of <tt>Foo</tt> has member
 functions <tt>bari()</tt> and <tt>bard()</tt> added.
 
 <p>
-A common use of member templates is to define constructors for copies and conversions. For example:
+A common use of member templates is to define constructors for copies
+and conversions. For example:
 </p>
 
 <blockquote>
@@ -3422,8 +3462,8 @@ accessible through <tt>operator-&gt;()</tt>.  This includes any methods
 that might be accessible through inheritance.   However, there are a number of restrictions:
 
 <ul>
-<li>Only member variables and methods are wrapped through a smart pointer.  Static members, enumerations,
+<li>Member variables and methods are wrapped through a smart
-constructors, and destructors are not wrapped.
+pointer. Enumerations, constructors, and destructors are not wrapped.
 </li>
 
 <li>If the smart-pointer class and the underlying object both define a method or