Skip to content

bpo-29677: DOC: clarify documentation for round #357

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 27, 2017
Merged

bpo-29677: DOC: clarify documentation for round #357

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9c7da44
DOC: clarify documentation for `round`
gerritholl Feb 28, 2017
de8659b
DOC: remove trailing whitespace in previous commit
gerritholl Feb 28, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion Doc/library/functions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1262,7 +1262,8 @@ are always available. They are listed here in alphabetical order.
closest multiple of 10 to the power minus *ndigits*; if two multiples are
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Member

@vadmium vadmium Mar 2, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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__

Copy link
Member

@Mariatta Mariatta Mar 27, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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. :-)

equally close, rounding is done toward the even choice (so, for example,
both ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is
``2``). The return value is an integer if called with one argument,
``2``). Any integer value is valid for *ndigits* (positive, zero, or
negative). The return value is an integer if called with one argument,
otherwise of the same type as *number*.

.. note::
Expand Down