Merge branch 'luav-master'
* luav-master:
Doc corrections for %shared_ptr and enhancements for %inline
Library docs chapter tweaks
%rename for functions with default parameters explained, see #1087
%shared_ptr usage for the templates documented, see #1049
Includes inside %inline block documented, see #1068
diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html
index 97db5f1..f3beb22 100644
--- a/Doc/Manual/Contents.html
+++ b/Doc/Manual/Contents.html
@@ -358,26 +358,32 @@
<div class="sectiontoc">
<ul>
<li><a href="Library.html#Library_nn2">The %include directive and library search path</a>
-<li><a href="Library.html#Library_nn3">C Arrays and Pointers</a>
+<li><a href="Library.html#Library_nn3">C arrays and pointers</a>
<ul>
<li><a href="Library.html#Library_nn4">cpointer.i</a>
<li><a href="Library.html#Library_carrays">carrays.i</a>
<li><a href="Library.html#Library_nn6">cmalloc.i</a>
<li><a href="Library.html#Library_nn7">cdata.i</a>
</ul>
-<li><a href="Library.html#Library_nn8">C String Handling</a>
+<li><a href="Library.html#Library_nn8">C string handling</a>
<ul>
<li><a href="Library.html#Library_nn9">Default string handling</a>
<li><a href="Library.html#Library_nn10">Passing binary data</a>
<li><a href="Library.html#Library_nn11">Using %newobject to release memory</a>
<li><a href="Library.html#Library_nn12">cstring.i</a>
</ul>
-<li><a href="Library.html#Library_stl_cpp_library">STL/C++ Library</a>
+<li><a href="Library.html#Library_stl_cpp_library">STL/C++ library</a>
<ul>
<li><a href="Library.html#Library_std_string">std::string</a>
<li><a href="Library.html#Library_std_vector">std::vector</a>
<li><a href="Library.html#Library_stl_exceptions">STL exceptions</a>
<li><a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a>
+<ul>
+<li><a href="Library.html#Library_shared_ptr_basics">shared_ptr basics</a>
+<li><a href="Library.html#Library_shared_ptr_inheritance">shared_ptr and inheritance</a>
+<li><a href="Library.html#Library_shared_ptr_templates">shared_ptr and templates</a>
+<li><a href="Library.html#Library_shared_ptr_directors">shared_ptr and directors</a>
+</ul>
<li><a href="Library.html#Library_std_auto_ptr">auto_ptr smart pointer</a>
</ul>
<li><a href="Library.html#Library_nn16">Utility Libraries</a>
diff --git a/Doc/Manual/Library.html b/Doc/Manual/Library.html
index f41799b..8939c8d 100644
--- a/Doc/Manual/Library.html
+++ b/Doc/Manual/Library.html
@@ -12,26 +12,32 @@
<div class="sectiontoc">
<ul>
<li><a href="#Library_nn2">The %include directive and library search path</a>
-<li><a href="#Library_nn3">C Arrays and Pointers</a>
+<li><a href="#Library_nn3">C arrays and pointers</a>
<ul>
<li><a href="#Library_nn4">cpointer.i</a>
<li><a href="#Library_carrays">carrays.i</a>
<li><a href="#Library_nn6">cmalloc.i</a>
<li><a href="#Library_nn7">cdata.i</a>
</ul>
-<li><a href="#Library_nn8">C String Handling</a>
+<li><a href="#Library_nn8">C string handling</a>
<ul>
<li><a href="#Library_nn9">Default string handling</a>
<li><a href="#Library_nn10">Passing binary data</a>
<li><a href="#Library_nn11">Using %newobject to release memory</a>
<li><a href="#Library_nn12">cstring.i</a>
</ul>
-<li><a href="#Library_stl_cpp_library">STL/C++ Library</a>
+<li><a href="#Library_stl_cpp_library">STL/C++ library</a>
<ul>
<li><a href="#Library_std_string">std::string</a>
<li><a href="#Library_std_vector">std::vector</a>
<li><a href="#Library_stl_exceptions">STL exceptions</a>
<li><a href="#Library_std_shared_ptr">shared_ptr smart pointer</a>
+<ul>
+<li><a href="#Library_shared_ptr_basics">shared_ptr basics</a>
+<li><a href="#Library_shared_ptr_inheritance">shared_ptr and inheritance</a>
+<li><a href="#Library_shared_ptr_templates">shared_ptr and templates</a>
+<li><a href="#Library_shared_ptr_directors">shared_ptr and directors</a>
+</ul>
<li><a href="#Library_std_auto_ptr">auto_ptr smart pointer</a>
</ul>
<li><a href="#Library_nn16">Utility Libraries</a>
@@ -92,7 +98,7 @@
The directories that are searched are displayed when using <tt>-verbose</tt> commandline option.
</p>
-<H2><a name="Library_nn3">9.2 C Arrays and Pointers</a></H2>
+<H2><a name="Library_nn3">9.2 C arrays and pointers</a></H2>
<p>
@@ -761,7 +767,7 @@
Clearly they are unsafe.
</p>
-<H2><a name="Library_nn8">9.3 C String Handling</a></H2>
+<H2><a name="Library_nn8">9.3 C string handling</a></H2>
<p>
@@ -1365,7 +1371,7 @@
</li>
</ul>
-<H2><a name="Library_stl_cpp_library">9.4 STL/C++ Library</a></H2>
+<H2><a name="Library_stl_cpp_library">9.4 STL/C++ library</a></H2>
<p>
@@ -1728,6 +1734,9 @@
<H3><a name="Library_std_shared_ptr">9.4.4 shared_ptr smart pointer</a></H3>
+<H4><a name="Library_shared_ptr_basics">9.4.4.1 shared_ptr basics</a></H4>
+
+
<p>
Some target languages have support for handling the shared_ptr reference counted smart pointer.
This smart pointer is available in the standard C++11 library as <tt>std::shared_ptr</tt>.
@@ -1821,8 +1830,11 @@
</pre>
</div>
+<H4><a name="Library_shared_ptr_inheritance">9.4.4.2 shared_ptr and inheritance</a></H4>
+
+
<p>
-This shared_ptr library works quite differently to SWIG's normal, but somewhat limited,
+The shared_ptr library works quite differently to SWIG's normal, but somewhat limited,
<a href="SWIGPlus.html#SWIGPlus_smart_pointers">smart pointer handling</a>.
The shared_ptr library does not generate extra wrappers, just for smart pointer handling, in addition to the proxy class.
The normal proxy class including inheritance relationships is generated as usual.
@@ -1900,7 +1912,7 @@
<div class="code">
<pre>
-%include "boost_shared_ptr.i"
+%include <boost_shared_ptr.i>
%shared_ptr(GrandParent);
%shared_ptr(Parent);
%shared_ptr(Child);
@@ -1909,8 +1921,52 @@
</pre>
</div>
+<H4><a name="Library_shared_ptr_templates">9.4.4.3 shared_ptr and templates</a></H4>
+
<p>
-<b>Note:</b> There is somewhat limited support for <tt>%shared_ptr</tt> and the director feature
+The <tt>%shared_ptr</tt> macro should be used for all the required instantiations
+of the template before each of the <tt>%template</tt> instantiations.
+For example, consider <tt>number.h</tt> containing the following illustrative template:
+</p>
+
+<div class="code">
+<pre>
+#include <memory>
+
+template<int N> struct Number {
+ int num;
+ Number() : num(N) {}
+ static std::shared_ptr<Number<N>> make() { return std::make_shared<Number<N>>(); }
+};
+</pre>
+</div>
+
+<p>
+The SWIG code below shows the required ordering:
+</p>
+
+<div class="code">
+<pre>
+%include <std_shared_ptr.i>
+
+%shared_ptr(Number<10>);
+%shared_ptr(Number<42>);
+
+%{
+ #include "number.h"
+%}
+%include "number.h"
+
+%template(Number10) Number<10>;
+%template(Number42) Number<42>;
+</pre>
+</div>
+
+<H4><a name="Library_shared_ptr_directors">9.4.4.4 shared_ptr and directors</a></H4>
+
+
+<p>
+There is somewhat limited support for <tt>%shared_ptr</tt> and the director feature
and the degrees of success varies among the different target languages.
Please help to improve this support by providing patches with improvements.
</p>
diff --git a/Doc/Manual/SWIG.html b/Doc/Manual/SWIG.html
index de9e2ec..d677a22 100644
--- a/Doc/Manual/SWIG.html
+++ b/Doc/Manual/SWIG.html
@@ -3303,11 +3303,27 @@
return (Vector *) malloc(sizeof(Vector));
}
%}
-
</pre></div>
<p>
-The <tt>%inline</tt> directive inserts all of the code that follows
+This is the same as writing:
+</p>
+
+<div class="code"><pre>
+%{
+/* Create a new vector */
+Vector *new_Vector() {
+ return (Vector *) malloc(sizeof(Vector));
+}
+%}
+
+/* Create a new vector */
+Vector *new_Vector() {
+ return (Vector *) malloc(sizeof(Vector));
+}
+</pre></div>
+<p>
+In other words, the <tt>%inline</tt> directive inserts all of the code that follows
verbatim into the header portion of an interface file. The code is
then parsed by both the SWIG preprocessor and parser.
Thus, the above example creates a new command <tt>new_Vector</tt> using only one
@@ -3315,6 +3331,11 @@
is given to both the C compiler and SWIG, it is illegal to include any
SWIG directives inside a <tt>%{ ... %}</tt> block.</p>
+
+<p>
+<b>Note:</b> The usual SWIG C preprocessor rules apply to code in <tt>%apply</tt> blocks when SWIG parses this code. For example, as mentioned earlier, <a href="SWIG.html#SWIG_nn6">SWIG's C Preprocessor</a> does not follow <tt>#include</tt> directives by default.
+</p>
+
<H3><a name="SWIG_nn44">5.6.4 Initialization blocks</a></H3>
