Thanks Stefan! I added a couple of notes to your comments, I'll upload the new draft in a moment. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.... File Modules/_decimal/docstrings.h (left): https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.... Modules/_decimal/docstrings.h:34: Return a context manager that will set the default context to a copy of ctx\n\ On 2016/10/23 21:39:46, skrah wrote:

This is actually important in the age of asyncio. It returns *and sets* the thread's default context.

I prefer the existing wording here.

Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.... Modules/_decimal/docstrings.h:109: the same numeric value but different representations compare unequal\n\ On 2016/10/23 21:39:46, skrah wrote:

I'd leave this in. I tried to give examples only when something unexpected happens. This is one of the cases.

Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.... File Modules/_decimal/docstrings.h (right): https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.... Modules/_decimal/docstrings.h:244: Represents the number as a triple tuple, to show the internals exactly as\n\ On 2016/10/23 21:39:46, skrah wrote:

This is outdated for the Python version and wrong for the C version.

For python 3.7 it looks correct to me?

...

...

Decimal(10).as_tuple() DecimalTuple(sign=0, digits=(1, 0), exponent=0)

https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.... Modules/_decimal/docstrings.h:351: Compares two operands using their abstract representation rather than\n\ On 2016/10/23 21:39:46, skrah wrote:

Everyone has a preferred form. I think Guido prefers the imperative "Compare" (it may be in a PEP somewhere).

Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.... Modules/_decimal/docstrings.h:405: Returns a copy of the operand with the sign set to 0. This operation is unaffected by\n\ On 2016/10/23 21:59:26, skrah wrote:

I think "sign set to zero" is a bit confusing for the C version. "absolute value" sounds fine to me.

Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.... Modules/_decimal/docstrings.h:405: Returns a copy of the operand with the sign set to 0. This operation is unaffected by\n\ On 2016/10/23 21:59:26, skrah wrote:

I think "sign set to zero" is a bit confusing for the C version. "absolute value" sounds fine to me.

Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.... Modules/_decimal/docstrings.h:432: Copies the second operand's sign to the first one.\n\ On 2016/10/23 21:39:46, skrah wrote:

That sounds as if it is a destructive update.

Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.... Modules/_decimal/docstrings.h:739: value of that digit and without limiting the resulting exponent).\n\ On 2016/10/23 21:39:46, skrah wrote:

Personally, I have a hard time understanding this explanation.

I agree this is confusing. It is taken directly from the specification, I worry that clarifying the wording could misrepresent the definition, but the C docstring is a lot clearer. I'm not sure which would be better to include. https://bugs.python.org/review/27779/