add more docs

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

CHANGES.current

@@ -1,6 +1,50 @@
 Version 1.3.28 (unreleased).
 ===========================
 
+01/24/2006: mmatus
+	    - Better support for the %naturalvar directive, now it
+	      works along the scripting languages as well as
+	      java/csharp.
+	      
+	      Now, it can also be applied to class types:
+
+	        %naturalvar std::string;
+	        %include <std_string.i>
+	      
+              that will tell swig to use the the 'natural' wrapping
+              mechanism to all std::string global and member
+              variables. Just remember to use the directive before
+	      the class declaration.
+
+	    - Add support for the %allowexcept feature along the
+              scripting languages, which allows the %exception feature
+              to be applied to the variable access methods. Also, add
+              the %exceptionvar directive to specify a distintic
+              exception mechanism only for variables.
+	      
+	    
+	    - Add more docs for the %delobject directive to mark a method as a
+	      destructor, 'disowning' the first argument. For example:
+
+	        %newobject create_foo;
+	        %delobject destroy_foo;
+
+	        Foo *create_foo() { return new Foo(); }
+	        void destroy_foo(Foo *foo) { delete foo; }
+
+	      or in a member method as:
+
+	        %delobject Foo::destroy;
+
+	        class Foo {
+	        public:
+	          void destroy() { delete this;}
+
+	        private:
+	          ~Foo();
+               };
+
+
 01/24/2006: mgossage
             [Lua]
 	    - Removed the type swig_lua_command_info & replace with luaL_reg
@@ -10,7 +54,7 @@ Version 1.3.28 (unreleased).
 	      a double to an enum directly. Therefore cast to int then to enum
 	      (thenks to Jason Rego for this observation)
 
-01/16/2006: mmatus (Change disabled)
+01/16/2006: mmatus (Change disabled... will be back in CVS soon)
 	    Add initial support for regexp via the external library
 	    RxSpencer. SWIG doesn't require this library to compile
 	    and/or run. But if you specify --with-rxspencer, and the
@@ -672,11 +716,6 @@ Version 1.3.28 (unreleased).
 
 	      %naturalvar Bar::s;
 	    
-            or specific classes:
-	    
-	      %naturalvar std::string;
-	      %include <std_string.i>
-	      
 	    Then, in the following case for example:
 
 	       std::string s;

Doc/Manual/Customization.html

@@ -545,12 +545,28 @@ void destroy_foo(Foo *foo);
 </pre>
 </div>
 
+<p> or in a member method as: </p>
+<div class="code">
+<pre>
+%delobject Foo::destroy;
+
+class Foo {
+public:
+  void destroy() { delete this;}
+
+private:
+  ~Foo();
+};
+</pre>
+</div>
+
 <p>
-which instructs SWIG that the pointer passed to <tt>destroy_foo</tt> will
-be destroyed, and therefore, the target language should not attempt 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.
+<tt>%delobject</tt> instructs SWIG that the first argument passed to
+the method will be destroyed, and therefore, the target language
+should not attempt to deallocate it twice. This is similar to use the
+DISOWN typemap in the first method argument, and in fact, it also
+depends on the target language to implement the 'disown' mechanism
+properly.
 </p>
 
 <p>

README

@@ -77,22 +77,41 @@ SWIG-1.3.28 summary:
 - New language module: Common Lisp with CFFI.
 - More powerful renaming (%rename) capability.
 - More user friendly warning handling.
-- Initial GCJ/Java to scripting language support.
+- Add finer control for default constructors and destructors. We discourage
+  the use of the 'nodefault' option, which disable both constructors and
+  destructors, leading to possible memory leaks. Use instead 'nodefaultctor'
+  and/or 'nodefaultdtor'.
 - Optional automatic copy constructor wrapper generation.
-- Explicit conversions (python).
+- Python implicit conversion mechanism similar to C++, via the %implicitconv
+  directive (replaces and improves the implicit.i library). 
 - Python threading support added.
 - Support for Ruby bang methods.
 - Better handling of std::string variables.
 - Unified typemap library (UTL) potentially providing core typemaps for all
   scripting languages based on the recently evolving Python typemaps.
-- Python, Ruby, Perl and Tcl using using the UTL.
+- Python, Ruby, Perl and Tcl use the new UTL.
+- Initial GCJ/Java support for languages using the UTL.
 - Improved dispatching in overloaded functions by using a cast and rank
-  mechanism.
+  mechanism in perl and optionally in python via the -castmode option.
 - Better handling of Windows extensions and types.
 - C++ support added to the Allegrocl module, also enhanced C support.
-- Python STL support improved, eg performance improvements and addition of
-  iterators and STL containers of native Python types.
+- Python STL support improved, addition of iterators and STL containers of 
+  native Python types.
+- Python performance options and improvements, try the -O option to test
+  all of them. Python runtime benchmarks shows upto 20 times better performance
+  compared to 1.3.27 and older versions.
+- Python support for 'multi-inheritance' at the python side.
+- Python simplified proxy classes, now swig doesn't need to generate the auxiliar
+  'ClassPtr' clasess.
+- Python backward compatibility improved, many projects that used to work
+  only with  swig-1.3.21 to swig-1.3.24 are working again with swig-1.3.28
 - Better runtime error reporting.
+- Add the %catches directive to catch and dispatch exceptions.
+- Add the %naturalval directive for more 'natural' variable wrapping.
+- Add the %allowexcept and %exceptionvar directives to handle exceptions when
+  accesing a variable.
+- Add the %delobject directive to mark methods that act like destructors.
+- Add/doc more debug options.
 - Minor bug fixes and improvements to the Lua, Ruby, Java, C#, Python, Guile,
   Chicken, Tcl and Perl modules.