merge from trunk

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2009-sploving@11292 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Doc/Manual/Arguments.html

@@ -351,7 +351,7 @@ function like this in an interface file :</p>
 
 <div class="code"><pre>
 %module example
-%include typemaps.i
+%include "typemaps.i"
 ...
 %{
 extern void negate(double *);

Doc/Manual/CSharp.html

@@ -99,6 +99,7 @@ namespace com.bloggs.widget {
   ...
 }
 </pre></div>
+Note that by default, the generated C# classes have no namespace and the module name is unrelated to namespaces. The module name is just like in Java and is merely used to name some of the generated classes.
 </li>
 
 <li>
@@ -131,7 +132,7 @@ If it was used, it would generate an illegal runtime initialisation via a PInvok
 C# doesn't support the notion of throws clauses.
 Therefore there is no 'throws' typemap attribute support for adding exception classes to a throws clause.
 Likewise there is no need for an equivalent to <tt>%javaexception</tt>.
-In fact, throwing C# exceptions works quite differently, see <a href="CSharp.html#csharp_exceptions">C# Exceptions></a> below.
+In fact, throwing C# exceptions works quite differently, see <a href="CSharp.html#csharp_exceptions">C# Exceptions</a> below.
 </li>
 
 <li>
@@ -212,7 +213,7 @@ The "csin" typemap supports additional optional attributes called 'cshin' and 't
 The 'cshin' attribute should contain the parameter type and name whenever a <a href="Java.html#java_constructor_helper_function">constructor helper function</a> is generated due to the 'pre' or 'post' attributes. 
 The 'terminator' attribute normally just contains a closing brace for when the 'pre' attribute contains an opening brace, such as when a C# <tt>using</tt> or <tt>fixed</tt> block is started.
 Note that 'pre', 'post', 'terminator' and 'cshin' attributes are not used for marshalling the property set.
-Please see the <a href="#csharp_date_marshalling">Date marshalling example</a> and <a href="#CSharp.html#csharp_date_properties">Date marshalling of properties example</a> for further understanding of these "csin" applicable attributes.
+Please see the <a href="#csharp_date_marshalling">Date marshalling example</a> and <a href="#csharp_date_properties">Date marshalling of properties example</a> for further understanding of these "csin" applicable attributes.
 </p>
 </li>
 

Doc/Manual/Contents.html

@@ -488,6 +488,7 @@
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
+<li><a href="Modules.html#Modules_introduction">Modules Introduction</a>
 <li><a href="Modules.html#Modules_nn1">Basics</a>
 <li><a href="Modules.html#Modules_nn2">The SWIG runtime code</a>
 <li><a href="Modules.html#external_run_time">External access to the runtime</a>

Doc/Manual/Java.html

@@ -253,6 +253,12 @@ To change this, you can use the <tt>-o</tt> option.
 It is also possible to change the <a href="SWIG.html#output">output directory </a> that the Java files are generated into using <tt>-outdir</tt>.
 </p>
 
+<p>
+The module name, specified with <tt>%module</tt>, determines the name of various generated classes as discussed <a href=#module_packages_classes>later</a>.
+Note that the module name does not define a Java package and by default, the generated Java classes do not have a Java package.
+The <tt>-package</tt> option described below can specify a Java package name to use.
+</p>
+
 <p>
 The following sections have further practical examples and details on how you might go about
 compiling and using the generated files.

Doc/Manual/Modules.html

@@ -10,6 +10,7 @@
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
+<li><a href="#Modules_introduction">Modules Introduction</a>
 <li><a href="#Modules_nn1">Basics</a>
 <li><a href="#Modules_nn2">The SWIG runtime code</a>
 <li><a href="#external_run_time">External access to the runtime</a>
@@ -22,11 +23,49 @@
 
 
 
+<H2><a name="Modules_introduction"></a>15.1 Modules Introduction</H2>
+
+
+<p>
+Each invocation of SWIG requires a module name to be specified.
+The module name is used to name the resulting target language extension module. 
+Exactly what this means and and what the name is used for
+depends on the target language, for example the name can define
+a target language namespace or merely be a useful name for naming files or helper classes.
+Essentially, a module comprises target language wrappers for a chosen collection of global variables/functions, structs/classes and other C/C++ types.
+</p>
+
+<p>
+The module name can be supplied in one of two ways. 
+The first is to specify it with the special <tt>%module</tt>
+directive. This directive must appear at the beginning of the interface file.
+The general form of this directive is:
+</p>
+
+<div class="code"><pre>
+<tt>%module(option1="value1",option2="value2",...) modulename</tt>
+</pre></div>
+
+<p>
+where the modulename is mandatory and the options add one or more optional additional features.
+Typically no options are specified, for example:
+</p>
+
+<div class="code"><pre>
+<tt>%module mymodule</tt>
+</pre></div>
+
+<p>
+The second way to specify the module name is with the <tt>-module</tt> command line option, for example <tt>-module mymodule</tt>.
+If the module name is supplied on the command line, it overrides the name specified by the
+<tt>%module</tt> directive.
+</p>
+
 <p>
 When first working with SWIG, users commonly start by creating a
 single module.  That is, you might define a single SWIG interface that
 wraps some set of C/C++ code.  You then compile all of the generated
-wrapper code into a module and use it.   For large applications, however,
+wrapper code together and use it.   For large applications, however,
 this approach is problematic---the size of the generated wrapper code
 can be rather large.  Moreover, it is probably easier to manage the
 target language interface when it is broken up into smaller pieces.
@@ -34,10 +73,11 @@ target language interface when it is broken up into smaller pieces.
 
 <p>
 This chapter describes the problem of using SWIG in programs
-where you want to create a collection of modules.
+where you want to create a collection of modules. 
+Each module in the collection is created via separate invocations of SWIG.
 </p>
 
-<H2><a name="Modules_nn1"></a>15.1 Basics</H2>
+<H2><a name="Modules_nn1"></a>15.2 Basics</H2>
 
 
 <p>
@@ -135,7 +175,7 @@ in parallel from multiple threads as SWIG provides no locking - for more on that
 issue, read on.
 </p>
 
-<H2><a name="Modules_nn2"></a>15.2 The SWIG runtime code</H2>
+<H2><a name="Modules_nn2"></a>15.3 The SWIG runtime code</H2>
 
 
 <p>
@@ -201,7 +241,7 @@ can peacefully coexist. So the type structures are separated by the
 is empty. Only modules compiled with the same pair will share type information.
 </p>
 
-<H2><a name="external_run_time"></a>15.3 External access to the runtime</H2>
+<H2><a name="external_run_time"></a>15.4 External access to the runtime</H2>
 
 
 <p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
@@ -238,7 +278,7 @@ SWIG_TYPE_TABLE to be the same as the module whose types you are trying to
 access.
 </p>
 
-<H2><a name="Modules_nn4"></a>15.4 A word of caution about static libraries</H2>
+<H2><a name="Modules_nn4"></a>15.5 A word of caution about static libraries</H2>
 
 
 <p>
@@ -249,7 +289,7 @@ into it. This is very often <b>NOT</b> what you want and it can lead to unexpect
 behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries.
 </p>
 
-<H2><a name="Modules_nn5"></a>15.5 References</H2>
+<H2><a name="Modules_nn5"></a>15.6 References</H2>
 
 
 <p>
@@ -257,7 +297,7 @@ Due to the complexity of working with shared libraries and multiple modules, it
 an outside reference.  John Levine's "Linkers and Loaders" is highly recommended.
 </p>
 
-<H2><a name="Modules_nn6"></a>15.6 Reducing the wrapper file size</H2>
+<H2><a name="Modules_nn6"></a>15.7 Reducing the wrapper file size</H2>
 
 
 <p>

Doc/Manual/Ocaml.html

@@ -634,13 +634,13 @@ length.  Instead, use multiple returns, as in the argout_ref example.
 #include "example.h"
 %}
 
