Issue #27720: Fix error in eng_to_decimal docs and add examples from the specification.

(Based on a first draft patch from Evelyn Mitchell.)

1 files changed, 11 insertions, 5 deletions

diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
index 971600c..b5ce0b1 100644
--- a/Doc/library/decimal.rst
+++ b/Doc/library/decimal.rst
@@ -836,11 +836,13 @@ Decimal objects
 
    .. method:: to_eng_string(context=None)
 
-      Convert to an engineering-type string.
+      Convert to a string, using engineering notation if an exponent is needed.
 
-      Engineering notation has an exponent which is a multiple of 3, so there
-      are up to 3 digits left of the decimal place.  For example, converts
-      ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``.
+      Engineering notation has an exponent which is a multiple of 3.  This
+      can leave up to 3 digits to the left of the decimal place and may
+      require the addition of either one or two trailing zeros.
+
+      For example, this converts ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``.
 
    .. method:: to_integral(rounding=None, context=None)
 
@@ -1410,7 +1412,11 @@ In addition to the three supplied contexts, new contexts can be created with the
 
    .. method:: to_eng_string(x)
 
-      Converts a number to a string, using scientific notation.
+      Convert to a string, using engineering notation if an exponent is needed.
+
+      Engineering notation has an exponent which is a multiple of 3.  This
+      can leave up to 3 digits to the left of the decimal place and may
+      require the addition of either one or two trailing zeros.
 
 
    .. method:: to_integral_exact(x)