pythongh-92780: Improve sqlite3.Connection.create_collation docs (pyt…

…honGH-92790)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
(cherry picked from commit 7ee19e2)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>

Doc/library/sqlite3.rst

@@ -518,22 +518,19 @@ Connection Objects
 
  .. method:: create_collation(name, callable)
 
- Creates a collation with the specified *name* and *callable*. The callable will
- be passed two string arguments. It should return -1 if the first is ordered
- lower than the second, 0 if they are ordered equal and 1 if the first is ordered
- higher than the second. Note that this controls sorting (ORDER BY in SQL) so
- your comparisons don't affect other SQL operations.
+ Create a collation named *name* using the collating function *callable*.
+ *callable* is passed two :class:`string <str>` arguments,
+ and it should return an :class:`integer <int>`:
 
- Note that the callable will get its parameters as Python bytestrings, which will
- normally be encoded in UTF-8.
+ * ``1`` if the first is ordered higher than the second
+ * ``-1`` if the first is ordered lower than the second
+ * ``0`` if they are ordered equal
 
- The following example shows a custom collation that sorts "the wrong way":
+ The following example shows a reverse sorting collation:
 
  .. literalinclude:: ../includes/sqlite3/collation_reverse.py
 
- To remove a collation, call ``create_collation`` with ``None`` as callable::
-
- con.create_collation("reverse", None)
+ Remove a collation function by setting *callable* to :const:`None`.
 
  .. versionchanged:: 3.11
  The collation name can contain any Unicode character. Earlier, only