diff -r 5d8b3cda3559 Lib/_pydecimal.py
--- a/Lib/_pydecimal.py	Fri Sep 09 13:54:34 2016 -0700
+++ b/Lib/_pydecimal.py	Fri Sep 09 15:23:25 2016 -0700
@@ -527,6 +527,26 @@
              return +s  # Convert result to normal context
 
     >>> setcontext(DefaultContext)
+    >>> print(getcontext().prec) # Return a context manager for a copy of the supplied context
+
+    Uses a copy of the current context if no context is specified
+    The returned context manager creates a local decimal context
+    in a with statement:
+        def sin(x):
+             with localcontext() as ctx:
+                 ctx.prec += 2
+                 # Rest of sin calculation algorithm
+                 # uses a precision 2 greater than normal
+             return +s  # Convert result to normal precision
+
+         def sin(x):
+             with localcontext(ExtendedContext):
+                 # Rest of sin calculation algorithm
+                 # uses the Extended Context from the
+                 # General Decimal Arithmetic Specification
+             return +s  # Convert result to normal context
+
+    >>> setcontext(DefaultContext)
     >>> print(getcontext().prec)
     28
     >>> with localcontext():
@@ -541,6 +561,19 @@
     9
     >>> print(getcontext().prec)
     28
+    28
+    >>> with localcontext():
+    ...     ctx = getcontext()
+    ...     ctx.prec += 2
+    ...     print(ctx.prec)
+    ...
+    30
+    >>> with localcontext(ExtendedContext):
+    ...     print(getcontext().prec)
+    ...
+    9
+    >>> print(getcontext().prec)
+    28
     """
     if ctx is None: ctx = getcontext()
     return _ContextManager(ctx)
@@ -572,7 +605,7 @@
         Decimal('314')
         >>> Decimal(Decimal(314))        # another decimal instance
         Decimal('314')
-        >>> Decimal('  3.14  \\n')        # leading and trailing whitespace okay
+        >>> Decimal('  3.14  \\n')       # leading and trailing whitespace okay
         Decimal('3.14')
         """
 
@@ -1004,17 +1037,18 @@
         return -2 if ans == -1 else ans
 
     def as_tuple(self):
-        """Represents the number as a triple tuple.
-
-        To show the internals exactly as they are.
+        """Represents the number as a triple tuple, to show the internals
+        exactly as they are.
         """
         return DecimalTuple(self._sign, tuple(map(int, self._int)), self._exp)
 
     def as_integer_ratio(self):
         """Express a finite Decimal instance in the form n / d.
 
-        Returns a pair (n, d) of integers.  When called on an infinity
-        or NaN, raises OverflowError or ValueError respectively.
+        Return a pair (n, d) of integers, whose ratio is exactly equal to the
+        original Decimal and with a positive denominator. The ratio is in
+        lowest terms. Raise OverflowError on infinities and a ValueError
+        on NaNs.
 
         >>> Decimal('3.14').as_integer_ratio()
         (157, 50)
@@ -2942,7 +2976,10 @@
         return self._int[-1+self._exp] in '02468'
 
     def adjusted(self):
-        """Return the adjusted exponent of self"""
+        """Return the adjusted exponent of self.
+
+        Defined as exp + digits - 1.
+        """
         try:
             return self._exp + len(self._int) - 1
         # If NaN or Infinity, self._exp is string
@@ -2950,10 +2987,10 @@
             return 0
 
     def canonical(self):
-        """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.
+        """Return the canonical encoding of the argument.
+
+        Currently, the encoding of a Decimal instance is always canonical,
+        so this operation returns its argument unchanged.
         """
         return self
 
@@ -3094,7 +3131,7 @@
             return Decimal(self)
 
         # the result is now guaranteed to be inexact (the true
-        # mathematical result is transcendental). There's no need to
+        # mathematical is transcendental). There's no need to
         # raise Rounded and Inexact here---they'll always be raised as
         # a result of the call to _fix.
         p = context.prec
@@ -4235,6 +4272,11 @@
         subtraction: '-1' if the result is less than zero, '0' if the result is
         zero or negative zero, or '1' if the result is greater than zero.
 
+            a or b is a NaN ==> Decimal('NaN')
+            a < b           ==> Decimal('-1')
+            a == b          ==> Decimal('0')
+            a > b           ==> Decimal('1')
+
         >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))
         Decimal('-1')
         >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))
@@ -4253,6 +4295,8 @@
         Decimal('-1')
         >>> ExtendedContext.compare(1, Decimal(2))
         Decimal('-1')
+        >>> ExtendedContext.compare(Decimal('2'), Decimal('NaN'))
+        Decimal('NaN')
         """
         a = _convert_other(a, raiseit=True)
         return a.compare(b, context=self)
@@ -4293,11 +4337,21 @@
         return a.compare_signal(b, context=self)
 
     def compare_total(self, a, b):
-        """Compares two operands using their abstract representation.
-
-        This is not like the standard compare, which use their numerical
-        value. Note that a total ordering is defined for all possible abstract
-        representations.
+        """Compares two operands using their abstract representation rather
+        than their numerical value.
+
+        Similar to the compare() method, but the result gives a total ordering
+        on Decimal instances.
+
+        Quiet and signaling NaNs are also included in the total ordering. 
+        The result of this function is Decimal('0') if both operands have the 
+        same representation, Decimal('-1') if the first operand is lower in 
+        the total order than the second, and Decimal('1') if the first 
+        operand is higher in the total order than the second operand. See 
+        the specification for details of the total order.
+
+        This operation is unaffected by context and is quiet: no flags are
+        changed and no rounding is performed.
 
         >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))
         Decimal('-1')
