all: fix some comments to improve readability

Change-Id: If88a7d731009bfb40774ea45a94187ce4d0db848
Reviewed-on: https://go-review.googlesource.com/c/sync/+/785081
Reviewed-by: Mark Freeman <markfreeman@google.com>
Auto-Submit: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: golang-scoped@luci-project-accounts.iam.gserviceaccount.com <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Alan Donovan <adonovan@google.com>

Author: cuishuang

errgroup/errgroup.go

@@ -109,7 +109,7 @@ func (g *Group) TryGo(f func() error) bool {
 	if g.sem != nil {
 		select {
 		case g.sem <- token{}:
-			// Note: this allows barging iff channels in general allow barging.
+			// Note: this allows barging if and only if channels in general allow barging.
 		default:
 			return false
 		}

semaphore/semaphore.go

@@ -83,7 +83,7 @@ func (s *Weighted) Acquire(ctx context.Context, n int64) error {
 		default:
 			isFront := s.waiters.Front() == elem
 			s.waiters.Remove(elem)
-			// If we're at the front and there're extra tokens left, notify other waiters.
+			// If we're at the front and there are extra tokens left, notify other waiters.
 			if isFront && s.size > s.cur {
 				s.notifyWaiters()
 			}
@@ -139,15 +139,15 @@ func (s *Weighted) notifyWaiters() {
 
 		w := next.Value.(waiter)
 		if s.size-s.cur < w.n {
-			// Not enough tokens for the next waiter.  We could keep going (to try to
+			// Not enough tokens for the next waiter. We could keep going (to try to
 			// find a waiter with a smaller request), but under load that could cause
 			// starvation for large requests; instead, we leave all remaining waiters
 			// blocked.
 			//
 			// Consider a semaphore used as a read-write lock, with N tokens, N
-			// readers, and one writer.  Each reader can Acquire(1) to obtain a read
-			// lock.  The writer can Acquire(N) to obtain a write lock, excluding all
-			// of the readers.  If we allow the readers to jump ahead in the queue,
+			// readers, and one writer. Each reader can Acquire(1) to obtain a read
+			// lock. The writer can Acquire(N) to obtain a write lock, excluding all
+			// of the readers. If we allow the readers to jump ahead in the queue,
 			// the writer will starve — there is always one token available for every
 			// reader.
 			break

semaphore/semaphore_bench_test.go

@@ -12,7 +12,7 @@ import (
 	"golang.org/x/sync/semaphore"
 )
 
-// weighted is an interface matching a subset of *Weighted.  It allows
+// weighted is an interface matching a subset of *Weighted. It allows
 // alternate implementations for testing and benchmarking.
 type weighted interface {
 	Acquire(context.Context, int64) error

semaphore/semaphore_test.go

@@ -217,7 +217,7 @@ func TestWeightedAcquireCanceled(t *testing.T) {
 		sem.Release(1)
 		close(ch)
 	}()
-	// Since the context closing happens before enough tokens become available,
+	// Since the context being closed happens before enough tokens become available,
 	// this Acquire must fail.
 	if err := sem.Acquire(ctx, 2); err != context.Canceled {
 		t.Errorf("Acquire with canceled context returned wrong error: want context.Canceled, got %v", err)

singleflight/singleflight.go

@@ -15,12 +15,12 @@ import (
 	"sync"
 )
 
-// errGoexit indicates the runtime.Goexit was called in
-// the user given function.
+// errGoexit indicates runtime.Goexit was called in
+// the user-given function.
 var errGoexit = errors.New("runtime.Goexit was called")
 
 // A panicError is an arbitrary value recovered from a panic
-// with the stack trace during the execution of given function.
+// with the stack trace during the execution of the given function.
 type panicError struct {
 	value any
 	stack []byte
@@ -204,7 +204,7 @@ func (g *Group) doCall(c *call, key string, fn func() (any, error)) {
 	}
 }
 
-// Forget tells the singleflight to forget about a key.  Future calls
+// Forget tells the singleflight to forget about a key. Future calls
 // to Do for this key will call the function rather than waiting for
 // an earlier call to complete.
 func (g *Group) Forget(key string) {

syncmap/map_reference_test.go

@@ -9,7 +9,7 @@ import (
 	"sync/atomic"
 )
 
-// This file contains reference map implementations for unit-tests.
+// This file contains reference map implementations for unit tests.
 
 // mapInterface is the interface Map implements.
 type mapInterface interface {
@@ -82,7 +82,7 @@ func (m *RWMutexMap) Range(f func(key, value any) (shouldContinue bool)) {
 }
 
 // DeepCopyMap is an implementation of mapInterface using a Mutex and
-// atomic.Value.  It makes deep copies of the map on every write to avoid
+// atomic.Value. It makes deep copies of the map on every write to avoid
 // acquiring the Mutex in Load.
 type DeepCopyMap struct {
 	mu    sync.Mutex