Fix minor details in the Counter docs (GH-31029) (GH-31072)

diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index b8a717d883c0931fe1dca38d8e19071adb82d4b0..b97bc425de9eb9ae74e9c2621e363e838b7e2391 100644 (file)
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -271,7 +271,7 @@ For example::
     .. versionadded:: 3.1
 
     .. versionchanged:: 3.7 As a :class:`dict` subclass, :class:`Counter`
-       Inherited the capability to remember insertion order.  Math operations
+       inherited the capability to remember insertion order.  Math operations
        on *Counter* objects also preserve order.  Results are ordered
        according to when an element is first encountered in the left operand
        and then by the order encountered in the right operand.
@@ -366,19 +366,26 @@ Several mathematical operations are provided for combining :class:`Counter`
 objects to produce multisets (counters that have counts greater than zero).
 Addition and subtraction combine counters by adding or subtracting the counts
 of corresponding elements.  Intersection and union return the minimum and
-maximum of corresponding counts.  Each operation can accept inputs with signed
+maximum of corresponding counts.  Equality and inclusion compare
+corresponding counts.  Each operation can accept inputs with signed
 counts, but the output will exclude results with counts of zero or less.
 
+.. doctest::
+
     >>> c = Counter(a=3, b=1)
     >>> d = Counter(a=1, b=2)
     >>> c + d                       # add two counters together:  c[x] + d[x]
     Counter({'a': 4, 'b': 3})
     >>> c - d                       # subtract (keeping only positive counts)
     Counter({'a': 2})
-    >>> c & d                       # intersection:  min(c[x], d[x]) # doctest: +SKIP
+    >>> c & d                       # intersection:  min(c[x], d[x])
     Counter({'a': 1, 'b': 1})
     >>> c | d                       # union:  max(c[x], d[x])
     Counter({'a': 3, 'b': 2})
+    >>> c == d                      # equality:  c[x] == d[x]
+    False
+    >>> c <= d                      # inclusion:  c[x] <= d[x]
+    False
 
 Unary addition and subtraction are shortcuts for adding an empty counter
 or subtracting from an empty counter.

diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py
index bae0805d6686c5267cad435fac99f08b78bea7bf..818588f7403182b1bf747b3f0d3c9b79b14ef1b3 100644 (file)
--- a/Lib/collections/__init__.py
+++ b/Lib/collections/__init__.py
@@ -766,6 +766,10 @@ class Counter(dict):
     # To strip negative and zero counts, add-in an empty counter:
     #       c += Counter()
     #
+    # Results are ordered according to when an element is first
+    # encountered in the left operand and then by the order
+    # encountered in the right operand.
+    #
     # When the multiplicities are all zero or one, multiset operations
     # are guaranteed to be equivalent to the corresponding operations
     # for regular sets.