@@ -4322,9 +4376,15 @@
         return a.compare_total(b)
 
     def compare_total_mag(self, a, b):
-        """Compares two operands using their abstract representation ignoring sign.
-
-        Like compare_total, but with operand's sign ignored and assumed to be 0.
+        """Compares two operands using their abstract representation rather
+        than their numerical value and with their sign ignored.
+
+        Like compare_total, but with operand's sign ignored and assumed to be
+        0.
+
+        x.compare_total_mag(y) is equivalent to  x.copy_abs().compare_total(y.copy_abs())
+        This operation is unaffected by context and is quiet: no flags are
+        changed and no rounding is performed.
         """
         a = _convert_other(a, raiseit=True)
         return a.compare_total_mag(b)
@@ -4388,6 +4448,9 @@
         Decimal('-1')
         >>> ExtendedContext.copy_sign(1, Decimal(-2))
         Decimal('-1')
+
+        This operation is unaffected by context and is quiet: no flags are
+        changed and no rounding is performed.
         """
         a = _convert_other(a, raiseit=True)
         return a.copy_sign(b)
@@ -4474,7 +4537,9 @@
             return r
 
     def exp(self, a):
-        """Returns e ** a.
+        """Return the value of the (natural) exponential function e ** a. 
+        The function always uses the ROUND_HALF_EVEN mode and the result
+        is correctly rounded.
 
         >>> c = ExtendedContext.copy()
         >>> c.Emin = -999
@@ -4500,8 +4565,8 @@
     def fma(self, a, b, c):
         """Returns a multiplied by b, plus c.
 
-        The first two operands are multiplied together, using multiply,
-        the third operand is then added to the result of that
+        Fused multiple-add. The first two operands are multiplied together,
+        using multiply, the third operand is then added to the result of that
         multiplication, using add, all with only one final rounding.
 
         >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))
@@ -4571,7 +4636,7 @@
         return a.is_infinite()
 
     def is_nan(self, a):
-        """Return True if the operand is a qNaN or sNaN;
+        """Return True if the operand is a (quiet or signaling) NaN or NaN;
         otherwise return False.
 
         >>> ExtendedContext.is_nan(Decimal('2.50'))
@@ -4627,6 +4692,8 @@
     def is_signed(self, a):
         """Return True if the operand is negative; otherwise return False.
 
+        Note that both zeros and NaNs can carry signs.
+
         >>> ExtendedContext.is_signed(Decimal('2.50'))
         False
         >>> ExtendedContext.is_signed(Decimal('-12'))
@@ -4660,6 +4727,9 @@
     def is_subnormal(self, a):
         """Return True if the operand is subnormal; otherwise return False.
 
+        A number is subnormal if it is non-zero, finite, and has an adjusted
+        exponent less than Emin.
+
         >>> c = ExtendedContext.copy()
         >>> c.Emin = -999
         >>> c.Emax = 999
@@ -4699,6 +4769,9 @@
     def ln(self, a):
         """Returns the natural (base e) logarithm of the operand.
 
+        The function always uses the ROUND_HALF_EVEN mode and the result is
+        correctly rounded.
+
         >>> c = ExtendedContext.copy()
         >>> c.Emin = -999
         >>> c.Emax = 999
