No code change -- just trying to document the return conditions for all

the internal comparison routines.

Objects/object.c

@@ -723,6 +723,13 @@ delete_token(PyObject *token)
 	Py_DECREF(token);
 }
 
+/* Compare v to w.  Return
+   -1 if v <  w or exception (PyErr_Occurred() true in latter case).
+    0 if v == w.
+    1 if v > w.
+   XXX The docs (C API manual) say the return value is undefined in case
+   XXX of error.
+*/
 int
 PyObject_Compare(PyObject *v, PyObject *w)
 {
@@ -771,6 +778,7 @@ PyObject_Compare(PyObject *v, PyObject *w)
 	return result < 0 ? -1 : result;
 }
 
+/* Return (new reference to) Py_True or Py_False. */
 static PyObject *
 convert_3way_to_object(int op, int c)
 {
@@ -788,7 +796,12 @@ convert_3way_to_object(int op, int c)
 	return result;
 }
 	
-
+/* We want a rich comparison but don't have one.  Try a 3-way cmp instead.
+   Return
+   NULL      if error
+   Py_True   if v op w
+   Py_False  if not (v op w)
+*/
 static PyObject *
 try_3way_to_rich_compare(PyObject *v, PyObject *w, int op)
 {
@@ -802,6 +815,12 @@ try_3way_to_rich_compare(PyObject *v, PyObject *w, int op)
 	return convert_3way_to_object(op, c);
 }
 
+/* Do rich comparison on v and w.  Return
+   NULL      if error
+   Else a new reference to an object other than Py_NotImplemented, usually(?):
+   Py_True   if v op w
+   Py_False  if not (v op w)
+*/
 static PyObject *
 do_richcmp(PyObject *v, PyObject *w, int op)
 {
@@ -841,6 +860,13 @@ do_richcmp(PyObject *v, PyObject *w, int op)
 	return try_3way_to_rich_compare(v, w, op);
 }
 
+/* Return:
+   NULL for exception;
+   NotImplemented if this particular rich comparison is not implemented or
+     undefined;
+   some object not equal to NotImplemented if it is implemented
+     (this latter object may not be a Boolean).
+*/
 PyObject *
 PyObject_RichCompare(PyObject *v, PyObject *w, int op)
 {