Correct notes on customising Python builtin comparison operators

Also add example for python:compare feature

Examples/test-suite/python/python_builtin_runme.py

@@ -45,3 +45,26 @@ if is_python_builtin():
   del d
   if cvar.Dealloc3CalledCount != 1:
     raise RuntimeError("count should be 1")
+
+  # Test 5 for python:compare feature
+  m10 = MyClass(10)
+  m20 = MyClass(20)
+  m15 = MyClass(15)
+
+  if not m10 < m15:
+    raise RuntimeError("m10 < m15")
+  if not m10 < m20:
+    raise RuntimeError("m10 < m20")
+  if not m15 < m20:
+    raise RuntimeError("m15 < m20")
+
+  if m10 > m15:
+    raise RuntimeError("m10 > m15")
+  if m10 > m20:
+    raise RuntimeError("m10 > m20")
+  if m15 > m20:
+    raise RuntimeError("m15 > m20")
+
+  if MyClass.less_than_counts != 6:
+    raise RuntimeError("python:compare feature not working")
+

Examples/test-suite/python_builtin.i

@@ -112,3 +112,19 @@ void Dealloc2Destroyer(PyObject *v) {
 }
 %}
 
+// Test 5 for python:compare feature
+%feature("python:compare", "Py_LT") MyClass::lessThan;
+
+%inline %{
+  class MyClass {
+  public:
+    MyClass(int val = 0) : val(val) {}
+    bool lessThan(const MyClass& other) const {
+      less_than_counts++;
+      return val < other.val;
+    }
+    int val;
+    static int less_than_counts;
+  };
+  int MyClass::less_than_counts = 0;
+%}

Lib/python/pyopers.swg

@@ -18,6 +18,13 @@
  where <slot> is the name of a field in a PyTypeObject, PyNumberMethods,
  PyMappingMethods, PySequenceMethods, or PyBufferProcs.  For example:
 
+   %feature("python:tp_hash") MyClass "myHashFunc";
+
+   class MyClass {
+     public:
+       ...
+   };
+
    %{
      // Note: Py_hash_t was introduced in Python 3.2
      static Py_hash_t myHashFunc(PyObject *pyobj) {
@@ -27,13 +34,6 @@
      }
    %}
 
-   %feature("python:tp_hash") MyClass "myHashFunc";
-
-   class MyClass {
-     public:
-       ...
-   };
-
  NOTE: It is the responsibility of the programmer (that's you) to ensure
  that a statically defined slot function has the correct signature.
 
@@ -62,20 +62,21 @@
  operator overloads for comparison (operator==, operator<, etc.), they
  will be called from the generated rich compare function.  If you
  want to explicitly choose a method to handle a certain comparison
- operation, you may use %feature("python:slot") like this:
+ operation, you may use a different feature, %feature("python:compare")
+ like this:
+
+   %feature("python:compare", "Py_LT") MyClass::lessThan;
 
    class MyClass {
      public:
-       bool lessThan (const MyClass& x) const;
+       bool lessThan(const MyClass& other) const;
        ...
    };
    
-   %feature("python:slot", "Py_LT") MyClass::lessThan;
-
  ... where "Py_LT" is one of the rich comparison opcodes defined in the
  python header file object.h.
 
- If there's no method defined to handle a particular comparsion operation,
+ If there's no method defined to handle a particular comparison operation,
  the default behavior is to compare pointer values of the wrapped
  C++ objects.