Update doctstrings for 'Entity.save' and 'Connection.save_entity'.

tseaver · tseaver · commit 8e40313abf0b · 2014-10-17T13:17:21.000-04:00
Reinforce that previously-stored properties which don't have values set
in the current entity instance will be removed.
diff --git a/gcloud/datastore/connection.py b/gcloud/datastore/connection.py
@@ -339,8 +339,9 @@ def save_entity(self, dataset_id, key_pb, properties):
         """Save an entity to the Cloud Datastore with the provided properties.
 
         .. note::
-           Any existing properties for the entity will be cleared before
-           applying those passed in 'properties'.
+           Any existing properties for the entity identified by 'key_pb'
+           will be replaced by those passed in 'properties';  properties
+           not passed in 'properties' no longer be set for the entity.
 
         :type dataset_id: string
         :param dataset_id: The dataset in which to save the entity.
diff --git a/gcloud/datastore/entity.py b/gcloud/datastore/entity.py
@@ -187,6 +187,12 @@ def reload(self):
     def save(self):
         """Save the entity in the Cloud Datastore.
 
+        .. note::
+           Any existing properties for the entity will be replaced by those
+           currently set on this instance.  Already-stored properties which do
+           not correspond to keys set on this instance will be removed from
+           the datastore.
+
         :rtype: :class:`gcloud.datastore.entity.Entity`
         :returns: The entity with a possibly updated Key.
         """
