bpo-45584: Clarify the meaning of `truncate` in documentation #29183

Arthur-Milchior · 2021-10-23T01:33:44Z

bpo-45584: Clarify the meaning of `truncate` in documentation

While floor/ceil 's documentation are very precise, truncate was not explained. I actually had to search online to understand the difference between truncate and floor (admittedly, once I remembered that numbers are signed, and that floating numbers actually uses a bit for negation symbol instead of two complement, it became obvious)

I assume that I won't be the only user having this trouble, especially for people whose mother tongue is not English. So I suggest adding a clarification to help make what should be obvious to most actually explicit

https://bugs.python.org/issue45584

merwok

Not a math expert but the change makes sense to me!

jacobtylerwalls · 2021-10-31T13:05:47Z

Doc/library/math.rst

-   :class:`~numbers.Integral` (usually an integer). Delegates to
-   :meth:`x.__trunc__() <object.__trunc__>`.
+   :class:`~numbers.Integral` (usually an integer). Truncating *x* means
+   removing the digits after the decimal comma, hence rounding toward 0. It is


Since not all locales use a comma:

Suggested change

removing the digits after the decimal comma, hence rounding toward 0. It is

removing the digits after the decimal separator, hence rounding toward 0. It is

Done.
I didn't realize that the English doc had to be normalized. I admit that if I were to translate it to French (my mother tongue), I clearly would have used "dot". But I guess it's great this way, thanks!

Not a math expert but the change makes sense to me!

Great! That's the point. That the doc is easy to get even without being a math expert. At least in my opinion.

While floor/ceil 's documentation are very precise, `truncate` was not explained. I actually had to search online to understand the difference between `truncate` and `floor` (admittedly, once I remembered that numbers are signed, and that floating numbers actually uses a bit for negation symbol instead of two complement, it became obvious) I assume that I won't be the only user having this trouble, especially for people whose mother tongue is not English. So I suggest adding a clarification to help make what should be obvious to most actually explicit

merwok · 2021-11-01T03:34:55Z

For future PRs to CPython repositories, please avoid using rebases and force pushes: https://devguide.python.org/pullrequest/#quick-guide

Source is https://bugs.python.org/issue45584#msg405481

Arthur-Milchior · 2021-11-02T04:24:08Z

Uploaded a new version as suggested on bpo https://bugs.python.org/issue45584?@ok_message=msg%20405487%20cr%C3%A9%C3%A9%0Aissue%2045584%20message_count%2C%20messages%20modifi%C3%A9%28s%29%20avec%20succ%C3%A8s&@template=item#msg405481

Doc/library/math.rst

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

Doc/library/math.rst

Arthur-Milchior · 2021-11-02T22:59:15Z

Azure pipelines PR fail at Pre-build check

stating

##[error]No hosted parallelism has been purchased or granted. To request a free parallelism grant, please fill out the following form https://aka.ms/azpipelines-parallelism-request

I assume it's unrelated to the current PR. What should I do here?

Doc/library/math.rst

bedevere-bot · 2021-11-03T00:08:10Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

And if you don't make the requested changes, you will be put in the comfy chair!

terryjreedy · 2021-11-03T00:16:53Z

Azure Pipelines PR tests are currently not working, so that failure can be ignored. In essence, all checks are currently passing.

bedevere-bot · 2021-11-26T04:53:35Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Arthur-Milchior · 2021-11-27T02:35:45Z

I have made the requested changes; please review again.

I tested ceil and floor, they both link as expected.

Do you believe it would make sens to try to go over the whole

bedevere-bot · 2021-11-27T02:35:48Z

Thanks for making the requested changes!

@terryjreedy, @merwok: please review the changes made to this pull request.

