maintner, godata: explain updates and read locks

Explain how to keep the godata corpus up-to-date, and clarify the
requirements around locking and updating.

Fix a typo.

Change-Id: Ic9dbe203d1dee7ad3c7463ae932df5daadb51923
Reviewed-on: https://go-review.googlesource.com/47813
Reviewed-by: Andrew Bonventre <andybons@google.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

maintner/godata/godata.go

@@ -23,6 +23,9 @@ import (
 // Github activity, and Gerrit activity and metadata since the
 // beginning of the project.
 //
+// Use Corpus.Update to keep the corpus up-to-date. If you do this, you must
+// hold the read lock if reading and updating concurrently.
+//
 // The initial call to Get will download approximately 350-400 MB of
 // data into a directory "golang-maintner" under your operating
 // system's user cache directory. Subsequent calls will only download

maintner/maintner.go

@@ -64,7 +64,7 @@ type Corpus struct {
 }
 
 // RLock grabs the corpus's read lock. Grabbing the read lock prevents
-// any concurrent writes from mutation the corpus. This is only
+// any concurrent writes from mutating the corpus. This is only
 // necessary if the application is querying the corpus and calling its
 // Update method concurrently.
 func (c *Corpus) RLock() { c.mu.RLock() }
@@ -249,8 +249,9 @@ var ErrSplit = errors.New("maintner: leader server's history split, process out
 // the context expires.
 // If Update returns ErrSplit, the corpus can longer be updated.
 //
-// Update must not be called concurrently with any other method or
-// access of the corpus, including other Update calls.
+// Update must not be called concurrently with any other Update calls. If
+// reading the corpus concurrently while the corpus is updating, you must hold
+// the read lock using Corpus.RLock.
 func (c *Corpus) Update(ctx context.Context) error {
 	if c.mutationSource == nil {
 		panic("Update called without call to Initialize")