From 1e95dbb79dd4fd7fe8bd45ae3df0ea0e75178487 Mon Sep 17 00:00:00 2001
From: lipengyu <lipengyu@kylinos.cn>
Date: Sun, 25 Oct 2026 19:00:38 +0800
Subject: [PATCH] Fix inaccurate wording in multiple decimal module docstrings

---
 Lib/_pydecimal.py                    |  9 +++++----
 Modules/_decimal/_decimal.c          | 14 ++++++++++----
 Modules/_decimal/clinic/_decimal.c.h | 12 +++++++++---
 3 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/Lib/_pydecimal.py b/Lib/_pydecimal.py
index 0759b707dc414a5..62f0c045b542497 100644
--- a/Lib/_pydecimal.py
+++ b/Lib/_pydecimal.py
@@ -5158,8 +5158,8 @@ def number_class(self, a):
         """Returns an indication of the class of the operand.
 
         The class is one of the following strings:
-          -sNaN
-          -NaN
+          sNaN
+          NaN
           -Infinity
           -Normal
           -Subnormal
@@ -5668,8 +5668,9 @@ def to_integral_value(self, a):
         When the operand has a negative exponent, the result is the same
         as using the quantize() operation using the given operand as the
         left-hand-operand, 1E+0 as the right-hand-operand, and the precision
-        of the operand as the precision setting, except that no flags will
-        be set.  The rounding mode is taken from the context.
+        of the operand as the precision setting, except that the Inexact and
+        Rounded flags will not be set.  The rounding mode is taken from the
+        context.
 
         >>> ExtendedContext.to_integral_value(Decimal('2.1'))
         Decimal('2')
diff --git a/Modules/_decimal/_decimal.c b/Modules/_decimal/_decimal.c
index 01caedee08a8eb2..1cca329bb11125a 100644
--- a/Modules/_decimal/_decimal.c
+++ b/Modules/_decimal/_decimal.c
@@ -6736,7 +6736,7 @@ _decimal.Context.power
 Compute a**b.
 
 If 'a' is negative, then 'b' must be integral. The result will be
-inexact unless 'a' is integral and the result is finite and can be
+inexact unless 'b' is integral and the result is finite and can be
 expressed exactly in 'precision' digits.  In the Python version the
 result is always correctly rounded, in the C version the result is
 almost always correctly rounded.
@@ -6754,7 +6754,7 @@ restrictions hold:
 static PyObject *
 _decimal_Context_power_impl(PyObject *context, PyTypeObject *cls,
                             PyObject *base, PyObject *exp, PyObject *mod)
-/*[clinic end generated code: output=d06d40c37cdd69dc input=178a254468ec189b]*/
+/*[clinic end generated code: output=d06d40c37cdd69dc input=660210a6607ca4b0]*/
 {
     PyObject *a, *b, *c = NULL;
     PyObject *result;
@@ -7014,13 +7014,19 @@ _decimal_Context_apply_impl(PyObject *context, PyTypeObject *cls,
 /*[clinic input]
 _decimal.Context.canonical = _decimal.Context.is_normal
 
-Return a new instance of x.
+Returns the same Decimal object.
+
+As we do not have different encodings for the same number, the
+received object already is in its canonical form.
+
+>>> ExtendedContext.canonical(Decimal('2.50'))
+Decimal('2.50')
 [clinic start generated code]*/
 
 static PyObject *
 _decimal_Context_canonical_impl(PyObject *context, PyTypeObject *cls,
                                 PyObject *x)
-/*[clinic end generated code: output=f213e433e2032e5e input=025ecb106ac15bff]*/
+/*[clinic end generated code: output=f213e433e2032e5e input=d9f19ee3e7ed9433]*/
 {
     decimal_state *state = PyType_GetModuleState(cls);
     if (!PyDec_Check(state, x)) {
diff --git a/Modules/_decimal/clinic/_decimal.c.h b/Modules/_decimal/clinic/_decimal.c.h
index 0fc6c5ab7ffb73c..e0730202b1a8cb5 100644
--- a/Modules/_decimal/clinic/_decimal.c.h
+++ b/Modules/_decimal/clinic/_decimal.c.h
@@ -5328,7 +5328,7 @@ PyDoc_STRVAR(_decimal_Context_power__doc__,
 "Compute a**b.\n"
 "\n"
 "If \'a\' is negative, then \'b\' must be integral. The result will be\n"
-"inexact unless \'a\' is integral and the result is finite and can be\n"
+"inexact unless \'b\' is integral and the result is finite and can be\n"
 "expressed exactly in \'precision\' digits.  In the Python version the\n"
 "result is always correctly rounded, in the C version the result is\n"
 "almost always correctly rounded.\n"
@@ -6023,7 +6023,13 @@ PyDoc_STRVAR(_decimal_Context_canonical__doc__,
 "canonical($self, x, /)\n"
 "--\n"
 "\n"
-"Return a new instance of x.");
+"Returns the same Decimal object.\n"
+"\n"
+"As we do not have different encodings for the same number, the\n"
+"received object already is in its canonical form.\n"
+"\n"
+">>> ExtendedContext.canonical(Decimal(\'2.50\'))\n"
+"Decimal(\'2.50\')");
 
 #define _DECIMAL_CONTEXT_CANONICAL_METHODDEF    \
     {"canonical", _PyCFunction_CAST(_decimal_Context_canonical), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _decimal_Context_canonical__doc__},
@@ -6984,4 +6990,4 @@ _decimal_Context_same_quantum(PyObject *context, PyTypeObject *cls, PyObject *co
 #ifndef _DECIMAL_CONTEXT_APPLY_METHODDEF
     #define _DECIMAL_CONTEXT_APPLY_METHODDEF
 #endif /* !defined(_DECIMAL_CONTEXT_APPLY_METHODDEF) */
-/*[clinic end generated code: output=72f619bdb52660d6 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=58a4ee7a222a6861 input=a9049054013a1b77]*/