This commit is the first commit of what I plan to be a sequence of commit whose goal is to improve the documentation usability. It's goal is to be an example, concentrated on ``__name__``, that will allow me to get feedback and show my goals before working on other missing references. Whatever the place in the documentation, it may always save a little bit of time that references are clicable. This allows the reader to easily get more information if needed. My goal is to go through the part of the documentation in /Doc and ensure that as many method, variable, members, functions, classes... becomes links. Actually, I got the idea from PR python#29183, where terryjreedy asked me to add a link to a method in a part of the documentation my PR was touching. I believe the idea was good and should be systematized. Since this may be a big change, here are the steps to ensure that it gets easy to review: * each commit consider a single word. In this case ``__name__``, so the commit is really easy (even if boring) to review * only the lines containing the changed words are changed. No other reformating occurs. This allow any diff tool to really easily show that no other differences are introduced. The downside is that some lines are now longer than 80 characters. However, I should note that this constraint was already not respected in a lot of place of the documentation. And until there is an automated formatting tool, I think the cost is quite small compared to the improvement in the documentation usability. If those 80 characters are considered a blocker, it would be easy to reformat all lines in a last commit, once the link creations are done.

Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>

JelleZijlstra

Looks good.

@terryjreedy your suggestions were addressed, are you OK with merging this now?

terryjreedy · 2022-04-02T22:00:51Z

Please go ahead.

miss-islington · 2022-04-02T22:11:23Z

Thanks @Arthur-Milchior for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9, 3.10.
🐍🍒⛏🤖

miss-islington · 2022-04-02T22:11:25Z

Sorry @Arthur-Milchior and @JelleZijlstra, I had trouble checking out the 3.10 backport branch.
Please backport using cherry_picker on command line.
cherry_picker ebbdbbff5d6840807e46ec61b8a323e94ee88de2 3.10

bedevere-bot · 2022-04-02T22:11:40Z

GH-32272 is a backport of this pull request to the 3.9 branch.

miss-islington · 2022-04-02T22:11:56Z

Thanks @Arthur-Milchior for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10.
🐍🍒⛏🤖

bedevere-bot · 2022-04-02T22:12:08Z

GH-32273 is a backport of this pull request to the 3.10 branch.

While floor/ceil 's documentation are very precise, `truncate` was not explained. I actually had to search online to understand the difference between `truncate` and `floor` (admittedly, once I remembered that numbers are signed, and that floating numbers actually uses a bit for negation symbol instead of two complement, it became obvious) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> Co-authored-by: Éric Araujo <merwok@netwok.org> Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> (cherry picked from commit ebbdbbf) Co-authored-by: Arthur Milchior <arthur@milchior.fr>

bedevere-bot added the awaiting review label Oct 23, 2021

the-knights-who-say-ni added the CLA not signed label Oct 23, 2021

bedevere-bot added the docs Documentation in the Doc dir label Oct 23, 2021

the-knights-who-say-ni added CLA signed and removed CLA not signed labels Oct 27, 2021

merwok added needs backport to 3.9 only security fixes needs backport to 3.10 only security fixes labels Oct 30, 2021

merwok approved these changes Oct 30, 2021

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting review labels Oct 30, 2021

merwok added the skip news label Oct 30, 2021

jacobtylerwalls reviewed Oct 31, 2021

View reviewed changes

Arthur-Milchior force-pushed the truncate branch from aab6de7 to 93db851 Compare November 1, 2021 00:38

Arthur-Milchior force-pushed the truncate branch from 93db851 to e0a173d Compare November 1, 2021 00:38

python deleted a comment from the-knights-who-say-ni Nov 2, 2021

Improved version of trunc documentation by Terry Reedy

afaa3a2

Source is https://bugs.python.org/issue45584#msg405481

AlexWaygood reviewed Nov 2, 2021

View reviewed changes

Doc/library/math.rst Outdated Show resolved Hide resolved

Update Doc/library/math.rst

02ca5d3

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

merwok reviewed Nov 2, 2021

View reviewed changes

Doc/library/math.rst Outdated Show resolved Hide resolved

add space

2b0dc77

merwok reviewed Nov 2, 2021

View reviewed changes

Doc/library/math.rst Outdated Show resolved Hide resolved

terryjreedy requested changes Nov 3, 2021

View reviewed changes

