Skip to content

gh-122450: Expand documentation for Rational and Fraction #136800

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 13 commits into
base: main
Choose a base branch
from

Conversation

skirpichev
Copy link
Contributor

@skirpichev skirpichev commented Jul 19, 2025

@skirpichev skirpichev changed the title gh-122450: Expand numbers.Rational docstrings gh-122450: Expand numbers.Rational docstrings and sphinx docs Jul 19, 2025
@skirpichev skirpichev added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Jul 19, 2025
Copy link
Member

@serhiy-storchaka serhiy-storchaka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Look also at the paragraph before the constructor description: "A Fraction instance can be constructed from a pair of integers, from another rational number, or from a string." It is outdated. The numbers in the pair can be not only integers, and the single numerical argument can be not only rational. Making it more precise will only lead to repetition, so I would make it more generic instead.

@bedevere-app

This comment was marked as resolved.

@AA-Turner AA-Turner changed the title gh-122450: Expand numbers.Rational docstrings and sphinx docs gh-122450: Expand documentation for Rational and Fraction Jul 21, 2025
@skirpichev skirpichev requested a review from AA-Turner July 21, 2025 13:10
@skirpichev

This comment was marked as resolved.

@bedevere-app

This comment was marked as resolved.

skirpichev and others added 2 commits July 31, 2025 11:04
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
@AA-Turner
Copy link
Member

I'll wait until tomorrow to merge in case others have comments.

A

Comment on lines +29 to +30
The numerator and denominator of this new instance are converted to be in
simplest integral terms, always with a positive denominator.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The numerator and denominator of this new instance are converted to be in
simplest integral terms, always with a positive denominator.

I think above sentence should be removed: we already have descriptions for numerator/denominator attributes. This will be a third time. Also, notion of denominator clash with denominator argument name in surrounding sentences. Last, but not least: readers can think, that our internal representation of the Fraction is like described. While it's true - this is an implementation detail.

@AA-Turner, please don't merge this. Lets wait for a second approval from @serhiy-storchaka or @picnixz.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will be a third time.

In total, yes, but the first and only within the constructor. We have seen from analytics and annecdotal evidence that when looking for reference documentation, readers generally only look at the relevant function/class/method, rather than following links or looking elsewhere. Here, the repetition helps, not hinders.

Last, but not least: readers can think, that our internal representation of the Fraction is like described. While it's true - this is an implementation detail.

I'm not sure I follow. Could you elaborate?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I concur with @skirpichev. This sentence is redundant here, it will only confuse users.

When you say "The numerator and denominator of this new instance are converted" you refers to the numerator and denominator attributes. Since there is no any mark up, it can be confused with constructor parameters. If you add links, this will be just a repetition of what was referenced.

The point is not that this sentence can be interpreted in correct way (if you already know how it all works), but that it can be interpreted incorrectly, and it is easy to misinterpret it on first reading.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have a suggested rewording? I remain of the opinion that we should mention this in the documentation for the constructor, rather than indirectly through attribute documentation.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is redundant here, it will only confuse users.

Does the rest looks ok?

Since there is no any mark up, it can be confused with constructor parameters.

(As a side note, I don't think it's a good idea if we will distinguish different meanings just by markup.)

I'm not sure I follow. Could you elaborate?

Rational numbers are just a set of ordered pairs of integers with some equivalency relation. Any such equivalent pair can be used to represent a rational number. So, on which numerator/denominator you are talking here? Are you saying that Fraction internally represented by a canonical representative (in lowest terms and with a positive denominator)? Or that attributes of the Fraction instance returns that canonical representative?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is it needed? In what cases the user needs such information?

Comment on lines +29 to +30
The numerator and denominator of this new instance are converted to be in
simplest integral terms, always with a positive denominator.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I concur with @skirpichev. This sentence is redundant here, it will only confuse users.

When you say "The numerator and denominator of this new instance are converted" you refers to the numerator and denominator attributes. Since there is no any mark up, it can be confused with constructor parameters. If you add links, this will be just a repetition of what was referenced.

The point is not that this sentence can be interpreted in correct way (if you already know how it all works), but that it can be interpreted incorrectly, and it is easy to misinterpret it on first reading.

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy