PEP 851: Clarify a few things around set symmetry

peps/pep-0851.rst

@@ -15,8 +15,9 @@ Abstract
 
 Add ``list.discard(x)``, which removes the first item equal to *x* if one
 is present and does nothing otherwise, returning whether an item was
-removed. It is the non-raising counterpart to :meth:`list.remove`, as
-:meth:`set.discard` is to :meth:`set.remove`.
+removed. It is the non-raising counterpart to :meth:`list.remove`, which
+currently has none. The name is taken from :meth:`set.discard`, which
+already means "remove if present" in Python.
 
 
 Motivation
@@ -79,16 +80,15 @@ method for consistency.
 Rationale
 =========
 
-The name follows the ``remove()`` / ``discard()`` distinction already
-made by ``set``, where ``discard()`` is the variant that tolerates a
-missing item. It has been raised that after ``s.discard(x)`` the test
-``x not in s`` holds, while after ``lst.discard(x)`` it need not if *x*
-appears more than once. This is a real difference. ``discard()``
-deliberately shares the search and removal semantics of :meth:`list.remove`
-rather than those of :meth:`set.discard`, and the documentation for
-``list.discard()`` in the reference implementation states this explicitly.
-The name remains the least surprising choice as users who know
-sets can apply that knowledge directly.
+Symmetry with :class:`set` is not the goal. The motivation is the missing
+non-raising form of :meth:`list.remove`. :class:`set` only supplies the name,
+since :meth:`set.discard` already means "remove if present" in Python.
+
+It has been raised that after ``s.discard(x)`` the test ``x not in s``
+holds, while after ``lst.discard(x)`` it need not if *x* appears more than
+once. That is a property of sets, not of ``discard()``, and
+:meth:`list.remove` has the same behaviour today. ``discard()`` follows
+``remove()`` here, and its will documentation clearly say so.
 
 Unlike :meth:`set.discard`, which returns ``None``, a bool is returned. This
 costs nothing, since the implementation already knows the outcome, and lets