semaphore: add more Acquire documentation

Change-Id: Ie64db438145a307ec8aef8fd412d445a2fe74d40
Reviewed-on: https://go-review.googlesource.com/c/136995
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

semaphore/semaphore.go

@@ -32,9 +32,9 @@ type Weighted struct {
 	waiters list.List
 }
 
-// Acquire acquires the semaphore with a weight of n, blocking only until ctx
+// Acquire acquires the semaphore with a weight of n, blocking until resources
-// is done. On success, returns nil. On failure, returns ctx.Err() and leaves
+// are available or ctx is done. On success, returns nil. On failure, returns
-// the semaphore unchanged.
+// ctx.Err() and leaves the semaphore unchanged.
 //
 // If ctx is already done, Acquire may still succeed without blocking.
 func (s *Weighted) Acquire(ctx context.Context, n int64) error {