sync: make another attempt at clarifying RWMutex double RLock rules

Updates #15418 (the original bug, fixed by https://golang.org/cl/23570)
Fixes #19460 (round two)

Change-Id: Iac4447daabb56e3b470046c489c22d588c20163e
Reviewed-on: https://go-review.googlesource.com/45697
Reviewed-by: Ian Lance Taylor <iant@golang.org>

1 files changed, 10 insertions, 5 deletions

diff --git a/src/sync/rwmutex.go b/src/sync/rwmutex.go
index a8607d9167..94889149a1 100644
--- a/src/sync/rwmutex.go
+++ b/src/sync/rwmutex.go
@@ -16,11 +16,12 @@ import (
 //
 // An RWMutex must not be copied after first use.
 //
-// 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. In particular, this prohibits recursive read locking.
-// This is to ensure that the lock eventually becomes available;
-// a blocked Lock call excludes new readers from acquiring the lock.
+// If a goroutine holds a RWMutex for reading and another goroutine might
+// call Lock, no goroutine should expect to be able to acquire a read lock
+// until the initial read lock is released. In particular, this prohibits
+// recursive read locking. This is to ensure that the lock eventually becomes
+// available; a blocked Lock call excludes new readers from acquiring the
+// lock.
 type RWMutex struct {
 	w           Mutex  // held if there are pending writers
 	writerSem   uint32 // semaphore for writers to wait for completing readers
@@ -32,6 +33,10 @@ type RWMutex struct {
 const rwmutexMaxReaders = 1 << 30
 
 // RLock locks rw for reading.
+//
+// It should not be used for recursive read locking; a blocked Lock
+// call excludes new readers from acquiring the lock. See the
+// documentation on the RWMutex type.
 func (rw *RWMutex) RLock() {
 	if race.Enabled {
 		_ = rw.w.state