add %delobject docs

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

Doc/Manual/Customization.html

@@ -18,7 +18,7 @@
 <li><a href="#Customization_nn6">Defining different exception handlers</a>
 <li><a href="#Customization_nn7">Using The SWIG exception library</a>
 </ul>
-<li><a href="#ownership">Object ownership and %newobject</a>
+<li><a href="#ownership">Object ownership, %newobject and %delobject </a>
 <li><a href="#features">Features and the %feature directive</a>
 <ul>
 <li><a href="#Customization_feature_flags">Feature flags</a>
@@ -529,6 +529,30 @@ is a copy of the original result, the data returned by <tt>strdup()</tt> is no l
 The "newfree" typemap in the example simply releases this memory.
 </p>
 
+<p>
+As a complement to the <tt>%newobject</tt>, from SWIG 1.3.28, you can
+use the <tt>%delobject</tt> directive. For example, if you have two
+methods, one to create objects and one to destroy them, you can use:
+</p>
+
+<div class="code">
+<pre>
+%newobject create_foo;
+%delobject destroy_foo;
+...
+Foo *create_foo();
+void destroy_foo(Foo *foo);
+</pre>
+</div>
+
+<p>
+which instructs SWIG that the pointer passed <tt>destroy_foo</tt> will
+be destroyed and therefore, the target language should not attemp to
+deallocate it twice. This is similar to the DISOWN typemap, and in
+fact, it also depends on the target language to implement the 'disown'
+mechanism properly.
+</p>
+
 <p>
 <b>Compatibility note:</b>  Previous versions of SWIG had a special <tt>%new</tt> directive.  However, unlike <tt>%newobject</tt>,
 it only applied to the next declaration.  For example: