Updated pyrex differences and limitations to better reflect current Cython

docs/limitations.rst

@@ -77,10 +77,6 @@ Other Current Limitations
 
 * The :func:`globals` and :func:`locals` functions cannot be used.
 * Class and function definitions cannot be placed inside control structures.
-* Special methods of extension types cannot have functioning docstrings.
-* The use of string literals as comments is not recommended at present,
-  because Cython doesn't optimize them away, and won't even accept them in places
-  where executable statements are not allowed.
 
 Semantic differences between Python and Cython
 ----------------------------------------------

docs/pyrex_differences.rst

@@ -78,6 +78,8 @@ yields::
     6
     8
 
+.. note:: see :ref:`automatic-range-conversion`
+       
 
 Boolean int type (e.g. it acts like a c int, but coerces to/from python as a boolean)
 -------------------------------------------------------------------------------------
@@ -168,7 +170,9 @@ of step) can be determined.
     This may change the semantics if the range causes
     assignment to ``i`` to overflow. Specifically, if this option is set, an error
     will be raised before the loop is entered, whereas without this option the loop
-    will execute until a overflowing value is encountered. 
+    will execute until a overflowing value is encountered. If this effects you
+    change ``Cython/Compiler/Options.py`` (eventually there will be a better
+    way to set this).
 
 More friendly type casting
 --------------------------
@@ -260,3 +264,12 @@ file with an encoding comment and generally write your source code in UTF-8.
 This impacts the encoding of byte strings and the conversion of unicode string
 literals like ``u'abcd'`` to unicode objects.
 
+Automatic ``typecheck``
+========================
+
+Rather than introducing a new keyword :keyword:`typecheck` as explained in the
+`Pyrex docs
+<http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/version/Doc/Manual/special_methods.html>`_,
+Cython emits a (non-spoofable and faster) typecheck whenever
+:func:`isinstance` is used with an extension type as the second parameter.
+