math/rand: unclear documentation on Int31n & associated method familly

[ladydascalie]

Please answer these questions before submitting your issue. Thanks!

What version of Go are you using (go version)?

go version go1.10.3 darwin/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

Not relevant, documentation related

What did you do?

I read the following piece of documentation:

Int31n returns, as an int32, a non-negative pseudo-random number in [0,n). It panics if n <= 0.

What did you expect to see?

I expected to understand the meaning of n in that context.

What did you see instead?

I didn't.

[ladydascalie]

I intend to fix this.

[gopherbot]

Change https://golang.org/cl/127549 mentions this issue: math/rand: tweak documentation

[as]

I expected to understand the meaning of n in that context.

That's self-evident if you include the signature of the function being documented.

func Int31n(n int32) int32
    Int31n returns, as an int32, a non-negative pseudo-random number in [0,n)
    from the default Source. It panics if n <= 0.

Which tool did you use to get an output without the function signature (above is the standard go doc rand.Int31n)?

[robpike]

It's very common mathematical notation that I've seen since junior high school. Does the Go documentation need to describe things like this? It's really a policy question: What are we allowed to assume? One person being confused by a reference or a notation is indeed unfortunate, but we cannot be expected to explain everything to everyone, nor should we.

Where do we draw the line?

[ianlancetaylor]

One possible guideline for cases where people report being confused is to make sure that a web search will provide the answer. Unfortunately searching for "[0,n)" provides nothing. But if we like this principle we could, for example, write "a non-negative pseudo-random number in (using interval notation) [0,n)".

[jimmyfrasche]

Current issue aside, why do the docs both say "non-negative" explicitly and include the explicitly non-negative interval?

[robpike]

I like the idea of "(using interval notation)" and the general policy of easy search. I agree it's hard to find "[0,n)" by a web search, but the rewording fixes that an sets a nice precedent.

[mikioh]

I personally think it's fine to use symbols/notations defined in ISO/IEC 80000 family. If the confusion comes from various representation schemes of the symbols, I mean, language-defined math. operators/notations vs. ISO/IEC 80000 math. operators/notations, we can use math. operators in Unicode for clarification:

[0,n) and n <= 0
[𝟢,𝑛) and 𝑛 ≤ 𝟢

[ladydascalie]

It's very common mathematical notation that I've seen since junior high school.

@robpike Unfortunately, I am a high school drop-out. I have not been taught this notation, and it was very difficult to search and find the right information, without pre-existing knowledge.

Of course, this is entirely due to my lack of knowledge, I fully admit that, but I am willing to bet that I may not be the only person in this situation.

the rewording @ianlancetaylor proposes is very much satisfactory in my opinion, it would have given me enough information to find the answer to my question. I shall update my CL to reflect that.

[RalphCorderoy]

I too can remember not knowing this notation, way before Go. I asked a few programmer friends and found out it was 'interval notation'. I just did a few Google searches. Nothing found for phrases "interval notation" or "half open" with site:golang.org or site:docs.python.org. So Python doesn't seem to explain it either, as a data point.

https://books.google.com/ngrams/graph?content=interval+notation%2Chalf+open&year_start=1960&year_end=2010&corpus=15&smoothing=3&share=&direct_url=t1%3B%2Cinterval%20notation%3B%2Cc0%3B.t1%3B%2Chalf%20open%3B%2Cc0 shows both phrases trending up in recent decades. That matches my gut feel that they're seen more often and thus more likely to be understood.