-
-
Notifications
You must be signed in to change notification settings - Fork 32.5k
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
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this 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.
This comment was marked as resolved.
This comment was marked as resolved.
Rational
and Fraction
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
I'll wait until tomorrow to merge in case others have comments. A |
The numerator and denominator of this new instance are converted to be in | ||
simplest integral terms, always with a positive denominator. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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?
The numerator and denominator of this new instance are converted to be in | ||
simplest integral terms, always with a positive denominator. |
There was a problem hiding this comment.
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>
Co-authored-by: Hugo Sansaqua privet.kitty99@gmail.com
denominator
ofFraction
is positive, which should be documented #122450Links: