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

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

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

Yes, revise and retest your branch and push it.

Done

New changeset ebbdbbff5d6840807e46ec61b8a323e94ee88de2 by Arthur Milchior in branch 'main':
bpo-45584: Clarify `math.trunc` documentation (GH-29183)
https://github.com/python/cpython/commit/ebbdbbff5d6840807e46ec61b8a323e94ee88de2

Thanks for the patch!

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/3031b867531009d270d5d7d3e53e739c4cba8816

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/694425817ba2b3a796acb3413a7111f6de4bd086