gh-142108: Document Decimal formatting behavior differences

Doc/c-api/descriptor.rst

@@ -21,12 +21,45 @@
 .. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
 
 
+.. c:var:: PyTypeObject PyMemberDescr_Type
+
+   The type object for member descriptor objects created from
+   :c:type:`PyMemberDef` structures. These descriptors expose fields of a
+   C struct as attributes on a type, and correspond to :class:`types.MemberDescriptorType`
+   objects in the Python layer.
+
+
+.. c:var:: PyTypeObject PyGetSetDescr_Type
+
+   The type object for get/set descriptor objects created from
+   :c:type:`PyGetSetDef` structures. These descriptors implement attributes
+   whose value is computed by C getter and setter functions, and are used
+   for many built-in type attributes.
+
+
 .. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
 
 
+.. c:var:: PyTypeObject PyMethodDescr_Type
+
+   The type object for method descriptor objects created from
+   :c:type:`PyMethodDef` structures. These descriptors expose C functions as
+   methods on a type, and correspond to :class:`types.MemberDescriptorType` objects in the
+   Python layer.
+
+
 .. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
 
 
+.. c:var:: PyTypeObject PyWrapperDescr_Type
+
+   The type object for wrapper descriptor objects created by
+   :c:func:`PyDescr_NewWrapper` and :c:func:`PyWrapper_New`. Wrapper
+   descriptors are used internally to expose special methods implemented
+   via wrapper structures, and appear in Python as :class:`types.WrapperDescriptorType`
+   objects.
+
+
 .. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
 
 
@@ -55,6 +88,14 @@
    :class:`classmethod` in the Python layer.
 
 
+.. c:var:: PyTypeObject PyClassMethodDescr_Type
+
+   The type object for C-level class method descriptor objects.
+   This is the type of the descriptors created for :func:`classmethod` defined in C
+   extension types, and is the same object as :class:`classmethod` in the
+   Python layer.
+
+
 .. c:function:: PyObject *PyClassMethod_New(PyObject *callable)
 
    Create a new :class:`classmethod` object wrapping *callable*.

Doc/c-api/dict.rst

@@ -43,6 +43,17 @@ Dictionary Objects
    prevent modification of the dictionary for non-dynamic class types.
 
 
+.. c:var:: PyTypeObject PyDictProxy_Type
+
+   The type object for mapping proxy objects created by
+   :c:func:`PyDictProxy_New` and for the read-only ``__dict__`` attribute
+   of many built-in types. A :c:type:`PyDictProxy_Type` instance provides a
+   dynamic, read-only view of an underlying dictionary: changes to the
+   underlying dictionary are reflected in the proxy, but the proxy itself
+   does not support mutation operations.These objects correspond to
+   :class:`types.MappingProxyType` in Python.
+
+
 .. c:function:: void PyDict_Clear(PyObject *p)
 
    Empty an existing dictionary of all key-value pairs.

Doc/library/string.rst

@@ -629,6 +629,20 @@
 of the :func:`round` builtin.  For :class:`~decimal.Decimal`, the rounding
 mode of the current :ref:`context <decimal-context>` will be used.
 
+
+.. note::
+
+   The :class:`~decimal.Decimal` type has special formatting behavior:
+
+   * When using ``__format__`` (f-strings, ``format()``, ``str.format()``),
+    Decimal formats with maximum precision only when precision is **omitted**
+    in ``f``, ``e``, or ``g`` format types. If precision is explicitly specified,
+    it is respected.
+
+   * When using ``%`` formatting (old-style string formatting with the ``%`` operator),
+   Decimal values are first converted to :class:`float`, which may result in
+   precision loss.
+
 The available presentation types for :class:`complex` are the same as those for
 :class:`float` (``'%'`` is not allowed).  Both the real and imaginary components
 of a complex number are formatted as floating-point numbers, according to the