gh-144837: Improve documentation for more collection methods

Doc/library/array.rst

@@ -112,9 +112,9 @@ The module defines the following type:
       The length in bytes of one array item in the internal representation.
 
 
-   .. method:: append(x)
+   .. method:: append(value, /)
 
-      Append a new item with value *x* to the end of the array.
+      Append a new item with the specified value to the end of the array.
 
 
    .. method:: buffer_info()
@@ -144,20 +144,20 @@ The module defines the following type:
       different byte order.
 
 
-   .. method:: count(x)
+   .. method:: count(value, /)
 
-      Return the number of occurrences of *x* in the array.
+      Return the number of occurrences of *value* in the array.
 
 
-   .. method:: extend(iterable)
+   .. method:: extend(iterable, /)
 
       Append items from *iterable* to the end of the array.  If *iterable* is another
       array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
       be raised.  If *iterable* is not an array, it must be iterable and its elements
       must be the right type to be appended to the array.
 
 
-   .. method:: frombytes(buffer)
+   .. method:: frombytes(buffer, /)
 
       Appends items from the :term:`bytes-like object`, interpreting
       its content as an array of machine values (as if it had been read
@@ -167,55 +167,55 @@ The module defines the following type:
          :meth:`!fromstring` is renamed to :meth:`frombytes` for clarity.
 
 
-   .. method:: fromfile(f, n)
+   .. method:: fromfile(f, n, /)
 
       Read *n* items (as machine values) from the :term:`file object` *f* and append
       them to the end of the array.  If less than *n* items are available,
       :exc:`EOFError` is raised, but the items that were available are still
       inserted into the array.
 
 
-   .. method:: fromlist(list)
+   .. method:: fromlist(list, /)
 
       Append items from the list.  This is equivalent to ``for x in list:
       a.append(x)`` except that if there is a type error, the array is unchanged.
 
 
-   .. method:: fromunicode(s)
+   .. method:: fromunicode(ustr, /)
 
       Extends this array with data from the given Unicode string.
       The array must have type code ``'u'`` or ``'w'``; otherwise a :exc:`ValueError` is raised.
       Use ``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to an
       array of some other type.
 
 
-   .. method:: index(x[, start[, stop]])
+   .. method:: index(value[, start[, stop]])
 
       Return the smallest *i* such that *i* is the index of the first occurrence of
-      *x* in the array.  The optional arguments *start* and *stop* can be
-      specified to search for *x* within a subsection of the array.  Raise
-      :exc:`ValueError` if *x* is not found.
+      *value* in the array.  The optional arguments *start* and *stop* can be
+      specified to search for *value* within a subsection of the array.  Raise
+      :exc:`ValueError` if *value* is not found.
 
       .. versionchanged:: 3.10
          Added optional *start* and *stop* parameters.
 
 
-   .. method:: insert(i, x)
+   .. method:: insert(index, value, /)
 
-      Insert a new item with value *x* in the array before position *i*. Negative
+      Insert a new item *value* in the array before position *index*. Negative
       values are treated as being relative to the end of the array.
 
 
-   .. method:: pop([i])
+   .. method:: pop(index=-1, /)
 
       Removes the item with the index *i* from the array and returns it. The optional
       argument defaults to ``-1``, so that by default the last item is removed and
       returned.
 
 
-   .. method:: remove(x)
+   .. method:: remove(value, /)
 
-      Remove the first occurrence of *x* from the array.
+      Remove the first occurrence of *value* from the array.
 
 
    .. method:: clear()
@@ -240,7 +240,7 @@ The module defines the following type:
          :meth:`!tostring` is renamed to :meth:`tobytes` for clarity.
 
 
-   .. method:: tofile(f)
+   .. method:: tofile(f, /)
 
       Write all items (as machine values) to the :term:`file object` *f*.
 

Doc/library/collections.rst

@@ -240,7 +240,9 @@ For example::
     [('the', 1143), ('and', 966), ('to', 762), ('of', 669), ('i', 631),
      ('you', 554),  ('a', 546), ('my', 514), ('hamlet', 471), ('in', 451)]
 
-.. class:: Counter([iterable-or-mapping])
+.. class:: Counter(**kwargs)
+           Counter(iterable, /, **kwargs)
+           Counter(mapping, /, **kwargs)
 
     A :class:`Counter` is a :class:`dict` subclass for counting :term:`hashable` objects.
     It is a collection where elements are stored as dictionary keys
@@ -290,7 +292,7 @@ For example::
             >>> sorted(c.elements())
             ['a', 'a', 'a', 'a', 'b', 'b']
 
-    .. method:: most_common([n])
+    .. method:: most_common(n=None)
 
         Return a list of the *n* most common elements and their counts from the
         most common to the least.  If *n* is omitted or ``None``,
@@ -300,7 +302,9 @@ For example::
             >>> Counter('abracadabra').most_common(3)
             [('a', 5), ('b', 2), ('r', 2)]
 
-    .. method:: subtract([iterable-or-mapping])
+    .. method:: subtract(**kwargs)
+                subtract(iterable, /, **kwargs)
+                subtract(mapping, /, **kwargs)
 
         Elements are subtracted from an *iterable* or from another *mapping*
         (or counter).  Like :meth:`dict.update` but subtracts counts instead
@@ -331,7 +335,9 @@ For example::
 
         This class method is not implemented for :class:`Counter` objects.
 
-    .. method:: update([iterable-or-mapping])
+    .. method:: update(**kwargs)
+                update(iterable, /, **kwargs)
+                update(mapping, /, **kwargs)
 
         Elements are counted from an *iterable* or added-in from another
         *mapping* (or counter).  Like :meth:`dict.update` but adds counts
@@ -484,14 +490,14 @@ or subtracting from an empty counter.
 
     Deque objects support the following methods:
 
-    .. method:: append(x)
+    .. method:: append(item, /)
 
-        Add *x* to the right side of the deque.
+        Add *item* to the right side of the deque.
 
 
-    .. method:: appendleft(x)
+    .. method:: appendleft(item, /)
 
-        Add *x* to the left side of the deque.
+        Add *item* to the left side of the deque.
 
 
     .. method:: clear()
@@ -506,38 +512,38 @@ or subtracting from an empty counter.
         .. versionadded:: 3.5
 
 
-    .. method:: count(x)
+    .. method:: count(value, /)
 
-        Count the number of deque elements equal to *x*.
+        Count the number of deque elements equal to *value*.
 
         .. versionadded:: 3.2
 
 
-    .. method:: extend(iterable)
+    .. method:: extend(iterable, /)
 
         Extend the right side of the deque by appending elements from the iterable
         argument.
 
 
-    .. method:: extendleft(iterable)
+    .. method:: extendleft(iterable, /)
 
         Extend the left side of the deque by appending elements from *iterable*.
         Note, the series of left appends results in reversing the order of
         elements in the iterable argument.
 
 
-    .. method:: index(x[, start[, stop]])
+    .. method:: index(value[, start[, stop]])
 
-        Return the position of *x* in the deque (at or after index *start*
+        Return the position of *value* in the deque (at or after index *start*
         and before index *stop*).  Returns the first match or raises
         :exc:`ValueError` if not found.
 
         .. versionadded:: 3.5
 
 
-    .. method:: insert(i, x)
+    .. method:: insert(index, value, /)
 
-        Insert *x* into the deque at position *i*.
+        Insert *value* into the deque at position *index*.
 
         If the insertion would cause a bounded deque to grow beyond *maxlen*,
         an :exc:`IndexError` is raised.
@@ -557,7 +563,7 @@ or subtracting from an empty counter.
         elements are present, raises an :exc:`IndexError`.
 
 
-    .. method:: remove(value)
+    .. method:: remove(value, /)
 
         Remove the first occurrence of *value*.  If not found, raises a
         :exc:`ValueError`.
@@ -570,7 +576,7 @@ or subtracting from an empty counter.
         .. versionadded:: 3.2
 
 
-    .. method:: rotate(n=1)
+    .. method:: rotate(n=1, /)
 
         Rotate the deque *n* steps to the right.  If *n* is negative, rotate
         to the left.
@@ -722,7 +728,9 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
 :class:`defaultdict` objects
 ----------------------------
 
-.. class:: defaultdict(default_factory=None, /, [...])
+.. class:: defaultdict(default_factory=None, /, **kwargs)
+           defaultdict(default_factory, mapping, /, **kwargs)
+           defaultdict(default_factory, iterable, /, **kwargs)
 
     Return a new dictionary-like object.  :class:`defaultdict` is a subclass of the
     built-in :class:`dict` class.  It overrides one method and adds one writable
@@ -738,7 +746,7 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
     :class:`defaultdict` objects support the following method in addition to the
     standard :class:`dict` operations:
 
-    .. method:: __missing__(key)
+    .. method:: __missing__(key, /)
 
         If the :attr:`default_factory` attribute is ``None``, this raises a
         :exc:`KeyError` exception with the *key* as argument.
@@ -944,7 +952,7 @@ In addition to the methods inherited from tuples, named tuples support
 three additional methods and two attributes.  To prevent conflicts with
 field names, the method and attribute names start with an underscore.
 
-.. classmethod:: somenamedtuple._make(iterable)
+.. classmethod:: somenamedtuple._make(iterable, /)
 
     Class method that makes a new instance from an existing sequence or iterable.
 
@@ -1141,7 +1149,9 @@ Some differences from :class:`dict` still remain:
 * Until Python 3.8, :class:`dict` lacked a :meth:`~object.__reversed__` method.
 
 
-.. class:: OrderedDict([items])
+.. class:: OrderedDict(**kwargs)
+           OrderedDict(mapping, /, **kwargs)
+           OrderedDict(iterable, /, **kwargs)
 
     Return an instance of a :class:`dict` subclass that has methods
     specialized for rearranging dictionary order.
@@ -1322,13 +1332,14 @@ subclass directly from :class:`dict`; however, this class can be easier
 to work with because the underlying dictionary is accessible as an
 attribute.
 
-.. class:: UserDict([initialdata])
+.. class:: UserDict(**kwargs)
+           UserDict(mapping, /, **kwargs)
+           UserDict(iterable, /, **kwargs)
 
     Class that simulates a dictionary.  The instance's contents are kept in a
     regular dictionary, which is accessible via the :attr:`data` attribute of
-    :class:`UserDict` instances.  If *initialdata* is provided, :attr:`data` is
-    initialized with its contents; note that a reference to *initialdata* will not
-    be kept, allowing it to be used for other purposes.
+    :class:`UserDict` instances.  If arguments are provided, they are used to
+    initialize :attr:`data`, like a regular dictionary.
 
     In addition to supporting the methods and operations of mappings,
     :class:`UserDict` instances provide the following attribute:

Doc/tutorial/datastructures.rst

@@ -15,35 +15,35 @@ More on Lists
 The :ref:`list <typesseq-list>` data type has some more methods. Here are all
 of the methods of list objects:
 
-.. method:: list.append(x)
+.. method:: list.append(value, /)
    :noindex:
 
    Add an item to the end of the list.  Similar to ``a[len(a):] = [x]``.
 
 
-.. method:: list.extend(iterable)
+.. method:: list.extend(iterable, /)
    :noindex:
 
    Extend the list by appending all the items from the iterable.  Similar to
    ``a[len(a):] = iterable``.
 
 
-.. method:: list.insert(i, x)
+.. method:: list.insert(index, value, /)
    :noindex:
 
    Insert an item at a given position.  The first argument is the index of the
    element before which to insert, so ``a.insert(0, x)`` inserts at the front of
    the list, and ``a.insert(len(a), x)`` is equivalent to ``a.append(x)``.
 
 
-.. method:: list.remove(x)
+.. method:: list.remove(value, /)
    :noindex:
 
-   Remove the first item from the list whose value is equal to *x*.  It raises a
+   Remove the first item from the list whose value is equal to *value*.  It raises a
    :exc:`ValueError` if there is no such item.
 
 
-.. method:: list.pop([i])
+.. method:: list.pop(index=-1, /)
    :noindex:
 
    Remove the item at the given position in the list, and return it.  If no index
@@ -58,10 +58,10 @@ of the methods of list objects:
    Remove all items from the list.  Similar to ``del a[:]``.
 
 
-.. method:: list.index(x[, start[, end]])
+.. method:: list.index(value[, start[, stop])
    :noindex:
 
-   Return zero-based index of the first occurrence of *x* in the list.
+   Return zero-based index of the first occurrence of *value* in the list.
    Raises a :exc:`ValueError` if there is no such item.
 
    The optional arguments *start* and *end* are interpreted as in the slice
@@ -70,10 +70,10 @@ of the methods of list objects:
    sequence rather than the *start* argument.
 
 
-.. method:: list.count(x)
+.. method:: list.count(value, /)
    :noindex:
 
-   Return the number of times *x* appears in the list.
+   Return the number of times *value* appears in the list.
 
 
 .. method:: list.sort(*, key=None, reverse=False)