[Zope-Checkins] CVS: Zope/lib/python/BTrees - BucketTemplate.c:1.35

[Tim Peters]

Update of /cvs-repository/Zope/lib/python/BTrees
In directory cvs.zope.org:/tmp/cvs-serv19974

Modified Files:
	BucketTemplate.c 
Log Message:
Brought the _bucket_get comments into synch with what the code actually
does.


=== Zope/lib/python/BTrees/BucketTemplate.c 1.34 => 1.35 ===
 ** _bucket_get
 **
-** Get the bucket item with the matching key
+** Search a bucket for a given key.
 **
-** Arguments:	self	The bucket
-**		key	The key to match against
-**		has_key	Just return object "1" if key found, object "0" if not
+** Arguments
+**     self	The bucket
+**     keyarg	The key to look for
+**     has_key	Boolean; if true, return a true/false result; else return
+**              the value associated with the key.
 **
-** Returns:	object	matching object or 0/1 object
+** Return
+**     If has_key:
+**         Returns the Python int 0 if the key is absent, else returns
+**         has_key itself as a Python int.  A BTree caller generally passes
+**         the depth of the bucket for has_key, so a true result returns
+**         the bucket depth then.
+**         Note that has_key should be tree when searching set buckets.
+**     If not has_key:
+**         If the key is present, returns the associated value, and the
+**         caller owns the reference.  Else returns NULL and sets KeyError.
+**     Whether or not has_key:
+**         If a comparison sets an exception, returns NULL.
 */
-
-
 static PyObject *
 _bucket_get(Bucket *self, PyObject *keyarg, int has_key)
 {