context: update documentation on cancelation and go vet check.

Also replace double spaces after periods with single spaces.

Change-Id: Iedaea47595c5ce64e7e8aa3a368f36d49061c555
Reviewed-on: https://go-review.googlesource.com/24431Reviewed-by: Alan Donovan <adonovan@google.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

src/context/context.go

@@ -6,32 +6,35 @@
 // cancelation signals, and other request-scoped values across API boundaries
 // and between processes.
 //
-// Incoming requests to a server should create a Context, and outgoing calls to
-// servers should accept a Context.  The chain of function calls between them
-// must propagate the Context, optionally replacing it with a derived Context
-// created using WithCancel, WithDeadline, WithTimeout, or WithValue.  These
-// Context values form a tree: when a Context is canceled, all Contexts derived
-// from it are also canceled.
+// Incoming requests to a server should create a Context, and outgoing
+// calls to servers should accept a Context. The chain of function
+// calls between them must propagate the Context, optionally replacing
+// it with a derived Context created using WithCancel, WithDeadline,
+// WithTimeout, or WithValue. When a Context is canceled, all
+// Contexts derived from it are also canceled.
 //
-// The WithCancel, WithDeadline, and WithTimeout functions return a derived
-// Context and a CancelFunc.  Calling the CancelFunc cancels the new Context and
-// any Contexts derived from it, removes the Context from the parent's tree, and
-// stops any associated timers.  Failing to call the CancelFunc leaks the
-// associated resources until the parent Context is canceled or the timer fires.
+// The WithCancel, WithDeadline, and WithTimeout functions take a
+// Context (the parent) and return a derived Context (the child) and a
+// CancelFunc. Calling the CancelFunc cancels the child and its
+// children, removes the parent's reference to the child, and stops
+// any associated timers. Failing to call the CancelFunc leaks the
+// child and its children until the parent is canceled or the timer
+// fires. The go vet tool checks that CancelFuncs are used on all
+// control-flow paths.
 //
 // Programs that use Contexts should follow these rules to keep interfaces
 // consistent across packages and enable static analysis tools to check context
 // propagation:
 //
 // Do not store Contexts inside a struct type; instead, pass a Context
-// explicitly to each function that needs it.  The Context should be the first
+// explicitly to each function that needs it. The Context should be the first
 // parameter, typically named ctx:
 //
 // 	func DoSomething(ctx context.Context, arg Arg) error {
 // 		// ... use ctx ...
 // 	}
 //
-// Do not pass a nil Context, even if a function permits it.  Pass context.TODO
+// Do not pass a nil Context, even if a function permits it. Pass context.TODO
 // if you are unsure about which Context to use.
 //
 // Use context Values only for request-scoped data that transits processes and
