[Zodb-checkins] CVS: Zope3/lib/python/Persistence/BTrees - BucketTemplate.c:1.1.2.27

[Tim Peters]

Update of /cvs-repository/Zope3/lib/python/Persistence/BTrees
In directory cvs.zope.org:/tmp/cvs-serv5648

Modified Files:
      Tag: Zope-3x-branch
	BucketTemplate.c 
Log Message:
Bring the _bucket_get comments into line with reality.


=== Zope3/lib/python/Persistence/BTrees/BucketTemplate.c 1.1.2.26 => 1.1.2.27 ===
 ** _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 true 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)
 {