[Python-checkins] bpo-46076: Improve documentation for per-attribute docstrings with `__slots__` (GH-30109)

[rhettinger]

https://github.com/python/cpython/commit/aeb9ef4c7287fe367b6e9adcf1c5f994d5bc1a09
commit: aeb9ef4c7287fe367b6e9adcf1c5f994d5bc1a09
branch: main
author: Alex Waygood <Alex.Waygood at Gmail.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2021-12-19T14:20:07-06:00
summary:

bpo-46076: Improve documentation for per-attribute docstrings with `__slots__` (GH-30109)

files:
M Doc/reference/datamodel.rst

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index aa0d91ad1c97d..48c54d729424c 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1944,9 +1944,12 @@ Notes on using *__slots__*
 * Nonempty *__slots__* does not work for classes derived from "variable-length"
   built-in types such as :class:`int`, :class:`bytes` and :class:`tuple`.
 
-* Any non-string iterable may be assigned to *__slots__*. Mappings may also be
-  used; however, in the future, special meaning may be assigned to the values
-  corresponding to each key.
+* Any non-string :term:`iterable` may be assigned to *__slots__*.
+
+* If a :class:`dictionary <dict>` is used to assign *__slots__*, the dictionary
+  keys will be used as the slot names. The values of the dictionary can be used
+  to provide per-attribute docstrings that will be recognised by
+  :func:`inspect.getdoc` and displayed in the output of :func:`help`.
 
 * :attr:`~instance.__class__` assignment works only if both classes have the
   same *__slots__*.