I intend to fix this.

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

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)?

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?

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)".

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

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.

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 𝑛 ≤ 𝟢

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.

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.