[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