PYTHON-1109 - Custom type examples are deprecated

behackett · behackett · commit 6e4b54e322bc · 2016-07-05T14:56:44.000-07:00
diff --git a/doc/examples/custom_type.rst b/doc/examples/custom_type.rst
@@ -1,6 +1,26 @@
 Custom Type Example
 ===================
 
+.. warning:: The following examples document a deprecated feature. The
+  :class:`~pymongo.son_manipulator.SONManipulator` API has limitations as a
+  technique for transforming your data. Instead, it is more flexible and
+  straightforward to transform outgoing documents in your own code before
+  passing them to PyMongo, and transform incoming documents after receiving
+  them from PyMongo.
+
+  Thus the :meth:`~pymongo.database.Database.add_son_manipulator` method is
+  deprecated. PyMongo 3's new CRUD API does **not** apply SON manipulators to
+  documents passed to :meth:`~pymongo.collection.Collection.bulk_write`,
+  :meth:`~pymongo.collection.Collection.insert_one`,
+  :meth:`~pymongo.collection.Collection.insert_many`,
+  :meth:`~pymongo.collection.Collection.update_one`, or
+  :meth:`~pymongo.collection.Collection.update_many`. SON manipulators are
+  **not** applied to documents returned by the new methods
+  :meth:`~pymongo.collection.Collection.find_one_and_delete`,
+  :meth:`~pymongo.collection.Collection.find_one_and_replace`, and
+  :meth:`~pymongo.collection.Collection.find_one_and_update`.
+
+
 This is an example of using a custom type with PyMongo. The example
 here is a bit contrived, but shows how to use a
 :class:`~pymongo.son_manipulator.SONManipulator` to manipulate
