Update docs wrt property syntax deprecation

3 files changed, 37 insertions, 16 deletions

diff --git a/docs/src/reference/extension_types.rst b/docs/src/reference/extension_types.rst
index be5636739..378221536 100644
--- a/docs/src/reference/extension_types.rst
+++ b/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
diff --git a/docs/src/tutorial/cdef_classes.rst b/docs/src/tutorial/cdef_classes.rst
index 8c8761df9..93fd6cfc8 100644
--- a/docs/src/tutorial/cdef_classes.rst
+++ b/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):
-              return 1.0 / self.freq
-          def __set__(self, value):
-              self.freq = 1.0 / value
+      @property
+      def period(self):
+          return 1.0 / self.freq
+      @period.setter
+      def period(self, value):
+          self.freq = 1.0 / value
       <...>
diff --git a/docs/src/userguide/extension_types.rst b/docs/src/userguide/extension_types.rst
index 1aa58f05a..75c79913d 100644
--- a/docs/src/userguide/extension_types.rst
+++ b/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,16 +278,17 @@ when it is deleted.::
         def __cinit__(self):
             self.cheeses = []
 
-        property cheese:
+        @property
+        def cheese(self):
+            return "We don't have: %s" % self.cheeses
 
-            def __get__(self):
-                return "We don't have: %s" % self.cheeses
+        @cheese.setter
+        def cheese(self):
+            self.cheeses.append(value)
 
-            def __set__(self, value):
-                self.cheeses.append(value)
-
-            def __del__(self):
-                del self.cheeses[:]
+        @cheese.deleter
+        def cheese(self):
+            del self.cheeses[:]
 
     # Test input
     from cheesy import CheeseShop