Merge pull request #2278 from gabrieldemarmiesse/transfer_note_from_cinit_and_init

Transfered a note from the reference guide extension types to the userguide.

docs/src/userguide/special_methods.rst

@@ -71,7 +71,18 @@ 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.
+..  Note::
+
+    All constructor arguments will be passed as Python objects.
+    This implies that non-convertible C types such as pointers or C++ objects
+    cannot be passed into the constructor from Cython code.  If this is needed,
+    use a factory function instead that handles the object initialisation.
+    It often helps to directly call ``__new__()`` in this function to bypass the
+    call to the ``__init__()`` constructor.
+
+.. 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