context: document that WithValue returns a derived context

Also replace "copy of parent" with "derived context" in doc comments.

Fixes #68923

Change-Id: I319c1594f390e35b32b4e58ee979927bb84bfdf9
Reviewed-on: https://go-review.googlesource.com/c/go/+/606555
Reviewed-by: Sameer Ajmani <sameer@golang.org>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Auto-Submit: Sameer Ajmani <sameer@golang.org>
Commit-Queue: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/src/context/context.go b/src/context/context.go
index 763d4f777ffb867379fd88699c54a4b7285ec63a..c960fda5f19c508a57653a54fab601d84b723e1b 100644 (file)
--- a/src/context/context.go
+++ b/src/context/context.go
@@ -226,9 +226,10 @@ func TODO() Context {
 // After the first call, subsequent calls to a CancelFunc do nothing.
 type CancelFunc func()
 
-// WithCancel returns a copy of parent with a new Done channel. The returned
-// context's Done channel is closed when the returned cancel function is called
-// or when the parent context's Done channel is closed, whichever happens first.
+// WithCancel returns a derived context that points to the parent context
+// but has a new Done channel. The returned context's Done channel is closed
+// when the returned cancel function is called or when the parent context's
+// Done channel is closed, whichever happens first.
 //
 // Canceling this context releases resources associated with it, so code should
 // call cancel as soon as the operations running in this [Context] complete.
@@ -565,7 +566,8 @@ func (c *cancelCtx) cancel(removeFromParent bool, err, cause error) {
        }
 }
 
-// WithoutCancel returns a copy of parent that is not canceled when parent is canceled.
+// WithoutCancel returns a derived context that points to the parent context
+// and is not canceled when parent is canceled.
 // The returned context returns no Deadline or Err, and its Done channel is nil.
 // Calling [Cause] on the returned context returns nil.
 func WithoutCancel(parent Context) Context {
@@ -599,12 +601,12 @@ func (c withoutCancelCtx) String() string {
        return contextName(c.c) + ".WithoutCancel"
 }
 
-// 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
-// [Context.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.
+// WithDeadline returns a derived context that points to the parent context
+// but has 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 [Context.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.
 //
 // Canceling this context releases resources associated with it, so code should
 // call cancel as soon as the operations running in this [Context] complete.
@@ -697,8 +699,8 @@ func WithTimeoutCause(parent Context, timeout time.Duration, cause error) (Conte
        return WithDeadlineCause(parent, time.Now().Add(timeout), cause)
 }
 
-// WithValue returns a copy of parent in which the value associated with key is
-// val.
+// WithValue returns a derived context that points to the parent Context.
+// In the derived context, the value associated with key is val.
 //
 // Use context Values only for request-scoped data that transits processes and
 // APIs, not for passing optional parameters to functions.