[issue45584] Clarifying truncating in documentation

[miss-islington]

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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45584] Clarifying truncating in documentation

[miss-islington]

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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45584] Clarifying truncating in documentation

[Jelle Zijlstra]

Jelle Zijlstra  added the comment:

Thanks for the patch!

--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45584] Clarifying truncating in documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +30336
pull_request: https://github.com/python/cpython/pull/32273

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45584] Clarifying truncating in documentation

[miss-islington]

Change by miss-islington :


--
nosy: +miss-islington
nosy_count: 7.0 -> 8.0
pull_requests: +30335
pull_request: https://github.com/python/cpython/pull/32272

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45584] Clarifying truncating in documentation

[Jelle Zijlstra]

Jelle Zijlstra  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/ebbdbbff5d6840807e46ec61b8a323e94ee88de2


--
nosy: +JelleZijlstra

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45584] Clarifying truncating in documentation

[Arthur Milchior]

Arthur Milchior  added the comment:

Done

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45584] Clarifying truncating in documentation

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Yes, revise and retest your branch and push it.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45584] Clarifying truncating in documentation

[Arthur Milchior]

Arthur Milchior  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45584] Clarifying truncating in documentation

[Terry J. Reedy]

Terry J. Reedy  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__() `.

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45584] Clarifying truncating in documentation

[Roundup Robot]

Change by Roundup Robot :


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

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45584] Clarifying truncating in documentation

[Arthur Milchior]

New submission from 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

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

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com