Issue #23006: Improve the documentation and indexing of dict.__missing__.

Add an entry in the language datamodel special methods section.
Revise and index its discussion in the stdtypes mapping/dict section.

3 files changed, 18 insertions, 5 deletions

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 3f09b19..e076cbb 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -3761,11 +3761,13 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
       Return the item of *d* with key *key*.  Raises a :exc:`KeyError` if *key* is
       not in the map.
 
-      If a subclass of dict defines a method :meth:`__missing__`, if the key *key*
+	  .. index:: __missing__()
+
+      If a subclass of dict defines a method :meth:`__missing__` and *key*
       is not present, the ``d[key]`` operation calls that method with the key *key*
       as argument.  The ``d[key]`` operation then returns or raises whatever is
-      returned or raised by the ``__missing__(key)`` call if the key is not
-      present. No other operations or methods invoke :meth:`__missing__`. If
+      returned or raised by the ``__missing__(key)`` call.
+      No other operations or methods invoke :meth:`__missing__`. If
       :meth:`__missing__` is not defined, :exc:`KeyError` is raised.
       :meth:`__missing__` must be a method; it cannot be an instance variable::
 
@@ -3779,8 +3781,9 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
           >>> c['red']
           1
 
-      See :class:`collections.Counter` for a complete implementation including
-      other methods helpful for accumulating and managing tallies.
+      The example above shows part of the implementation of
+      :class:`collections.Counter`.  A different ``__missing__`` method is used
+      by :class:`collections.defaultdict`.
 
    .. describe:: d[key] = value
 
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 618c257..d0eede7 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1904,6 +1904,12 @@ through the container; for mappings, :meth:`__iter__` should be the same as
       indexes to allow proper detection of the end of the sequence.
 
 
+.. method:: object.__missing__(self, key)
+
+   Called by :class:`dict`\ .\ :meth:`__getitem__` to implement ``self[key]`` for dict subclasses
+   when key is not in the dictionary.
+
+
 .. method:: object.__setitem__(self, key, value)
 
    Called to implement assignment to ``self[key]``.  Same note as for
diff --git a/Misc/NEWS b/Misc/NEWS
index d4cd62e..8a6fd24 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -9474,6 +9474,10 @@ C-API
 Documentation
 -------------
 
+- Issue #23006: Improve the documentation and indexing of dict.__missing__.
+  Add an entry in the language datamodel special methods section.
+  Revise and index its discussion in the stdtypes mapping/dict section.
+
 - Issue #13989: Document that GzipFile does not support text mode, and give a
   more helpful error message when opened with an invalid mode string.