Propose a contract for Key.parent.

gcloud/datastore/key.py

@@ -33,6 +33,9 @@ def _clone(self):
     We make a shallow copy of the :class:`gcloud.datastore.dataset.Dataset`
     because it holds a reference an authenticated connection,
     which we don't want to lose.
+
+    :rtype: :class:`gcloud.datastore.key.Key`
+    :returns: a new `Key` instance
     """
     clone = copy.deepcopy(self)
     clone._dataset = self._dataset  # Make a shallow copy of the Dataset.
@@ -259,7 +262,12 @@ def id_or_name(self):
     return self.id() or self.name()
 
   def parent(self):#pragma NO COVER
-    # See https://github.com/GoogleCloudPlatform/gcloud-python/issues/135
+    """Getter:  return a new key for the next highest elemen in path.
+
+    :rtype: :class:`gcloud.datastore.key.Key`
+    :returns: a new `Key` instance, whose path consists of all but the last
+    element of self's path.  If self has only one path element, return None.
+    """
     raise NotImplementedError
 
   def __repr__(self): #pragma NO COVER