Doc/library/math.rst Outdated Show resolved Hide resolved

bedevere-bot added awaiting changes and removed awaiting merge labels Nov 3, 2021

Arthur-Milchior added 2 commits November 27, 2021 03:26

ceil and floor documentation uses :meth:

af253ee

correct

569cff7

bedevere-bot added awaiting change review and removed awaiting changes labels Nov 27, 2021

bedevere-bot requested a review from terryjreedy November 27, 2021 02:35

Update Doc/library/math.rst

a00f434

Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>

JelleZijlstra approved these changes Apr 2, 2022

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting change review labels Apr 2, 2022

JelleZijlstra self-assigned this Apr 2, 2022

JelleZijlstra merged commit ebbdbbf into python:main Apr 2, 2022

bedevere-bot removed the awaiting merge label Apr 2, 2022

bedevere-bot removed the needs backport to 3.9 only security fixes label Apr 2, 2022

JelleZijlstra added needs backport to 3.10 only security fixes and removed needs backport to 3.10 only security fixes labels Apr 2, 2022

bedevere-bot removed the needs backport to 3.10 only security fixes label Apr 2, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bpo-45584: Clarify the meaning of `truncate` in documentation #29183

bpo-45584: Clarify the meaning of `truncate` in documentation #29183

Arthur-Milchior commented Oct 23, 2021 •

edited by bedevere-bot

Loading

merwok left a comment

jacobtylerwalls Oct 31, 2021

Arthur-Milchior Nov 1, 2021

Arthur-Milchior Nov 1, 2021

merwok commented Nov 1, 2021

Arthur-Milchior commented Nov 2, 2021

Arthur-Milchior commented Nov 2, 2021

bedevere-bot commented Nov 3, 2021

terryjreedy commented Nov 3, 2021

bedevere-bot commented Nov 26, 2021

Arthur-Milchior commented Nov 27, 2021

bedevere-bot commented Nov 27, 2021

JelleZijlstra left a comment

terryjreedy commented Apr 2, 2022

miss-islington commented Apr 2, 2022

miss-islington commented Apr 2, 2022

bedevere-bot commented Apr 2, 2022

miss-islington commented Apr 2, 2022

bedevere-bot commented Apr 2, 2022

	removing the digits after the decimal comma, hence rounding toward 0. It is
	removing the digits after the decimal separator, hence rounding toward 0. It is

bpo-45584: Clarify the meaning of truncate in documentation #29183

bpo-45584: Clarify the meaning of truncate in documentation #29183

Conversation

Arthur-Milchior commented Oct 23, 2021 • edited by bedevere-bot Loading

bpo-45584: Clarify the meaning of truncate in documentation

merwok left a comment

Choose a reason for hiding this comment

jacobtylerwalls Oct 31, 2021

Choose a reason for hiding this comment

Arthur-Milchior Nov 1, 2021

Choose a reason for hiding this comment

Arthur-Milchior Nov 1, 2021

Choose a reason for hiding this comment

merwok commented Nov 1, 2021

Arthur-Milchior commented Nov 2, 2021

Arthur-Milchior commented Nov 2, 2021

bedevere-bot commented Nov 3, 2021

terryjreedy commented Nov 3, 2021

bedevere-bot commented Nov 26, 2021

Arthur-Milchior commented Nov 27, 2021

bedevere-bot commented Nov 27, 2021

JelleZijlstra left a comment

Choose a reason for hiding this comment

terryjreedy commented Apr 2, 2022

miss-islington commented Apr 2, 2022

miss-islington commented Apr 2, 2022

bedevere-bot commented Apr 2, 2022

miss-islington commented Apr 2, 2022

bedevere-bot commented Apr 2, 2022

bpo-45584: Clarify the meaning of `truncate` in documentation #29183

bpo-45584: Clarify the meaning of `truncate` in documentation #29183

Arthur-Milchior commented Oct 23, 2021 •

edited by bedevere-bot

Loading

bpo-45584: Clarify the meaning of `truncate` in documentation