[issue45584] Clarifying truncating in documentation
New submission from Arthur Milchior arthur@milchior.fr:
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
---------- assignee: docs@python components: Documentation messages: 404850 nosy: ArthurMilchior, docs@python priority: normal severity: normal status: open title: Clarifying truncating in documentation type: enhancement versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
Change by Roundup Robot devnull@psf.upfronthosting.co.za:
---------- keywords: +patch nosy: +python-dev nosy_count: 2.0 -> 3.0 pull_requests: +27457 stage: -> patch review pull_request: https://github.com/python/cpython/pull/29183
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
Terry J. Reedy tjreedy@udel.edu added the comment:
Current docs:
math.ceil(x) Return the ceiling of x, the smallest integer greater than or equal to x. If x is not a float, delegates to x.__ceil__(), which should return an Integral value.
math.floor(x) Return the floor of x, the largest integer less than or equal to x. If x is not a float, delegates to x.__floor__(), which should return an Integral value.
math.trunc(x) Return the Real value x truncated to an Integral (usually an integer). Delegates to x.__trunc__().
Problems. 0. First sentence not parallel. 1. What does truncated mean? 2. What does 'Real' mean? 3. Delegation sentence not quite parallel. Copy the ceil/floor version.
Current Proposal:
Return the Real value *x* truncated to an Integral (usually an integer). Truncating *x* means removing the digits after the decimal separator, hence rounding toward 0. It is equivalent to floor and ceil for positive and negative numbers respectively. Delegates to :meth:`x.__trunc__() <object.__trunc__>`.
We can't say "Return the truncation (which refers to the action, not the result). "Return the truncated remains of x" would be accurate but begs the question about truncate.
I suggest instead:
"Return x with the fractional part removed, leaving the integer part. This rounds toward 0.0 and is equivalent to floor and ceil for positive and negative x respectively. If x is not a float, delegates to x.__trunc__(), which should return an Integral value."
---------- nosy: +mark.dickinson, rhettinger, terry.reedy versions: -Python 3.6, Python 3.7, Python 3.8
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
Arthur Milchior arthur@milchior.fr added the comment:
I'm quite fan of your suggestion. Should I push it on the PR? Do you create another PR? I'm not used to BPO, I beg your pardon, only to github
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
Terry J. Reedy tjreedy@udel.edu added the comment:
Yes, revise and retest your branch and push it.
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
Arthur Milchior arthur@milchior.fr added the comment:
Done
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
Jelle Zijlstra jelle.zijlstra@gmail.com added the comment:
New changeset ebbdbbff5d6840807e46ec61b8a323e94ee88de2 by Arthur Milchior in branch 'main': bpo-45584: Clarify `math.trunc` documentation (GH-29183) https://github.com/python/cpython/commit/ebbdbbff5d6840807e46ec61b8a323e94ee...
---------- nosy: +JelleZijlstra
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
Change by miss-islington mariatta.wijaya+miss-islington@gmail.com:
---------- nosy: +miss-islington nosy_count: 7.0 -> 8.0 pull_requests: +30335 pull_request: https://github.com/python/cpython/pull/32272
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
Change by miss-islington mariatta.wijaya+miss-islington@gmail.com:
---------- pull_requests: +30336 pull_request: https://github.com/python/cpython/pull/32273
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
Jelle Zijlstra jelle.zijlstra@gmail.com added the comment:
Thanks for the patch!
---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
miss-islington mariatta.wijaya+miss-islington@gmail.com added the comment:
New changeset 3031b867531009d270d5d7d3e53e739c4cba8816 by Miss Islington (bot) in branch '3.10': bpo-45584: Clarify `math.trunc` documentation (GH-29183) https://github.com/python/cpython/commit/3031b867531009d270d5d7d3e53e739c4cb...
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
miss-islington mariatta.wijaya+miss-islington@gmail.com added the comment:
New changeset 694425817ba2b3a796acb3413a7111f6de4bd086 by Miss Islington (bot) in branch '3.9': bpo-45584: Clarify `math.trunc` documentation (GH-29183) https://github.com/python/cpython/commit/694425817ba2b3a796acb3413a7111f6de4...
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue45584 _______________________________________
participants (5)
-
Arthur Milchior -
Jelle Zijlstra
-
miss-islington
-
Roundup Robot
-
Terry J. Reedy