Clarifying truncating in documentation

[Arthur-Milchior]

BPO	45584
Nosy	@rhettinger, @terryjreedy, @mdickinson, @JelleZijlstra, @miss-islington, @Arthur-Milchior
PRs	bpo-45584: Clarify the meaning of truncate in documentation #29183 [3.9] bpo-45584: Clarify math.trunc documentation (GH-29183) #32272 [3.10] bpo-45584: Clarify math.trunc documentation (GH-29183) #32273

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2022-04-02.22:14:42.277>
created_at = <Date 2021-10-23.01:31:06.824>
labels = ['3.11', 'type-feature', '3.9', '3.10', 'docs']
title = 'Clarifying truncating in documentation'
updated_at = <Date 2022-04-02.22:36:49.047>
user = 'https://github.com/Arthur-Milchior'

bugs.python.org fields:

activity = <Date 2022-04-02.22:36:49.047>
actor = 'miss-islington'
assignee = 'docs@python'
closed = True
closed_date = <Date 2022-04-02.22:14:42.277>
closer = 'JelleZijlstra'
components = ['Documentation']
creation = <Date 2021-10-23.01:31:06.824>
creator = 'Arthur-Milchior'
dependencies = []
files = []
hgrepos = []
issue_num = 45584
keywords = ['patch']
message_count = 9.0
messages = ['404850', '405481', '405483', '405486', '405487', '416598', '416599', '416601', '416602']
nosy_count = 8.0
nosy_names = ['rhettinger', 'terry.reedy', 'mark.dickinson', 'docs@python', 'python-dev', 'JelleZijlstra', 'miss-islington', 'Arthur-Milchior']
pr_nums = ['29183', '32272', '32273']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue45584'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[Arthur-Milchior]

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

[terryjreedy]

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

[Arthur-Milchior]

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