@@ -4721,6 +4794,9 @@
     def log10(self, a):
         """Returns the base 10 logarithm of the operand.
 
+        The function always uses the ROUND_HALF_EVEN mode and the result
+        is correctly rounded.
+
         >>> c = ExtendedContext.copy()
         >>> c.Emin = -999
         >>> c.Emax = 999
@@ -4747,7 +4823,7 @@
         return a.log10(context=self)
 
     def logb(self, a):
-        """ Returns the exponent of the magnitude of the operand's MSD.
+        """Returns the exponent of the magnitude of the operand's MSD.
 
         The result is the integer which is the exponent of the magnitude
         of the most significant digit of the operand (as though the
diff -r 5d8b3cda3559 Modules/_decimal/docstrings.h
--- a/Modules/_decimal/docstrings.h	Fri Sep 09 13:54:34 2016 -0700
+++ b/Modules/_decimal/docstrings.h	Fri Sep 09 15:23:25 2016 -0700
@@ -17,13 +17,114 @@
 
 
 PyDoc_STRVAR(doc__decimal,
-"C decimal arithmetic module");
+"This is an implementation of decimal floating point arithmetic based on\n\
+the General Decimal Arithmetic Specification:\n\
+\n\
+    http://speleotrove.com/decimal/decarith.html\n\
+\n\
+and IEEE standard 854-1987:\n\
+\n\
+    http://en.wikipedia.org/wiki/IEEE_854-1987\n\
+\n\
+Decimal floating point has finite precision with arbitrarily large bounds.\n\
+\n\
+The purpose of this module is to support arithmetic using familiar\n\
+\"schoolhouse\" rules and to avoid some of the tricky representation\n\
+issues associated with binary floating point.  The package is especially\n\
+useful for financial applications or for contexts where users have\n\
+expectations that are at odds with binary floating point (for instance,\n\
+in binary floating point, 1.00 % 0.1 gives 0.09999999999999995 instead\n\
+of 0.0; Decimal('1.00') % Decimal('0.1') returns the expected\n\
+Decimal('0.00')).\n\
+\n\
+Here are some examples of using the decimal module:\n\
+\n\
+    >>> from decimal import *\n\
+    >>> setcontext(ExtendedContext)\n\
+    >>> Decimal(0)\n\
+    Decimal('0')\n\
+    >>> Decimal('1')\n\
+    Decimal('1')\n\
+    >>> Decimal('-.0123')\n\
+    Decimal('-0.0123')\n\
+    >>> Decimal(123456)\n\
+    Decimal('123456')\n\
+    >>> Decimal('123.45e12345678')\n\
+    Decimal('1.2345E+12345680')\n\
+    >>> Decimal('1.33') + Decimal('1.27')\n\
+    Decimal('2.60')\n\
+    >>> Decimal('12.34') + Decimal('3.87') - Decimal('18.41')\n\
+    Decimal('-2.20')\n\
+    >>> dig = Decimal(1)\n\
+    >>> print(dig / Decimal(3))\n\
+    0.333333333\n\
+    >>> getcontext().prec = 18\n\
+    >>> print(dig / Decimal(3))\n\
+    0.333333333333333333\n\
+    >>> print(dig.sqrt())\n\
+    1\n\
+    >>> print(Decimal(3).sqrt())\n\
+    1.73205080756887729\n\
+    >>> print(Decimal(3) ** 123)\n\
+    4.85192780976896427E+58\n\
+    >>> inf = Decimal(1) / Decimal(0)\n\
+    >>> print(inf)\n\
+    Infinity\n\
+    >>> neginf = Decimal(-1) / Decimal(0)\n\
+    >>> print(neginf)\n\
+    -Infinity\n\
+    >>> print(neginf + inf)\n\
+    NaN\n\
+    >>> print(neginf * inf)\n\
+    -Infinity\n\
+    >>> print(dig / 0)\n\
+    Infinity\n\
+    >>> getcontext().traps[DivisionByZero] = 1\n\
+    >>> print(dig / 0)\n\
+    Traceback (most recent call last):\n\
+      ...\n\
+      ...\n\
+      ...\n\
+    decimal.DivisionByZero: x / 0\n\
+    >>> c = Context()\n\
+    >>> c.traps[InvalidOperation] = 0\n\
+    >>> print(c.flags[InvalidOperation])\n\
+    0\n\
+    >>> c.divide(Decimal(0), Decimal(0))\n\
+    Decimal('NaN')\n\
+    >>> c.traps[InvalidOperation] = 1\n\
+    >>> print(c.flags[InvalidOperation])\n\
+    1\n\
+    >>> c.flags[InvalidOperation] = 0\n\
+    >>> print(c.flags[InvalidOperation])\n\
+    0\n\
+    >>> print(c.divide(Decimal(0), Decimal(0)))\n\
+    Traceback (most recent call last):\n\
+      ...\n\
+      ...\n\
+      ...\n\
+    decimal.InvalidOperation: 0 / 0\n\
+    >>> print(c.flags[InvalidOperation])\n\
+    1\n\
+    >>> c.flags[InvalidOperation] = 0\n\
+    >>> c.traps[InvalidOperation] = 0\n\
+    >>> print(c.divide(Decimal(0), Decimal(0)))\n\
+    NaN\n\
+    >>> print(c.flags[InvalidOperation])\n\
+    1\n\
+    >>>\n\
+\n");
 
 PyDoc_STRVAR(doc_getcontext,
 "getcontext($module, /)\n--\n\n\
-Get the current default context.\n\
+Returns this thread's context.\n\
+\n\
+If this thread does not yet have a context, returns\n\
+a new context and sets this thread's context.\n\
+New contexts are copies of DefaultContext.\n\
 \n");
 
+/*This seems clearer than the python version*/
 PyDoc_STRVAR(doc_setcontext,
 "setcontext($module, context, /)\n--\n\n\
 Set a new default context.\n\
@@ -31,10 +132,72 @@
 
 PyDoc_STRVAR(doc_localcontext,
 "localcontext($module, /, ctx=None)\n--\n\n\
-Return a context manager that will set the default context to a copy of ctx\n\
-on entry to the with-statement and restore the previous default context when\n\
-exiting the with-statement. If no context is specified, a copy of the current\n\
-default context is used.\n\
+Return a context manager for a copy of the supplied context.\n\
+Uses a copy of the current context if no context is specified.\n\
+The returned context manager creates a local decimal context\n\
+in a with statement:\n\
+    def sin(x):\n\
+         with localcontext() as ctx:\n\
+             ctx.prec += 2\n\
+             # Rest of sin calculation algorithm\n\
+             # uses a precision 2 greater than normal\n\
+         return +s  # Convert result to normal precision\n\
+\n\
+     def sin(x):\n\
+         with localcontext(ExtendedContext):\n\
+             # Rest of sin calculation algorithm\n\
+             # uses the Extended Context from the\n\
+             # General Decimal Arithmetic Specification\n\
+         return +s  # Convert result to normal context\n\
+\n\
+    >>> setcontext(DefaultContext)\n\
+    >>> print(getcontext().prec) # Return a context manager for a copy of the supplied context\n\
+\n\
+Uses a copy of the current context if no context is specified.\n\
+The returned context manager creates a local decimal context\n\
+in a with statement:\n\
+    def sin(x):\n\
+         with localcontext() as ctx:\n\
+             ctx.prec += 2\n\
+             # Rest of sin calculation algorithm\n\
+             # uses a precision 2 greater than normal\n\
+         return +s  # Convert result to normal precision\n\
+\n\
+    def sin(x):\n\
+        with localcontext(ExtendedContext):\n\
+            # Rest of sin calculation algorithm\n\
+            # uses the Extended Context from the\n\
+            # General Decimal Arithmetic Specification\n\
+        return +s  # Convert result to normal context\n\
+\n\
+    >>> setcontext(DefaultContext)\n\
+    >>> print(getcontext().prec)\n\
+    28\n\
+    >>> with localcontext():\n\
+    ...     ctx = getcontext()\n\
+    ...     ctx.prec += 2\n\
+    ...     print(ctx.prec)\n\
+    ...\n\
+    30\n\
+    >>> with localcontext(ExtendedContext):\n\
+    ...     print(getcontext().prec)\n\
+    ...\n\
+    9\n\
+    >>> print(getcontext().prec)\n\
+    28\n\
+    28\n\
+    >>> with localcontext():\n\
+    ...     ctx = getcontext()\n\
+    ...     ctx.prec += 2\n\
+    ...     print(ctx.prec)\n\
+    ...\n\
+    30\n\
+    >>> with localcontext(ExtendedContext):\n\
+    ...     print(getcontext().prec)\n\
+    ...\n\
+    9\n\
+    >>> print(getcontext().prec)\n\
+    28\n\
 \n");
 
 #ifdef EXTRA_FUNCTIONALITY
@@ -58,59 +221,136 @@
 or another Decimal object. If no value is given, return Decimal('0'). The\n\
 context does not affect the conversion and is only passed to determine if\n\
 the InvalidOperation trap is active.\n\
+\n\
+    >>> Decimal('3.14')              # string input\n\
+    Decimal('3.14')\n\
+    >>> Decimal((0, (3, 1, 4), -2))  # tuple (sign, digit_tuple, exponent)\n\
+    Decimal('3.14')\n\
+    >>> Decimal(314)                 # int\n\
+    Decimal('314')\n\
+    >>> Decimal(Decimal(314))        # another decimal instance\n\
+    Decimal('314')\n\
+    >>> Decimal('  3.14  \\\\n')      # leading and trailing whitespace okay\n\
+    Decimal('3.14')\n\
 \n");
 
 PyDoc_STRVAR(doc_adjusted,
 "adjusted($self, /)\n--\n\n\
-Return the adjusted exponent of the number.  Defined as exp + digits - 1.\n\
+Return the adjusted exponent of the number. Defined as exp + digits - 1.\n\
 \n");
 
 PyDoc_STRVAR(doc_as_tuple,
 "as_tuple($self, /)\n--\n\n\
-Return a tuple representation of the number.\n\
+Represents the number as a triple tuple, to show the internals exactly as\n\
+they are.\n\
 \n");
 
 PyDoc_STRVAR(doc_as_integer_ratio,
 "as_integer_ratio($self, /)\n--\n\n\
-Decimal.as_integer_ratio() -> (int, int)\n\
-\n\
-Return a pair of integers, whose ratio is exactly equal to the original\n\
+Express a finite Decimal instance in the form n / d.\n\
+Return a pair (n, d) of integers, whose ratio is exactly equal to the original\n\
 Decimal and with a positive denominator. The ratio is in lowest terms.\n\
 Raise OverflowError on infinities and a ValueError on NaNs.\n\
+\n\
+    >>> Decimal('3.14').as_integer_ratio()\n\
+    (157, 50)\n\
+    >>> Decimal('-123e5').as_integer_ratio()\n\
+    (-12300000, 1)\n\
+    >>> Decimal('0.00').as_integer_ratio()\n\
+    (0, 1)\n\
 \n");
 
 PyDoc_STRVAR(doc_canonical,
 "canonical($self, /)\n--\n\n\
-Return the canonical encoding of the argument.  Currently, the encoding\n\
-of a Decimal instance is always canonical, so this operation returns its\n\
-argument unchanged.\n\
+Returns the same Decimal object.\n\
+As we do not have different encodings for the same number, the received\n\
+object already is in its canonical form.\n\
+\n\
+    >>> ExtendedContext.canonical(Decimal('2.50'))\n\
+    Decimal('2.50')\n\
 \n");
 
 PyDoc_STRVAR(doc_compare,
 "compare($self, /, other, context=None)\n--\n\n\
-Compare self to other.  Return a decimal value:\n\
+Compares values numerically.\n\
 \n\
-    a or b is a NaN ==> Decimal('NaN')\n\
-    a < b           ==> Decimal('-1')\n\
-    a == b          ==> Decimal('0')\n\
-    a > b           ==> Decimal('1')\n\
+If the signs of the operands differ, a value representing each operand\n\
+('-1' if the operand is less than zero, '0' if the operand is zero or\n\
+negative zero, or '1' if the operand is greater than zero) is used in\n\
+place of that operand for the comparison instead of the actual\n\
+operand.\n\
+\n\
+The comparison is then effected by subtracting the second operand from\n\
+the first and then returning a value according to the result of the\n\
+subtraction: '-1' if the result is less than zero, '0' if the result is\n\
+zero or negative zero, or '1' if the result is greater than zero.\n\
+\n\
+        a or b is a NaN ==> Decimal('NaN')\n\
+        a < b           ==> Decimal('-1')\n\
+        a == b          ==> Decimal('0')\n\
+        a > b           ==> Decimal('1')\n\
+\n\
+    >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))\n\
+    Decimal('0')\n\
+    >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))\n\
+    Decimal('0')\n\
+    >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))\n\
+    Decimal('1')\n\
+    >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))\n\
+    Decimal('1')\n\
+    >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.compare(1, 2)\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.compare(Decimal(1), 2)\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.compare(1, Decimal(2))\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.compare(Decimal('2'), Decimal('NaN'))\n\
+    Decimal('NaN')\n\
 \n");
 
 PyDoc_STRVAR(doc_compare_signal,
 "compare_signal($self, /, other, context=None)\n--\n\n\
-Identical to compare, except that all NaNs signal.\n\
+Compares the values of the two operands numerically.\n\
+\n\
+It's pretty much like compare(), but all NaNs signal, with signaling\n\
+NaNs taking precedence over quiet NaNs.\n\
+\n\
+    >>> c = ExtendedContext\n\
+    >>> c.compare_signal(Decimal('2.1'), Decimal('3'))\n\
+    Decimal('-1')\n\
+    >>> c.compare_signal(Decimal('2.1'), Decimal('2.1'))\n\
+    Decimal('0')\n\
+    >>> c.flags[InvalidOperation] = 0\n\
+    >>> print(c.flags[InvalidOperation])\n\
+    0\n\
+    >>> c.compare_signal(Decimal('NaN'), Decimal('2.1'))\n\
+    Decimal('NaN')\n\
+    >>> print(c.flags[InvalidOperation])\n\
+    1\n\
+    >>> c.flags[InvalidOperation] = 0\n\
+    >>> print(c.flags[InvalidOperation])\n\
+    0\n\
+    >>> c.compare_signal(Decimal('sNaN'), Decimal('2.1'))\n\
+    Decimal('NaN')\n\
+    >>> print(c.flags[InvalidOperation])\n\
+    1\n\
+    >>> c.compare_signal(-1, 2)\n\
+    Decimal('-1')\n\
+    >>> c.compare_signal(Decimal(-1), 2)\n\
+    Decimal('-1')\n\
+    >>> c.compare_signal(-1, Decimal(2))\n\
+    Decimal('-1')\n\
 \n");
 
 PyDoc_STRVAR(doc_compare_total,
 "compare_total($self, /, other, context=None)\n--\n\n\
-Compare two operands using their abstract representation rather than\n\
+Compares two operands using their abstract representation rather than\n\
 their numerical value.  Similar to the compare() method, but the result\n\
-gives a total ordering on Decimal instances.  Two Decimal instances with\n\
-the same numeric value but different representations compare unequal\n\
-in this ordering:\n\
-\n\
-    >>> Decimal('12.0').compare_total(Decimal('12'))\n\
-    Decimal('-1')\n\
+gives a total ordering on Decimal instances.\n\
 \n\
 Quiet and signaling NaNs are also included in the total ordering. The result\n\
 of this function is Decimal('0') if both operands have the same representation,\n\
@@ -121,12 +361,32 @@
 This operation is unaffected by context and is quiet: no flags are changed\n\
 and no rounding is performed. As an exception, the C version may raise\n\
 InvalidOperation if the second operand cannot be converted exactly.\n\
+\n\
+    >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.compare_total(Decimal('-127'),  Decimal('12'))\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))\n\
+    Decimal('0')\n\
+    >>> ExtendedContext.compare_total(Decimal('12.3'),  Decimal('12.300'))\n\
+    Decimal('1')\n\
+    >>> ExtendedContext.compare_total(Decimal('12.3'),  Decimal('NaN'))\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.compare_total(1, 2)\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.compare_total(Decimal(1), 2)\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.compare_total(1, Decimal(2))\n\
+    Decimal('-1')\n\
 \n");
 
 PyDoc_STRVAR(doc_compare_total_mag,
 "compare_total_mag($self, /, other, context=None)\n--\n\n\
-Compare two operands using their abstract representation rather than their\n\
-value as in compare_total(), but ignoring the sign of each operand.\n\
+Compares two operands using their abstract representation rather than their\n\
+numerical value and with their sign ignored. Like compare_total, but with\n\
+operand's sign ignored and assumed to be 0.\n\
 \n\
 x.compare_total_mag(y) is equivalent to x.copy_abs().compare_total(y.copy_abs()).\n\
 \n\
@@ -137,28 +397,56 @@
 
 PyDoc_STRVAR(doc_conjugate,
 "conjugate($self, /)\n--\n\n\
-Return self.\n\
+Returns self.\n\
 \n");
 
 PyDoc_STRVAR(doc_copy_abs,
 "copy_abs($self, /)\n--\n\n\
-Return the absolute value of the argument.  This operation is unaffected by\n\
+Returns a copy of the operand with the sign set to 0. This operation is unaffected by\n\
 context and is quiet: no flags are changed and no rounding is performed.\n\
+\n\
+    >>> ExtendedContext.copy_abs(Decimal('2.1'))\n\
+    Decimal('2.1')\n\
+    >>> ExtendedContext.copy_abs(Decimal('-100'))\n\
+    Decimal('100')\n\
+    >>> ExtendedContext.copy_abs(-1)\n\
+    Decimal('1')\n\
 \n");
 
 PyDoc_STRVAR(doc_copy_negate,
 "copy_negate($self, /)\n--\n\n\
-Return the negation of the argument.  This operation is unaffected by context\n\
-and is quiet: no flags are changed and no rounding is performed.\n\
+Returns a copy of the operand with the sign inverted. This operation is\n\
+unaffected by context and is quiet: no flags are changed and no rounding\n\
+is performed.\n\
+\n\
+    >>> ExtendedContext.copy_negate(Decimal('101.5'))\n\
+    Decimal('-101.5')\n\
+    >>> ExtendedContext.copy_negate(Decimal('-101.5'))\n\
+    Decimal('101.5')\n\
+    >>> ExtendedContext.copy_negate(1)\n\
+    Decimal('-1')\n\
 \n");
 
 PyDoc_STRVAR(doc_copy_sign,
 "copy_sign($self, /, other, context=None)\n--\n\n\
-Return a copy of the first operand with the sign set to be the same as the\n\
-sign of the second operand. For example:\n\
+Copies the second operand's sign to the first one.\n\
+In detail, it returns a copy of the first operand with the sign\n\
+equal to the sign of the second operand.\n\
 \n\
-    >>> Decimal('2.3').copy_sign(Decimal('-1.5'))\n\
-    Decimal('-2.3')\n\
+    >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))\n\
+    Decimal('1.50')\n\
+    >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))\n\
+    Decimal('1.50')\n\
+    >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))\n\
+    Decimal('-1.50')\n\
+    >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))\n\
+    Decimal('-1.50')\n\
+    >>> ExtendedContext.copy_sign(1, -2)\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.copy_sign(Decimal(1), -2)\n\
+    Decimal('-1')\n\
+    >>> ExtendedContext.copy_sign(1, Decimal(-2))\n\
+    Decimal('-1')\n\
 \n\
 This operation is unaffected by context and is quiet: no flags are changed\n\
 and no rounding is performed. As an exception, the C version may raise\n\
@@ -167,9 +455,26 @@
 
 PyDoc_STRVAR(doc_exp,
 "exp($self, /, context=None)\n--\n\n\
-Return the value of the (natural) exponential function e**x at the given\n\
-number.  The function always uses the ROUND_HALF_EVEN mode and the result\n\
+Return the value of the (natural) exponential function e ** a. The function always uses the ROUND_HALF_EVEN mode and the result\n\
 is correctly rounded.\n\
+\n\
+    >>> c = ExtendedContext.copy()\n\
+    >>> c.Emin = -999\n\
+    >>> c.Emax = 999\n\
+    >>> c.exp(Decimal('-Infinity'))\n\
+    Decimal('0')\n\
+    >>> c.exp(Decimal('-1'))\n\
+    Decimal('0.367879441')\n\
+    >>> c.exp(Decimal('0'))\n\
+    Decimal('1')\n\
+    >>> c.exp(Decimal('1'))\n\
+    Decimal('2.71828183')\n\
+    >>> c.exp(Decimal('0.693147181'))\n\
+    Decimal('2.00000000')\n\
+    >>> c.exp(Decimal('+Infinity'))\n\
+    Decimal('Infinity')\n\
+    >>> c.exp(10)\n\
+    Decimal('22026.4658')\n\
 \n");
 
 PyDoc_STRVAR(doc_from_float,
@@ -191,103 +496,304 @@
 
 PyDoc_STRVAR(doc_fma,
 "fma($self, /, other, third, context=None)\n--\n\n\
-Fused multiply-add.  Return self*other+third with no rounding of the\n\
-intermediate product self*other.\n\
+Returns a multiplied by b, plus c.\n\
 \n\
-    >>> Decimal(2).fma(3, 5)\n\
-    Decimal('11')\n\
+Fused multiply-add. The first two operands are multiplied together,\n\
+using multiply, the third operand is then added to the result of that\n\
+multiplication, using add, all with only one final rounding.\n\
 \n\
+    >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))\n\
+    Decimal('22')\n\
+    >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))\n\
+    Decimal('-8')\n\
+    >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578'))\n\
+    Decimal('1.38435736E+12')\n\
+    >>> ExtendedContext.fma(1, 3, 4)\n\
+    Decimal('7')\n\
+    >>> ExtendedContext.fma(1, Decimal(3), 4)\n\
+    Decimal('7')\n\
+    >>> ExtendedContext.fma(1, 3, Decimal(4))\n\
+    Decimal('7')\n\
 \n");
 
 PyDoc_STRVAR(doc_is_canonical,
 "is_canonical($self, /)\n--\n\n\
-Return True if the argument is canonical and False otherwise.  Currently,\n\
-a Decimal instance is always canonical, so this operation always returns\n\
-True.\n\
+Return True if the operand is canonical; otherwise return False.\n\
+Currently, the encoding of a Decimal instance is always\n\
+canonical, so this method returns True for any Decimal.\n\
+\n\
+    >>> ExtendedContext.is_canonical(Decimal('2.50'))\n\
+    True\n\
 \n");
 
 PyDoc_STRVAR(doc_is_finite,
 "is_finite($self, /)\n--\n\n\
-Return True if the argument is a finite number, and False if the argument\n\
-is infinite or a NaN.\n\
+Return True if the operand is finite; otherwise return False.\n\
+A Decimal instance is considered finite if it is neither infinite nor a\n\
+NaN.\n\
+\n\
+    >>> ExtendedContext.is_finite(Decimal('2.50'))\n\
+    True\n\
+    >>> ExtendedContext.is_finite(Decimal('-0.3'))\n\
+    True\n\
+    >>> ExtendedContext.is_finite(Decimal('0'))\n\
+    True\n\
+    >>> ExtendedContext.is_finite(Decimal('Inf'))\n\
+    False\n\
+    >>> ExtendedContext.is_finite(Decimal('NaN'))\n\
+    False\n\
+    >>> ExtendedContext.is_finite(1)\n\
+    True\n\
 \n");
 
 PyDoc_STRVAR(doc_is_infinite,
 "is_infinite($self, /)\n--\n\n\
-Return True if the argument is either positive or negative infinity and\n\
-False otherwise.\n\
+Return True if the operand is infinite; otherwise return False.\n\
+\n\
+    >>> ExtendedContext.is_infinite(Decimal('2.50'))\n\
+    False\n\
+    >>> ExtendedContext.is_infinite(Decimal('-Inf'))\n\
+    True\n\
+    >>> ExtendedContext.is_infinite(Decimal('NaN'))\n\
+    False\n\
+    >>> ExtendedContext.is_infinite(1)\n\
+    False\n\
 \n");
 
 PyDoc_STRVAR(doc_is_nan,
 "is_nan($self, /)\n--\n\n\
-Return True if the argument is a (quiet or signaling) NaN and False\n\
-otherwise.\n\
+Return True if the operand is a (quiet or signaling) NaN or NaN;\n\
+otherwise return False.\n\
+\n\
+    >>> ExtendedContext.is_nan(Decimal('2.50'))\n\
+    False\n\
+    >>> ExtendedContext.is_nan(Decimal('NaN'))\n\
+    True\n\
+    >>> ExtendedContext.is_nan(Decimal('-sNaN'))\n\
+    True\n\
+    >>> ExtendedContext.is_nan(1)\n\
+    False\n\
 \n");
 
 PyDoc_STRVAR(doc_is_normal,
 "is_normal($self, /, context=None)\n--\n\n\
-Return True if the argument is a normal finite non-zero number with an\n\
-adjusted exponent greater than or equal to Emin. Return False if the\n\
-argument is zero, subnormal, infinite or a NaN.\n\
+Return True if the operand is a normal number; otherwise return False.\n\
+\n\
+    >>> c = ExtendedContext.copy()\n\
+    >>> c.Emin = -999\n\
+    >>> c.Emax = 999\n\
+    >>> c.is_normal(Decimal('2.50'))\n\
+    True\n\
+    >>> c.is_normal(Decimal('0.1E-999'))\n\
+    False\n\
+    >>> c.is_normal(Decimal('0.00'))\n\
+    False\n\
+    >>> c.is_normal(Decimal('-Inf'))\n\
+    False\n\
+    >>> c.is_normal(Decimal('NaN'))\n\
+    False\n\
+    >>> c.is_normal(1)\n\
+    True\n\
 \n");
 
 PyDoc_STRVAR(doc_is_qnan,
 "is_qnan($self, /)\n--\n\n\
-Return True if the argument is a quiet NaN, and False otherwise.\n\
+Return True if the argument is a quiet NaN; otherwise return False.\n\
+\n\
+    >>> ExtendedContext.is_qnan(Decimal('2.50'))\n\
+    False\n\
+    >>> ExtendedContext.is_qnan(Decimal('NaN'))\n\
+    True\n\
+    >>> ExtendedContext.is_qnan(Decimal('sNaN'))\n\
+    False\n\
+    >>> ExtendedContext.is_qnan(1)\n\
+    False\n\
 \n");
 
 PyDoc_STRVAR(doc_is_signed,
 "is_signed($self, /)\n--\n\n\
 Return True if the argument has a negative sign and False otherwise.\n\
 Note that both zeros and NaNs can carry signs.\n\
+\n\
+    >>> ExtendedContext.is_signed(Decimal('2.50'))\n\
+    False\n\
+    >>> ExtendedContext.is_signed(Decimal('-12'))\n\
+    True\n\
+    >>> ExtendedContext.is_signed(Decimal('-0'))\n\
+    True\n\
+    >>> ExtendedContext.is_signed(8)\n\
+    False\n\
+    >>> ExtendedContext.is_signed(-8)\n\
+    True\n\
 \n");
 
 PyDoc_STRVAR(doc_is_snan,
 "is_snan($self, /)\n--\n\n\
-Return True if the argument is a signaling NaN and False otherwise.\n\
+Return True if the operand is a signaling NaN; otherwise return False.\n\
+\n\
+    >>> ExtendedContext.is_snan(Decimal('2.50'))\n\
+    False\n\
+    >>> ExtendedContext.is_snan(Decimal('NaN'))\n\
+    False\n\
+    >>> ExtendedContext.is_snan(Decimal('sNaN'))\n\
+    True\n\
+    >>> ExtendedContext.is_snan(1)\n\
+    False\n\
 \n");
 
 PyDoc_STRVAR(doc_is_subnormal,
 "is_subnormal($self, /, context=None)\n--\n\n\
-Return True if the argument is subnormal, and False otherwise. A number is\n\
-subnormal if it is non-zero, finite, and has an adjusted exponent less\n\
+Return True if the argument is subnormal; otherwise return False. A number\n\
+is subnormal if it is non-zero, finite, and has an adjusted exponent less\n\
 than Emin.\n\
+\n\
+    >>> c = ExtendedContext.copy()\n\
+    >>> c.Emin = -999\n\
+    >>> c.Emax = 999\n\
+    >>> c.is_subnormal(Decimal('2.50'))\n\
+    False\n\
+    >>> c.is_subnormal(Decimal('0.1E-999'))\n\
+    True\n\
+    >>> c.is_subnormal(Decimal('0.00'))\n\
+    False\n\
+    >>> c.is_subnormal(Decimal('-Inf'))\n\
+    False\n\
+    >>> c.is_subnormal(Decimal('NaN'))\n\
+    False\n\
+    >>> c.is_subnormal(1)\n\
+    False\n\
 \n");
 
 PyDoc_STRVAR(doc_is_zero,
 "is_zero($self, /)\n--\n\n\
-Return True if the argument is a (positive or negative) zero and False\n\
-otherwise.\n\
+Return True if the operand is a zero; otherwise return False.\n\
+\n\
+    >>> ExtendedContext.is_zero(Decimal('0'))\n\
+    True\n\
+    >>> ExtendedContext.is_zero(Decimal('2.50'))\n\
+    False\n\
+    >>> ExtendedContext.is_zero(Decimal('-0E+2'))\n\
+    True\n\
+    >>> ExtendedContext.is_zero(1)\n\
+    False\n\
+    >>> ExtendedContext.is_zero(0)\n\
+    True\n\
 \n");
 
 PyDoc_STRVAR(doc_ln,
 "ln($self, /, context=None)\n--\n\n\
 Return the natural (base e) logarithm of the operand. The function always\n\
 uses the ROUND_HALF_EVEN mode and the result is correctly rounded.\n\
+\n\
+    >>> c = ExtendedContext.copy()\n\
+    >>> c.Emin = -999\n\
+    >>> c.Emax = 999\n\
+    >>> c.ln(Decimal('0'))\n\
+    Decimal('-Infinity')\n\
+    >>> c.ln(Decimal('1.000'))\n\
+    Decimal('0')\n\
+    >>> c.ln(Decimal('2.71828183'))\n\
+    Decimal('1.00000000')\n\
+    >>> c.ln(Decimal('10'))\n\
+    Decimal('2.30258509')\n\
+    >>> c.ln(Decimal('+Infinity'))\n\
+    Decimal('Infinity')\n\
+    >>> c.ln(1)\n\
+    Decimal('0')\n\
 \n");
 
 PyDoc_STRVAR(doc_log10,
 "log10($self, /, context=None)\n--\n\n\
-Return the base ten logarithm of the operand. The function always uses the\n\
+Return the base 10 logarithm of the operand. The function always uses the\n\
 ROUND_HALF_EVEN mode and the result is correctly rounded.\n\
+\n\
+    >>> c = ExtendedContext.copy()\n\
+    >>> c.Emin = -999\n\
+    >>> c.Emax = 999\n\
+    >>> c.log10(Decimal('0'))\n\
+    Decimal('-Infinity')\n\
+    >>> c.log10(Decimal('0.001'))\n\
+    Decimal('-3')\n\
+    >>> c.log10(Decimal('1.000'))\n\
+    Decimal('0')\n\
+    >>> c.log10(Decimal('2'))\n\
+    Decimal('0.301029996')\n\
+    >>> c.log10(Decimal('10'))\n\
+    Decimal('1')\n\
+    >>> c.log10(Decimal('70'))\n\
+    Decimal('1.84509804')\n\
+    >>> c.log10(Decimal('+Infinity'))\n\
+    Decimal('Infinity')\n\
+    >>> c.log10(0)\n\
+    Decimal('-Infinity')\n\
+    >>> c.log10(1)\n\
+    Decimal('0')\n\
 \n");
 
 PyDoc_STRVAR(doc_logb,
 "logb($self, /, context=None)\n--\n\n\
-For a non-zero number, return the adjusted exponent of the operand as a\n\
-Decimal instance.  If the operand is a zero, then Decimal('-Infinity') is\n\
-returned and the DivisionByZero condition is raised. If the operand is\n\
-an infinity then Decimal('Infinity') is returned.\n\
+Returns the exponent of the magnitude of the operand's MSD.\n\
+The result is the integer which is the exponent of the magnitude\n\
+of the most significant digit of the operand (as though the\n\
+operand were truncated to a single digit while maintaining the\n\
+value of that digit and without limiting the resulting exponent).\n\
+\n\
+    >>> ExtendedContext.logb(Decimal('250'))\n\
+    Decimal('2')\n\
+    >>> ExtendedContext.logb(Decimal('2.50'))\n\
+    Decimal('0')\n\
+    >>> ExtendedContext.logb(Decimal('0.03'))\n\
+    Decimal('-2')\n\
+    >>> ExtendedContext.logb(Decimal('0'))\n\
+    Decimal('-Infinity')\n\
+    >>> ExtendedContext.logb(1)\n\
+    Decimal('0')\n\
+    >>> ExtendedContext.logb(10)\n\
+    Decimal('1')\n\
+    >>> ExtendedContext.logb(100)\n\
+    Decimal('2')\n\
 \n");
 
 PyDoc_STRVAR(doc_logical_and,
 "logical_and($self, /, other, context=None)\n--\n\n\
-Return the digit-wise 'and' of the two (logical) operands.\n\
+Applies the logical operation 'and' between each operand's digits.\n\
+The operands must be both logical numbers.\n\
+\n\
+    >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))\n\
+    Decimal('0')\n\
+    >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))\n\
+    Decimal('0')\n\
+    >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))\n\
+    Decimal('0')\n\
+    >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))\n\
+    Decimal('1')\n\
+    >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))\n\
+    Decimal('1000')\n\
+    >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))\n\
+    Decimal('10')\n\
+    >>> ExtendedContext.logical_and(110, 1101)\n\
+    Decimal('100')\n\
+    >>> ExtendedContext.logical_and(Decimal(110), 1101)\n\
+    Decimal('100')\n\
+    >>> ExtendedContext.logical_and(110, Decimal(1101))\n\
+    Decimal('100')\n\
 \n");
 
 PyDoc_STRVAR(doc_logical_invert,
 "logical_invert($self, /, context=None)\n--\n\n\
-Return the digit-wise inversion of the (logical) operand.\n\
+Invert all the digits in the operand.\n\
+The operand must be a logical number.\n\
+\n\
+    >>> ExtendedContext.logical_invert(Decimal('0'))\n\
+    Decimal('111111111')\n\
+    >>> ExtendedContext.logical_invert(Decimal('1'))\n\
+    Decimal('111111110')\n\
+    >>> ExtendedContext.logical_invert(Decimal('111111111'))\n\
+    Decimal('0')\n\
+    >>> ExtendedContext.logical_invert(Decimal('101010101'))\n\
+    Decimal('10101010')\n\
+    >>> ExtendedContext.logical_invert(1101)\n\
+    Decimal('111110010')\n\
 \n");
 
 PyDoc_STRVAR(doc_logical_or,
@@ -879,6 +1385,3 @@
 
 
 #endif /* DOCSTRINGS_H */
-
-
-