Pedantically, you say "subsequent calls to RWMutex.RLock() will block" but it would be more correct to say "subsequent calls to RWMutex.RLock() may block."

Oh? Looks like I'm still confused then. 😛
It was my understanding that if you did something similar to this:

rw := sync.RWMutex{}
rw.RLock()
go rw.Lock()
rw.RLock() // :(

You would always* end up with a deadlock (*assuming 'favourable' scheduling)

I'm sorry, I misread your comment. I think you're right.

CL https://golang.org/cl/45697 mentions this issue.

This was already fixed once in #15418 by b3f98d7.

I just tried to say more in https://golang.org/cl/45697 but it's unclear how much better my updated text is.

I'll let @ianlancetaylor or @dvyukov decide.

The third paragraph "If a goroutine holds a RWMutex for reading,
it must not expect this or any other goroutine to be able to also take
the read lock until the first read lock is released." appears to contradict
the first paragraph "The lock can be held by an arbitrary number of
readers or a single writer."

Are you sure they are contradicting? What exactly is the contradiction?

The contradiction is only in a world with no goroutines calling Lock.

It says "an arbitrary number of readers" or "a single writer".

The arbitrary number of readers part is actually true if there's no goroutine ever calling Lock. Then anybody's free to call RLock without fear of deadlocks. The deadlock only happens if anybody's calling Lock.

The CL I sent above the words:

... and another goroutine might call Lock, ...

@bradfitz right
the change looks +1 to me

👍, though I still think RLock() should specify that it blocks.
Eg

RLock locks rw for reading. If another goroutine has or is trying to lock for writing, RLock blocks until the write has completed.

RLock may block until (at least for the "is trying to lock for writing" case)

I've added a small note to the RLock method referencing the type comment. PTAL.