-%include stl.i
+%include <stl.i>
 
 namespace std {
         %template(StringVector) std::vector < string >;
 };
 
-%include example.h
+%include "example.h"
 </pre></td></tr>
 <tr><td><font size="-1"><i>This example is in Examples/ocaml/stl
 </i></font></td></tr>

Doc/Manual/Perl5.html

@@ -264,7 +264,7 @@ extern int fact(int);
 %}
 
 // Include code for rebuilding Perl
-%include perlmain.i
+%include <perlmain.i>
 </pre></div>
 
 <p>
@@ -1543,7 +1543,7 @@ example:
 <div class="code">
 <pre>
 %module example
-%include typemaps.i
+%include "typemaps.i"
 
 void add(int x, int y, int *REFERENCE);
 </pre>

Doc/Manual/Php.html

@@ -479,7 +479,7 @@ One can include <b>cpointer.i</b> to generate PHP wrappers to <tt>int
 
 <div class="code"><pre>
 %module example
-%include cpointer.i
+%include "cpointer.i"
 %pointer_functions(int,intp)
 
 void add( int *in1, int *in2, int *result);
@@ -513,7 +513,7 @@ parameter names as appropriate.
 
 <div class="code"><pre>
 %module example
-%include typemaps.i
+%include "typemaps.i"
 
 void add( int *INPUT, int *INPUT, int *OUTPUT);
 
