Document the module attribute in %import and add warning to Python for when it should be used

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

CHANGES.current

@@ -1,6 +1,14 @@
 Version 1.3.37 (in progress)
 =============================
 
+2008-09-18: wsfulton
+	    Document the optional module attribute in the %import directive,
+            see Modules.html. Add a warning for Python wrappers when the
+            module name for an imported base class is missing, requiring the
+            module attribute to be added to %import, eg 
+
+              %import(module="FooModule") foo.h
+
 2008-09-18: olly
 	    [PHP5] Change the default input typemap for char * to turn PHP
 	    Null into C NULL (previously it was converted to an empty string).

Doc/Manual/Modules.html

@@ -50,41 +50,90 @@ scripting language runtime as you would do for the single module case.
 
 <p>
 A bit more complex is the case in which modules need to share information.
-For example, when one module extends the class of the another by deriving from
+For example, when one module extends the class of another by deriving from
 it:
 </p>
 
 <div class="code"><pre>
-%module base
+// File: base.h
-
-%inline %{
 class base {
 public:
-       int foo(void);
+  int foo();
 };
-%}
 </pre></div>
 &nbsp;
-<div class="code"><pre>
-%module derived
 
-%import "base.i"
+<div class="code"><pre>
+// File: base_module.i
+%module base_module
+
+%{
+#include "base.h"
+%}
+%include "base.h"
+</pre></div>
+&nbsp;
+
+<div class="code"><pre>
+// File: derived_module.i
+%module derived_module
+
+%import "base_module.i"
 
 %inline %{
 class derived : public base {
 public:
-       int bar(void);
+  int bar();
 };
 %}
 </pre></div>
 
-<p>To create the wrapper properly, module <tt>derived</tt> needs to know the
+<p>To create the wrapper properly, module <tt>derived_module</tt> needs to know about the
-<tt>base</tt> class and that it's interface is covered in another module. The
+<tt>base</tt> class and that its interface is covered in another module. The
-line <tt>%import "base.i"</tt> lets SWIG know exactly that. The common mistake here is
+line <tt>%import "base_module.i"</tt> lets SWIG know exactly that. Oftentimes
-to <tt>%import</tt> the <tt>.h</tt> file instead of the <tt>.i</tt>, which sadly won't do the trick. Another issue
+the <tt>.h</tt> file is passed to <tt>%import</tt> instead of the <tt>.i</tt>, 
-to take care of is that multiple dependent wrappers should not be linked/loaded
+which unfortunately doesn't work for all language modules. For example, Python requires the
+name of module that the base class exists in so that the proxy classes can fully inherit the
+base class's methods. Typically you will get a warning when the module name is missing, eg:
+</p>
+
+<div class="shell"> <pre>
+derived_module.i:8: Warning(401): Base class 'base' ignored - unknown module name for base. Either import 
+the appropriate module interface file or specify the name of the module in the %import directive.
+</pre></div>
+
+<p>
+It is sometimes desirable to import the header file rather than the interface file and overcome
+the above warning. 
+For example in the case of the imported interface being quite large, it may be desirable to
+simplify matters and just import a small header file of dependent types.
+This can be done by specifying the optional <tt>module</tt> attribute in the <tt>%import</tt> directive.
+The <tt>derived_module.i</tt> file shown above could be replaced with the following:
+
+<div class="code"><pre>
+// File: derived_module.i
+%module derived_module
+
+%import(module="base_module") "base.h"
+
+%inline %{
+class derived : public base {
+public:
+  int bar();
+};
+</pre></div>
+
+<p>
+Note that "base_module" is the module name and is the same as that specified in <tt>%module</tt>
+in <tt>base_module.i</tt> as well as the <tt>%import</tt> in <tt>derived_module.i</tt>.
+</p>
+
+<p>
+Another issue
+to beware of is that multiple dependent wrappers should not be linked/loaded
 in parallel from multiple threads as SWIG provides no locking - for more on that
 issue, read on.</p>
+</p>
 
 <H2><a name="Modules_nn2"></a>15.2 The SWIG runtime code</H2>
 

Doc/Manual/Preprocessor.html

@@ -81,7 +81,7 @@ Such information generally includes type declarations (e.g., <tt>typedef</tt>) a
 C++ classes that might be used as base-classes for class declarations in the interface.
 The use of <tt>%import</tt> is also important when SWIG is used to generate
 extensions as a collection of related modules.   This is an advanced topic and is described
-in a later chapter.
+in later in the <a href="Modules.html">Working with Modules</a> chapter.
 </p>
 
 <P>

Examples/test-suite/import_nomodule.i

@@ -3,6 +3,9 @@
 #include "import_nomodule.h"
 %}
 
+// For Python
+%warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Bar; // Base class 'Foo' ignored - unknown module name for base. Either import the appropriate module interface file or specify the name of the module in the %import directive. 
+
 %import "import_nomodule.h"
 
 #if !defined(SWIGJAVA) && !defined(SWIGRUBY) && !defined(SWIGCSHARP)

Examples/test-suite/imports_b.i

@@ -34,9 +34,14 @@
 */
 
 #if 0
-%import "imports_a.i"
+  %import "imports_a.i"
 #else
-%import(module="imports_a") "imports_a.h" 
+#  if 0
+  // Test Warning 401 (Python only)
+  %import "imports_a.h" 
+#  else
+  %import(module="imports_a") "imports_a.h" 
+#  endif
 #endif
 
 %include "imports_b.h"  

Source/Modules/python.cxx

@@ -2864,7 +2864,12 @@ public:
 	b = First(baselist);
 	while (b.item) {
 	  String *bname = Getattr(b.item, "python:proxy");
-	  if (!bname || GetFlag(b.item, "feature:ignore")) {
+          bool ignore = GetFlag(b.item, "feature:ignore") ? true : false;
+	  if (!bname || ignore) {
+            if (!bname && !ignore) {
+              Swig_warning(WARN_TYPE_UNDEFINED_CLASS, input_file, line_number,
+                  "Base class '%s' ignored - unknown module name for base. Either import the appropriate module interface file or specify the name of the module in the %%import directive.\n", SwigType_namestr(Getattr(b.item, "name")));
+            }
 	    b = Next(b);
 	    continue;
 	  }