Update docs wrt property syntax deprecation

docs/src/reference/extension_types.rst

@@ -81,7 +81,7 @@ Methods
 Properties
 ==========
 
-* Cython provides a special syntax::
+* Cython provides a special (deprecated) syntax::
 
     cdef class Spam:
 
@@ -120,7 +120,7 @@ Properties
             def __cinit__(self):
                 self.cheeses = []
 
-            property cheese:
+            property cheese:   # note that this syntax is deprecated
 
                 def __get__(self):
                     return "We don't have: %s" % self.cheeses

docs/src/tutorial/cdef_classes.rst

@@ -138,9 +138,10 @@ Attributes in cdef classes behave differently from attributes in regular classes
       # Available in Python-space:
       cdef public double freq
       # Available in Python-space:
-      property period:
-          def __get__(self):
+      @property
+      def period(self):
           return 1.0 / self.freq
-          def __set__(self, value):
+      @period.setter
+      def period(self, value):
           self.freq = 1.0 / value
       <...>

docs/src/userguide/extension_types.rst

@@ -223,7 +223,26 @@ extension types.
 Properties
 ============
 
-There is a special syntax for defining properties in an extension class::
+You can declare properties in an extension class using the same syntax as in ordinary Python code::
+
+    cdef class Spam:
+
+        @property
+        def cheese(self):
+            # This is called when the property is read.
+            ...
+
+        @cheese.setter
+        def cheese(self, value):
+                # This is called when the property is written.
+                ...
+
+        @cheese.deleter
+        def cheese(self):
+            # This is called when the property is deleted.
+
+
+There is also a special (deprecated) legacy syntax for defining properties in an extension class::
 
     cdef class Spam:
 
@@ -259,15 +278,16 @@ when it is deleted.::
         def __cinit__(self):
             self.cheeses = []
 
-        property cheese:
-
-            def __get__(self):
+        @property
+        def cheese(self):
             return "We don't have: %s" % self.cheeses
 
-            def __set__(self, value):
+        @cheese.setter
+        def cheese(self):
             self.cheeses.append(value)
 
-            def __del__(self):
+        @cheese.deleter
+        def cheese(self):
             del self.cheeses[:]
 
     # Test input