Skip to content
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

Jump to bottom

math/big: doesn't have example in the documentation for each function #59321

Open
stephane-archer opened this issue Mar 29, 2023 · 6 comments
Open

math/big: doesn't have example in the documentation for each function #59321

stephane-archer opened this issue Mar 29, 2023 · 6 comments
Labels
Documentation help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Backlog

Comments

@stephane-archer
Copy link

This makes the package a bit hard to use and I'm not sure I properly use it.
For example, NewRat return a *Rat, I have no idea if I should or not check for a nil value?
Adding examples should clarify a lot of questons.
@ianlancetaylor ianlancetaylor changed the title math.big doesn't have example in the documentation for each function math/big: doesn't have example in the documentation for each function Mar 29, 2023
@ianlancetaylor ianlancetaylor added help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. and removed pkgsite labels Mar 29, 2023
@ianlancetaylor ianlancetaylor added this to the Backlog milestone Mar 29, 2023
@DSBUGAY2

This comment was marked as spam.

Sign in to view
@qiulaidongfeng
Copy link
Contributor

see https://pkg.go.dev/math/big I think the package documentation clearly states not to check nil.

Copy the original words:

For instance, NewInt (x) returns an * Int set to the value of the int64 argument x, NewRat (a, b) returns a * Rate set to the fraction a/b where a and b are int64 values, and NewFloat (f) returns a * Float initialized to the float64 argument f

I saw help wanted, but I'm not sure if math/big really needs to add example.

@stephane-archer
Copy link
Author

@qiulaidongfeng From the original words you copied and pasted, I don't see to clearly stay not to check nil.
Maybe my English is not good enough but it doesn't say clearly it never fails.
For me, you approach the problem as someone who already knows how to use this package well.
"Everything is obvious why add something like that when people can just read the source code"
but not everyone is an expert.

@ianlancetaylor
Copy link
Contributor

Let's not get bogged down on nil. It will in general help people if the functions have examples. Thanks.

qiulaidongfeng added a commit to qiulaidongfeng/go that referenced this issue Oct 7, 2023
@qiulaidongfeng
math/big: add examples for functions or methods of Int
30d717c 
For functions or methods without examples, except for those that implement specific interfaces such as MarshalText, this CL ensures at least one example.

For golang#59321

Change-Id: Id990f75a8d1da1f01fb143ba48315ea9529489f5
@qiulaidongfeng qiulaidongfeng mentioned this issue Oct 7, 2023
Closed
@qiulaidongfeng
Copy link
Contributor

I am interested in solving this issue. Who knows how to assign this issue to me?

I plan to address this issue during the go1.22 development cycle. Who knows how to set the milestone for this issue as the go1.22 milestone?

@gopherbot
Copy link

Change https://go.dev/cl/533278 mentions this issue: math/big: add examples for functions or methods of Int

qiulaidongfeng added a commit to qiulaidongfeng/go that referenced this issue Oct 8, 2023
@qiulaidongfeng
math/big: add examples for functions or methods of Int
1a6d9fa 
For functions or methods without examples,
except for those that implement specific interfaces such as MarshalText,
this CL ensures at least one example.

For golang#59321

Change-Id: Id990f75a8d1da1f01fb143ba48315ea9529489f5
qiulaidongfeng added a commit to qiulaidongfeng/go that referenced this issue Oct 8, 2023
@qiulaidongfeng
math/big: add examples for functions or methods of Int
95ef6d5 
For functions or methods without examples,
except for those that implement specific interfaces such as MarshalText,
this CL ensures at least one example.

For golang#59321

Change-Id: Id990f75a8d1da1f01fb143ba48315ea9529489f5
qiulaidongfeng added a commit to qiulaidongfeng/go that referenced this issue Oct 8, 2023
@qiulaidongfeng
math/big: add examples for functions or methods of Int
fb90e68 
For functions or methods without examples,
except for those that implement specific interfaces such as MarshalText,
this CL ensures at least one example.

For golang#59321

Change-Id: Id990f75a8d1da1f01fb143ba48315ea9529489f5
qiulaidongfeng added a commit to qiulaidongfeng/go that referenced this issue Oct 9, 2023
@qiulaidongfeng
math/big: add examples for functions or methods of Int
6a29d01 
For functions or methods without examples,
except for those that implement specific interfaces such as MarshalText,
this CL ensures at least one example.

For golang#59321

Change-Id: Id990f75a8d1da1f01fb143ba48315ea9529489f5
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
5 participants
@stephane-archer @ianlancetaylor @gopherbot @DSBUGAY2 @qiulaidongfeng