add docs for new -nodefault, -nodefaultdtor and -oldnodefault

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

SWIG/CHANGES.current

@@ -77,22 +77,31 @@ Version 1.3.28 (unreleased).
 	    just to disable the destructor  when the flag is mainly 
 	    used to ignore the default constructor. 
 
-	    It should be noted that this is also the behavior for C,
+	    If needed, you can still disable the destructor, by using
-	    i.e., the destructor is always generated.
+	    the feature form:
 
-	    What about adding a -nodefaultdestructor? I am not sure, I
+	       %nodefaultdtor  MyVerySpecialClass;
-	    don't see a reason to do that as long as I don't a reason
-	    to add a flag like -pleasegeneratememoryleaks.
-
-	    But don't worry, if needed, we can still generate memory
-	    leaks, I mean, disable the destructor,  by using 
-
-	       %ignore Class::~Class();
 	    
-	    Yes, is not as automatic as '-nodefault' or
+	    Note: if you really really need it, you can still disable
-	    '-nodefaultdestructor', but in this case I think that
+	    the implicit destructors at the command line using
-	    forcing to do this manually and in a 'case by case' approach
+   	   
-	    is desirable.
+               swig  -nodefaultdtor
+
+	    But really, don't do that please.
+
+	    Also, you can force the old 'nodefault' behavior by using
+
+	       swig -oldnodefault
+   
+
+            *** POTENTIAL INCOMPATIBILITY ***
+
+	    If you use -nodefault in your interface, now some new
+	    destructors could be generated in the interface. This
+	    could solve some memory leaks but also produce some
+	    conflicts.
+
+	    To restore old behavior, you can use -oldnodefault.
  
 
 12/08/2005: mmatus 

SWIG/Doc/Manual/Java.html

@@ -6124,6 +6124,7 @@ The following interface file code should be placed before SWIG parses the above
 
 // Do not generate the default proxy constructor or destructor
 %nodefault Butler;
+%nodefaultdestructor Butler;
 
 // Add in pure Java code proxy constructor
 %typemap(javacode) Butler %{
@@ -6159,6 +6160,12 @@ Note that the JNI code sets the proxy's <tt>swigCPtr</tt> member variable to poi
 The <tt>swigCMemOwn</tt> remains unchanged (at false), so that the proxy does not own the memory.
 </p>
 
+<p>
+Note: prior to 1.3.28, the %nodefault directive disabled the default
+constructor and destructor at the same time. Now it is required to explicitly use
+%nodefault and %nodefaultdestructor to achieve the same result.
+</p>
+
 <p>
 The second approach offers a more object oriented interface to the Java user.
 We do this by making the Java proxy class's

SWIG/Doc/Manual/SWIG.html

@@ -2222,13 +2222,13 @@ differently.
 </p>
 
 <p>
-If you don't want SWIG to generate constructors and destructors, you
+If you don't want SWIG to generate default constructors when processing C++
-can use the <tt>%nodefault</tt> directive or the <tt>-no_default</tt>
+interfaces, you can use the <tt>%nodefault</tt> directive or the
-command line option.  For example:
+<tt>-nodefault</tt> command line option.  For example:
 </p>
 
 <div class="shell"><pre>
-swig -no_default example.i 
+swig -nodefault example.i 
 </pre></div>
 
 <p>
@@ -2238,9 +2238,9 @@ or
 <div class="code"><pre>
 %module foo
 ...
-%nodefault;        // Don't create default constructors/destructors
+%nodefault;        // Don't create default constructors
 ... declarations ...
-%makedefault;      // Reenable default constructors/destructors
+%makedefault;      // Reenable default constructors
 </pre></div>
 
 <p>
@@ -2250,16 +2250,38 @@ definitions.  For example:
 
 <div class="code">
 <pre>
-%nodefault Foo;          // No default constructor/destructors for Foo
+%nodefault Foo;          // No default constructor for Foo
 ...
-struct Foo {             // No default generated.
+struct Foo {             // No default constructor generated.
 };
 
-struct Bar {             // Default constructor/destructor generated.
+struct Bar {             // Default constructor generated.
 };
 </pre>
 </div>
 
+
+<p>
+Since ignoring the implicit or default destructors most of the times
+produce memory leaks, SWIG will always try to generate them. If
+needed, however, you can selectively disable the generation of the
+default/implicit destructor by using <tt>%nodefaultdestructor </tt>
+</p>
+
+<div class="code">
+<pre>
+%nodefaultdestructor Foo; // No default/implicit destructor for Foo
+...
+struct Foo {              // No default destructor is generated.
+};
+
+struct Bar {              // Default destructor generated.
+};
+</pre>
+</div>
+
+
+
 <p>
 <b>Compatibility note:</b> Prior to SWIG-1.3.7, SWIG did not generate default constructors
 or destructors unless you explicitly turned them on using <tt>-make_default</tt>. 
@@ -2267,6 +2289,17 @@ However, it appears that most users want to have constructor and destructor func
 has now been enabled as the default behavior.
 </p>
 
+<p>
+<b>Compatibility note:</b> Prior to SWIG-1.3.28, the
+<tt>-nodefault</tt> option and <tt>%nodefault</tt> directive also
+disable the default or implicit destructor generation. This had the
+major side effect of generating memory leaks, and is now disabled. If
+your interface needs the old behavior, use the
+<tt>-oldnodefault</tt> option.
+
+</p>
+
+
 <H3><a name="SWIG_adding_member_functions"></a>5.5.6 Adding member functions to C structures</H3>
 
 

SWIG/Doc/Manual/SWIGPlus.html

@@ -17,7 +17,7 @@
 <li><a href="#SWIGPlus_nn6">Simple C++ wrapping</a>
 <ul>
 <li><a href="#SWIGPlus_nn7">Constructors and destructors</a>
-<li><a href="#SWIGPlus_nn8">Default constructors</a>
+<li><a href="#SWIGPlus_nn8">Default constructors and implicit destructors</a>
 <li><a href="#SWIGPlus_nn9">When constructor wrappers aren't created</a>
 <li><a href="#SWIGPlus_nn10">Copy constructors</a>
 <li><a href="#SWIGPlus_nn11">Member functions</a>
@@ -270,13 +270,21 @@ void delete_List(List *l) {
 
 </pre></div>
 
-<H3><a name="SWIGPlus_nn8"></a>6.5.2 Default constructors</H3>
+<H3><a name="SWIGPlus_nn8"></a>6.5.2 Default constructors and implicit destructors</H3>
 
 
 <p>
-If a C++ class does not define any public constructors or
+If a C++ class does not define a destructor, SWIG will automatically
-destructors, SWIG will automatically create a default constructor or 
+create one following the implicit destructor rule from C++.
-destructor.   However, there are a few rules that define this behavior:
+</p>
+
+<p>
+If a C++ class does not define any public constructors, SWIG will
+automatically create a default constructor. 
+</p>
+
+<p>
+ There are, however, a few rules that alters the previous behavior:
 </p>
 
 <ul>
@@ -291,45 +299,108 @@ inherit from an abstract class, but don't provide definitions for all of the pur
 default constructor. 
 </li>
 
-<li>Default constructors and destructors are not created if a class
+<li>Default constructors and implicit destructors are not created if a class
 defines constructors or destructors in a <tt>private</tt> or <tt>protected</tt> section.
 </li>
 
-<li>Default constructors and destructors are not created if any base
+<li>Default constructors and implicit destructors are not created if any base
-class defines a private default constructor or a private destructor.
+class defines a non-public default constructor or destructor.
 </li>
 </ul>
 
 <p>
-SWIG should never generate a constructor or destructor for a class in which
+SWIG should never generate a default constructor for a class in which
-it is illegal to do so.   However, if it is necessary to disable the
+it is illegal to do so.  In some cases, however, it could be necessary
-default constructor/destructor creation, the <tt>%nodefault</tt> directive
+or desired to disable the default constructor. Then the
-can be used:
+<tt>%nodefault</tt> directive can be used:
 </p>
 
 <div class="code">
 <pre>
-%nodefault;   // Disable creation of constructor/destructor
+%nodefault Foo;     // Disable the default constructor for class Foo.
-class Foo {
+class Foo {         // No default constructor is generated, unless is declared
 ...
 };
-%makedefault;
+class Bar {         // A default constructor is generated, if possible
+...
+};
+</pre>
+</div>
+<p>
+The directive <tt>%nodefault</tt> can also be applied "globally", as in:
+</p>
+<div class="code">
+<pre>
+%nodefault;   // Disable creation of default constructors
+class Foo {   // No default constructor is generated, unless is declared
+...
+};
+class Bar {   // No default constructor is generated, unless is declared
+...
+};
+%makedefault; // Enable the creation of default constructors again
 </pre>
 </div>
 
 <p>
-<tt>%nodefault</tt> can also take a class name.  For example:
+Note that the <tt>%nodefault</tt> has no effect if the default
+constructor is explicitly declared, as in the following case:
+</p>
+<div class="code">
+<pre>
+%nodefault;   // Disable creation of default constructors
+class Foo {   
+public:
+  Foo();      // The default constructor is generated, since is declared
+};
+%makedefault; // Enable the creation of default constructors again
+</pre>
+</div>
+
+
+
+<p>
+The correspondig <tt>%nodefaultdtor</tt> directive can be used
+to disable the generation of the default or implicit destructor, if
+needed. Be aware, however, that this could lead to memory leaks in the
+target language. Hence, it is recommended to use this directive only
+in well known cases. For example:
 </p>
 
 <div class="code">
 <pre>
-%nodefault Foo;     // Disable for class Foo only.
+%nodefaultdtor Foo;   // Disable the implictit/default destructor for class Foo.
+class Foo {                 // No destructor is generated, unless is declared
+...
+};
 </pre>
 </div>
 
+<p>
+As in the <tt>%nodefault</tt> case, the <tt>%nodefaultdtor</tt>
+has no effect over classes that explicitly declare a public
+destructor:
+</p>
+
+<div class="code">
+<pre>
+%nodefaultdtor Foo;   // Try to disable the implictit/default destructor for class Foo.
+class Foo {                 
+public:
+  ~Foo();                   // The destructor is generated, since is declared
+};
+</pre>
+</div>
+
+<p>
+If you still need to prevent the generation of the default constructor
+or destructor, even when they are declared in the class, you need to
+use the <tt>%ignore</tt> directive.
+</p>
+
 <p>
 <b>Compatibility Note:</b> The generation of default
-constructors/destructors was made the default behavior in SWIG
+constructors/implicit destructors was made the default behavior in SWIG
 1.3.7. This may break certain older modules, but the old behavior can
 be easily restored using <tt>%nodefault</tt> or the
 <tt>-nodefault</tt> command line option.  Furthermore, in order for
@@ -344,6 +415,16 @@ for classes that define a constructor in those sections.  Consider restoring
 those sections in the interface or using <tt>%nodefault</tt> to fix the problem.
 </p>
 
+<p>
+<b>Compatibility Note:</b> Prior to 1.3.28, the <tt>%nodefault</tt>
+directive and the <tt>-nodefault</tt> option also disable the
+generation of the implicit destructors. This produced memory leaks
+across the target langauges in an indiscriminated way. If your
+interface needs the old behavior, use the <tt>-oldnodefault</tt>
+option.
+</p>
+
+
 <H3><a name="SWIGPlus_nn9"></a>6.5.3 When constructor wrappers aren't created</H3>
 
 

SWIG/Lib/swig.swg

@@ -47,13 +47,22 @@
 #define %clearimmutable  %feature("immutable","")
 #define %mutable         %clearimmutable
 
-/* Generation of default constructors/destructors */
+/* Generation of default constructors */
-
 #define %nodefault       %feature("nodefault","1")
 #define %default         %feature("nodefault","0")
 #define %clearnodefault  %feature("nodefault","")
 #define %makedefault     %cleardefault
 
+/* Disable the generation of implicit/default destructor */
+#define %nodefaultdtor       %feature("nodefaultdtor","1")
+#define %defaultdtor         %feature("nodefaultdtor","0")
+#define %clearnodefaultdtor  %feature("nodefaultdtor","")
+
+/* Force the old nodefault behavior */
+#define %oldnodefault       %feature("oldnodefault","1")
+#define %nooldnodefault     %feature("oldnodefault","0")
+#define %clearoldnodefault  %feature("oldnodefault","")
+
 /* the %exception directive */
 
 #ifdef SWIGCSHARP