bpo-29677: DOC: clarify documentation for round
#357
Conversation
Clarified that `round` can take a negative value for *ndigits*.
|
Hello, and thanks for your contribution! I'm a bot set up to make sure that the project can legally accept your contribution by verifying you have signed the PSF contributor agreement (CLA). Unfortunately we couldn't find an account corresponding to your GitHub username on bugs.python.org (b.p.o) to verify you have signed the CLA. This is necessary for legal reasons before we can look at your contribution. Please follow these steps to help rectify the issue:
Thanks again to your contribution and we look forward to looking at it! |
remove trailing whitespace in previous commit
mdickinson
changed the title
roundround
| nearest integer to its input. Delegates to ``number.__round__(ndigits)``. | ||
|
|
||
| For the built-in types supporting :func:`round`, values are rounded to the | ||
| closest multiple of 10 to the power minus *ndigits*; if two multiples are |
There was a problem hiding this comment.
while we are modifying the doc, I dislike the start: "Return the floating point value number": number can be an integer. round(123, -2) doesn't use floating point numbers. Maybe rephrase to following text?
Return number rounded to (...). number can be an integer or a floating point number.
Or just remove "floating pointer number"?
There was a problem hiding this comment.
@Haypo: agree:
Return number rounded to ndigits digits after the decimal point.
seems good to me.
About the negation, placement is good (too soon would have diluted the definition). About its wording, I'd prefer telling what it does instead of just stating it's possible, something like:
Negative ndigits permit rouding before the decimal point.
There was a problem hiding this comment.
Victor, I agree the first sentence is too specific. But the number is not restricted to “int” and “float”. I expect it should work with anything implementing __round__. This is already hinted by the rest of the entry, as well as
https://docs.python.org/dev/reference/datamodel.html#object.__round__
https://docs.python.org/dev/library/numbers.html#numbers.Real
https://docs.python.org/dev/library/fractions.html#fractions.Fraction.__round__
There was a problem hiding this comment.
Do you think we can accept this PR? If you would still like to see improvement with the first sentence, perhaps we can keep the issue open, so another person can work on it. Otherwise, @gerritholl's change in this PR seems good.
There was a problem hiding this comment.
I've made a few changes trying to clarify the wording for round. I hope I didn't overstep any bounds. I researched other, similar functions and looked at the help(). In the first line I wanted to say 'Return the real number x', but float() didn't specify real number, even though they both don't work on Complex.
Anyway, this is my first pull, so I hope I did OK. :-)
* DOC: clarify documentation for `round` Clarified that `round` can take a negative value for *ndigits*. * DOC: remove trailing whitespace in previous commit remove trailing whitespace in previous commit (cherry picked from commit 6003db7)
* DOC: clarify documentation for `round` Clarified that `round` can take a negative value for *ndigits*. * DOC: remove trailing whitespace in previous commit remove trailing whitespace in previous commit (cherry picked from commit 6003db7)
|
Thanks @gerritholl for your first contribution to CPython 🎉 |
7 participants
Clarified that
roundcan take a negative value for ndigits.