[docs] Sync-up docstrings in C version of the the decimal module (issue 27779)

lisaroach14 at gmail.com lisaroach14 at gmail.com
Thu Dec 1 16:44:42 EST 2016


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.h
File Modules/_decimal/docstrings.h (left):

https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.h#oldcode34
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.h#oldcode109
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.h
File Modules/_decimal/docstrings.h (right):

https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings.h#newcode244
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.h#newcode351
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.h#newcode405
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.h#newcode405
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.h#newcode432
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.h#newcode739
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/


More information about the docs mailing list