@@ -545,7 +545,7 @@ named typemap REFERENCE.
 
 <div class="code"><pre>
 %module example
-%include phppointers.i
+%include "phppointers.i"
 
 void add( int *REF, int *REF, int *REF);
 
@@ -781,12 +781,6 @@ Ko::threats();
 <H3><a name="Php_nn2_7"></a>29.2.7 PHP Pragmas, Startup and Shutdown code</H3>
 
 
-<p>
-Note: Currently pragmas for PHP need to be specified using
-<tt>%pragma(php)</tt> but also apply for PHP5!  This is just a historical
-oddity because SWIG's PHP support predates PHP5.
-</p>
-
 <p>
 To place PHP code in the generated "example.php" file one can use the
 <b>code</b> pragma. The code is inserted after loading the shared

Doc/Manual/Python.html

@@ -433,7 +433,7 @@ extern int mod(int, int);
 extern double My_variable;
 %}
 
-%include embed.i       // Include code for a static version of Python
+%include "embed.i"       // Include code for a static version of Python
 
 </pre></div>
 

Doc/Manual/Ruby.html

@@ -2393,7 +2393,7 @@ intset;<br>
 
 
 
-%include std_set.i<br>
+%include &lt;std_set.i&gt;<br>
 
 
 

Doc/Manual/SWIG.html

@@ -174,13 +174,8 @@ int bar(int x);
 ...
 </pre></div>
 <p>
-The name of the module is supplied using the special <tt>%module</tt>
-directive (or the <tt>-module</tt> command line option).  This
-directive must appear at the beginning of the file and is used to name
-the resulting extension module (in addition, this name often defines
-a namespace in the target language).  If the module name is supplied on the
-command line, it overrides the name specified with the
-<tt>%module</tt> directive.
+The module name is supplied using the special <tt>%module</tt>
+directive. Modules are described further in the <a href="Modules.html#Modules_introduction">Modules Introduction</a> section.
 </p>
 
 <p>
@@ -2361,7 +2356,7 @@ You can make a <tt>Vector</tt> look a lot like a class by writing a SWIG interfa
 #include "vector.h"
 %}
 
-%include vector.h            // Just grab original C header file
+%include "vector.h"          // Just grab original C header file
 %extend Vector {             // Attach these functions to struct Vector
 	Vector(double x, double y, double z) {
 		Vector *v;
@@ -2883,10 +2878,16 @@ interface to your program.
 SWIG's <tt>%include</tt> directive to process an entire C
 source/header file. 
 
-<li>Make sure everything in the interface file uses ANSI C/C++syntax.
+<li>Make sure everything in the interface file uses ANSI C/C++ syntax.
 
 <li>Make sure all necessary `<tt>typedef</tt>' declarations and
-type-information is available in the interface file.
+type-information is available in the interface file. 
+In particular, ensure that the type information is specified in the correct order as required by a C/C++ compiler.
+Most importantly, define a type before it is used! A C compiler will tell you
+if the full type information is not available if it is needed, whereas
+SWIG will usually not warn or error out as it is designed to work without
+full type information. However, if type information is not specified
+correctly, the wrappers can be sub-optimal and even result in uncompileable C/C++ code.
 
 <li>If your program has a main() function, you may need to rename it
 (read on).
@@ -2945,16 +2946,21 @@ extern void dump(FILE *f);
 
 <p>
 Of course, in this case, our header file is pretty simple so we could
-have made an interface file like this as well:</p>
+use a simpler approach and use an interface file like this:</p>
 
 <div class="code"><pre>
 /* File : interface.i */
 %module mymodule
-%include header.h
+%{
+#include "header.h"
+%}
+%include "header.h"
 </pre></div>
 
 <p>
-Naturally, your mileage may vary.</p>
+The main advantage of this approach is minimal maintenance of an interface file for when the header file changes in the future.
+In more complex projects, an interface file containing numerous <tt>%include</tt> and <tt>#include</tt> statements like this is one of the most common approaches to interface file design due to lower maintenance overhead.
+</p>
 
 <H3><a name="SWIG_nn48"></a>5.7.3 Why use separate interface files?</H3>
 

Doc/Manual/Tcl.html

@@ -190,7 +190,7 @@ extern int mod(int, int);
 extern double My_variable;
 %}
 
-%include tclsh.i       // Include code for rebuilding tclsh
+%include "tclsh.i"       // Include code for rebuilding tclsh
 
 </pre></div>
 
@@ -2822,7 +2822,7 @@ int print_args(char **argv) {
     return i;
 }
 %}
-%include tclsh.i
+%include "tclsh.i"
 
 </pre></div>