@@ -58,13 +61,13 @@ import (
 // Context's methods may be called by multiple goroutines simultaneously.
 type Context interface {
 	// Deadline returns the time when work done on behalf of this context
-	// should be canceled.  Deadline returns ok==false when no deadline is
-	// set.  Successive calls to Deadline return the same results.
+	// should be canceled. Deadline returns ok==false when no deadline is
+	// set. Successive calls to Deadline return the same results.
 	Deadline() (deadline time.Time, ok bool)
 
 	// Done returns a channel that's closed when work done on behalf of this
-	// context should be canceled.  Done may return nil if this context can
-	// never be canceled.  Successive calls to Done return the same value.
+	// context should be canceled. Done may return nil if this context can
+	// never be canceled. Successive calls to Done return the same value.
 	//
 	// WithCancel arranges for Done to be closed when cancel is called;
 	// WithDeadline arranges for Done to be closed when the deadline
@@ -93,24 +96,24 @@ type Context interface {
 	// a Done channel for cancelation.
 	Done() <-chan struct{}
 
-	// Err returns a non-nil error value after Done is closed.  Err returns
+	// Err returns a non-nil error value after Done is closed. Err returns
 	// Canceled if the context was canceled or DeadlineExceeded if the
-	// context's deadline passed.  No other values for Err are defined.
+	// context's deadline passed. No other values for Err are defined.
 	// After Done is closed, successive calls to Err return the same value.
 	Err() error
 
 	// Value returns the value associated with this context for key, or nil
-	// if no value is associated with key.  Successive calls to Value with
+	// if no value is associated with key. Successive calls to Value with
 	// the same key returns the same result.
 	//
 	// Use context values only for request-scoped data that transits
 	// processes and API boundaries, not for passing optional parameters to
 	// functions.
 	//
-	// A key identifies a specific value in a Context.  Functions that wish
+	// A key identifies a specific value in a Context. Functions that wish
 	// to store values in Context typically allocate a key in a global
 	// variable then use that key as the argument to context.WithValue and
-	// Context.Value.  A key can be any type that supports equality;
+	// Context.Value. A key can be any type that supports equality;
 	// packages should define keys as an unexported type to avoid
 	// collisions.
 	//
@@ -129,7 +132,7 @@ type Context interface {
 	// 	// This prevents collisions with keys defined in other packages.
 	// 	type key int
 	//
-	// 	// userKey is the key for user.User values in Contexts.  It is
+	// 	// userKey is the key for user.User values in Contexts. It is
 	// 	// unexported; clients use user.NewContext and user.FromContext
 	// 	// instead of using this key directly.
 	// 	var userKey key = 0
@@ -160,7 +163,7 @@ func (deadlineExceededError) Error() string { return "context deadline exceeded"
 
 func (deadlineExceededError) Timeout() bool { return true }
 
-// An emptyCtx is never canceled, has no values, and has no deadline.  It is not
+// An emptyCtx is never canceled, has no values, and has no deadline. It is not
 // struct{}, since vars of this type must have distinct addresses.
 type emptyCtx int
 
@@ -196,17 +199,17 @@ var (
 )
 
 // Background returns a non-nil, empty Context. It is never canceled, has no
-// values, and has no deadline.  It is typically used by the main function,
+// values, and has no deadline. It is typically used by the main function,
 // initialization, and tests, and as the top-level Context for incoming
 // requests.
 func Background() Context {
 	return background
 }
 
-// TODO returns a non-nil, empty Context.  Code should use context.TODO when
+// TODO returns a non-nil, empty Context. Code should use context.TODO when
 // it's unclear which Context to use or it is not yet available (because the
 // surrounding function has not yet been extended to accept a Context
-// parameter).  TODO is recognized by static analysis tools that determine
+// parameter). TODO is recognized by static analysis tools that determine
 // whether Contexts are propagated correctly in a program.
 func TODO() Context {
 	return todo
@@ -266,7 +269,7 @@ func propagateCancel(parent Context, child canceler) {
 }
 
 // parentCancelCtx follows a chain of parent references until it finds a
-// *cancelCtx.  This function understands how each of the concrete types in this
+// *cancelCtx. This function understands how each of the concrete types in this
 // package represents its parent.
 func parentCancelCtx(parent Context) (*cancelCtx, bool) {
 	for {
@@ -296,14 +299,14 @@ func removeChild(parent Context, child canceler) {
 	p.mu.Unlock()
 }
 
-// A canceler is a context type that can be canceled directly.  The
+// A canceler is a context type that can be canceled directly. The
 // implementations are *cancelCtx and *timerCtx.
 type canceler interface {
 	cancel(removeFromParent bool, err error)
 	Done() <-chan struct{}
 }
 
-// A cancelCtx can be canceled.  When canceled, it also cancels any children
+// A cancelCtx can be canceled. When canceled, it also cancels any children
 // that implement canceler.
 type cancelCtx struct {
 	Context
@@ -355,8 +358,8 @@ func (c *cancelCtx) cancel(removeFromParent bool, err error) {
 }
 
 // WithDeadline returns a copy of the parent context with the deadline adjusted
-// to be no later than d.  If the parent's deadline is already earlier than d,
-// WithDeadline(parent, d) is semantically equivalent to parent.  The returned
+// to be no later than d. If the parent's deadline is already earlier than d,
+// WithDeadline(parent, d) is semantically equivalent to parent. The returned
 // context's Done channel is closed when the deadline expires, when the returned
 // cancel function is called, or when the parent context's Done channel is
 // closed, whichever happens first.
@@ -388,8 +391,8 @@ func WithDeadline(parent Context, deadline time.Time) (Context, CancelFunc) {
 	return c, func() { c.cancel(true, Canceled) }
 }
 
-// A timerCtx carries a timer and a deadline.  It embeds a cancelCtx to
-// implement Done and Err.  It implements cancel by stopping its timer then
+// A timerCtx carries a timer and a deadline. It embeds a cancelCtx to
+// implement Done and Err. It implements cancel by stopping its timer then
 // delegating to cancelCtx.cancel.
 type timerCtx struct {
 	cancelCtx
@@ -451,7 +454,7 @@ func WithValue(parent Context, key, val interface{}) Context {
 	return &valueCtx{parent, key, val}
 }
 
-// A valueCtx carries a key-value pair.  It implements Value for that key and
+// A valueCtx carries a key-value pair. It implements Value for that key and
 // delegates all other calls to the embedded Context.
 type valueCtx struct {
 	Context