__new__ clarification

diff --git a/docs/sharing_declarations.rst b/docs/sharing_declarations.rst
index cb7453015f0fe9d169a08d1544951eed326f300b..ac01815bdccf7821ab07b09f6e22a94fd6e93636 100644 (file)
--- a/docs/sharing_declarations.rst
+++ b/docs/sharing_declarations.rst
@@ -212,7 +212,7 @@ and another module which uses it.::
         
     # Shrubbing.pyx
     cdef class Shrubbery:
-        def __new__(self, int w, int l):
+        def __cinit__(self, int w, int l):
             self.width = w
             self.length = l
 

diff --git a/docs/special_methods.rst b/docs/special_methods.rst
index 1cd20b52e90c9795cf05b36276fce1a540f92506..2186ad5d95e3d8702a37b94f5874ee8543fe81b6 100644 (file)
--- a/docs/special_methods.rst
+++ b/docs/special_methods.rst
@@ -65,12 +65,20 @@ subclassing your extension type in Python, you may find it useful to give the
 :meth:`__cinit__` method `*` and `**` arguments so that it can accept and
 ignore extra arguments. Otherwise, any Python subclass which has an
 :meth:`__init__` with a different signature will have to override
-:meth:`__new__` as well as :meth:`__init__`, which the writer of a Python
-class wouldn't expect to have to do.  As a convenience, if you declare
+:meth:`__new__`[#] as well as :meth:`__init__`, which the writer of a Python
+class wouldn't expect to have to do.  Alternatively, as a convenience, if you declare
 your :meth:`__cinit__`` method to take no arguments (other than self) it 
 will simply ignore any extra arguments passed to the constructor without
 complaining about the signature mismatch. 
 
+.. Note: Older Cython files may use :meth:`__new__` rather than :meth:`__cinit__`. The two are synonyms. 
+  The name change from :meth:`__new__` to :meth:`__cinit__` was to avoid 
+  confusion with Python :meth:`__new__` (which is an entirely different 
+  concept) and eventually the use of :meth:`__new__` in Cython will be 
+  disallowed to pave the way for supporting Python-style :meth:`__new__`  
+
+.. [#] http://docs.python.org/reference/datamodel.html#object.__new__
+
 Finalization method: :meth:`__dealloc__`
 ----------------------------------------