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

[stephane-archer]

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.

[qiulaidongfeng]

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]

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

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

[qiulaidongfeng]

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]

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