launchdarkly
diff --git a/‎README.md‎
Lines changed: 2 additions & 0 deletions b/‎README.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎ldattr/constants.go‎
Lines changed: 5 additions & 9 deletions b/‎ldattr/constants.go‎
Lines changed: 5 additions & 9 deletions
diff --git a/‎ldattr/package.go‎
Lines changed: 3 additions & 2 deletions b/‎ldattr/package.go‎
Lines changed: 3 additions & 2 deletions
diff --git a/‎ldattr/ref.go‎
Lines changed: 20 additions & 20 deletions b/‎ldattr/ref.go‎
Lines changed: 20 additions & 20 deletions
diff --git a/‎ldcontext/builder_multi.go‎
Lines changed: 37 additions & 35 deletions b/‎ldcontext/builder_multi.go‎
Lines changed: 37 additions & 35 deletions
diff --git a/‎ldcontext/builder_multi_test.go‎
Lines changed: 1 addition & 1 deletion b/‎ldcontext/builder_multi_test.go‎
Lines changed: 1 addition & 1 deletion
@@ -6,6 +6,8 @@
 
 This repository contains packages and types that are shared between the [LaunchDarkly Go SDK](https://github.com/launchdarkly/go-server-sdk) and other LaunchDarkly Go components.
 
+Version 3.x of `go-sdk-common` is used by version 6.x of the LaunchDarkly Go SDK. It is not usable with earlier SDK versions.
+
 Applications using the LaunchDarkly Go SDK will generally use the `ldcontext` subpackage, which contains the `Context` type, and may also use the `ldvalue` package, which contains the `Value` type that represents arbitrary JSON values. Other packages are less frequently used.
 
 ## Supported Go versions
 
@@ -3,25 +3,21 @@ package ldattr
 const (
 	// KeyAttr is a constant for the attribute name that corresponds to the Key() method in
 	// ldcontext.Context and ldcontext.Builder. This name is used in JSON representations and flag
-	// rules, and can be passed to ldcontext.Context.GetValue() or ldcontext.Context.SetValue().
-	// representations and flag rules.
+	// rules, and can be passed to ldcontext.Context.GetValue or ldcontext.Builder.SetValue.
 	KeyAttr = "key"
 
 	// KindAttr is a constant for the attribute name that corresponds to the Kind() method in
 	// ldcontext.Context and ldcontext.Builder. This name is used in JSON representations and flag
-	// rules, and can be passed to ldcontext.Context.GetValue() or ldcontext.Context.SetValue().
-	// representations and flag rules.
+	// rules, and can be passed to ldcontext.Context.GetValue or ldcontext.Builder.SetValue.
 	KindAttr = "kind"
 
 	// NameAttr is a constant for the attribute name that corresponds to the Name() method in
 	// ldcontext.Context and ldcontext.Builder. This name is used in JSON representations and flag
-	// rules, and can be passed to ldcontext.Context.GetValue() or ldcontext.Context.SetValue().
-	// representations and flag rules.
+	// rules, and can be passed to ldcontext.Context.GetValue or ldcontext.Builder.SetValue.
 	NameAttr = "name"
 
 	// AnonymousAttr is a constant for the attribute name that corresponds to the Anonymous() method
-	// in ldcontext.Context and ldcontext.Builder. This name is used in JSON representations and flag
-	// rules, and can be passed to ldcontext.Context.GetValue() or ldcontext.Context.SetValue().
-	// representations and flag rules.
+	// ldcontext.Context and ldcontext.Builder. This name is used in JSON representations and flag
+	// rules, and can be passed to ldcontext.Context.GetValue or ldcontext.Builder.SetValue.
 	AnonymousAttr = "anonymous"
 )
@@ -1,9 +1,10 @@
 // Package ldattr defines the model for context attribute references used by the LaunchDarkly SDK.
 //
-// This includes the ldattr.Ref type, which provides a syntax similar to JSON Pointer for
+// This includes the [Ref] type, which provides a syntax similar to JSON Pointer for
 // referencing values either of a top-level context attribute, or of a value within a JSON object
 // or JSON array. It also includes constants for the names of some built-in attributes.
 //
 // These types and constants are mainly intended to be used internally by LaunchDarkly SDK and
-// service code. Applications are unlikely to need to use them directly.
+// service code. Applications are unlikely to need to use them directly; context attributes are
+// normally set via methods in [github.com/launchdarkly/go-sdk-common/v3/ldcontext].
 package ldattr
@@ -15,13 +15,13 @@ import (
 // efficiency is a major concern so it's desirable to do any parsing or preprocessing just once.
 // Applications are unlikely to need to use the Ref type directly.
 //
-// It can be used to retrieve a value with Context.GetValueForRef(), or to identify an attribute or
-// nested value that should be considered private with Builder.Private() (the SDK configuration can also
-// have a list of private attribute references).
+// It can be used to retrieve a value with Context.GetValueForRef, or to identify an attribute or
+// nested value that should be considered private with Builder.PrivateRef (the SDK configuration
+// can also have a list of private attribute references).
 //
-// Parsing and validation are done at the time that the NewRef or NewLiteralRef constructor is called.
+// Parsing and validation are done at the time that the [NewRef] or [NewLiteralRef] constructor is called.
 // If a Ref instance was created from an invalid string, or if it is an uninitialized Ref{}, it is
-// considered invalid and its Err() method will return a non-nil error.
+// considered invalid and its [Ref.Err] method will return a non-nil error.
 //
 // # Syntax
 //
@@ -66,11 +66,11 @@ type Ref struct {
 	components          []string
 }
 
-// NewRef creates a Ref from a string. For the supported syntax and examples, see comments on the Ref type.
+// NewRef creates a Ref from a string. For the supported syntax and examples, see [Ref].
 //
 // This constructor always returns a Ref that preserves the original string, even if validation fails,
-// so that calling String() (or serializing the Ref to JSON) will produce the original string. If
-// validation fails, Err() will return a non-nil error and any SDK method that takes this Ref as a
+// so that calling [Ref.String] (or serializing the Ref to JSON) will produce the original string. If
+// validation fails, [Ref.Err] will return a non-nil error and any SDK method that takes this Ref as a
 // parameter will consider it invalid.
 func NewRef(referenceString string) Ref {
 	if referenceString == "" || referenceString == "/" {
@@ -105,7 +105,7 @@ func NewRef(referenceString string) Ref {
 	return ret
 }
 
-// NewLiteralRef is similar to NewRef except that it always interprets the string as a literal
+// NewLiteralRef is similar to [NewRef] except that it always interprets the string as a literal
 // attribute name, never as a slash-delimited path expression. There is no escaping or unescaping,
 // even if the name contains literal '/' or '~' characters. Since an attribute name can contain
 // any characters, this method always returns a valid Ref unless the name is empty.
@@ -129,15 +129,15 @@ func NewLiteralRef(attrName string) Ref {
 }
 
 // IsDefined returns true if the Ref has a value, meaning that it is not an uninitialized Ref{}.
-// That does not guarantee that the value is valid; use Err() to test that.
+// That does not guarantee that the value is valid; use [Ref.Err] to test that.
 func (a Ref) IsDefined() bool {
 	return a.rawPath != "" || a.err != nil
 }
 
 // Equal returns true if the two Ref instances have the same value.
 //
 // You cannot compare Ref instances with the == operator, because the struct may contain a slice;
-// reflect.DeepEqual will work, but is less efficient.
+// [reflect.DeepEqual] will work, but is less efficient.
 func (a Ref) Equal(other Ref) bool {
 	if a.err != other.err || a.rawPath != other.rawPath || a.singlePathComponent != other.singlePathComponent {
 		return false
@@ -151,7 +151,7 @@ func (a Ref) Equal(other Ref) bool {
 //
 // A Ref is invalid if the input string is empty, or starts with a slash but is not a valid
 // slash-delimited path, or starts with a slash and contains an invalid escape sequence. For a list of
-// the possible validation errors, see the ErrAttribute___ types in the lderrors package.
+// the possible validation errors, see the [lderrors] package.
 //
 // Otherwise, the Ref is valid, but that does not guarantee that such an attribute exists in any
 // given Context. For instance, NewRef("name") is a valid Ref, but a specific Context might or might
@@ -204,15 +204,15 @@ func (a Ref) Component(index int) string {
 }
 
 // String returns the attribute reference as a string, in the same format used by NewRef().
-// If the Ref was created with NewRef(), this value is identical to the original string. If it
-// was created with NewRefForName(), the value may be different due to unescaping (for instance,
+// If the Ref was created with [NewRef], this value is identical to the original string. If it
+// was created with [NewLiteralRef], the value may be different due to unescaping (for instance,
 // an attribute whose name is "/a" would be represented as "~1a".
 func (a Ref) String() string {
 	return a.rawPath
 }
 
 // MarshalJSON produces a JSON representation of the Ref. If it is an uninitialized Ref{}, this
-// is a JSON null token. Otherwise, it is a JSON string using the same value returned by String().
+// is a JSON null token. Otherwise, it is a JSON string using the same value returned by [Ref.String].
 func (a Ref) MarshalJSON() ([]byte, error) {
 	if !a.IsDefined() {
 		return []byte(`null`), nil
@@ -221,12 +221,12 @@ func (a Ref) MarshalJSON() ([]byte, error) {
 }
 
 // UnmarshalJSON parses a Ref from a JSON value. If the value is null, the result is an
-// uninitialized Ref(). If the value is a string, it is passed to NewRef(). Any other type
+// uninitialized Ref(). If the value is a string, it is passed to [NewRef]. Any other type
 // causes an error.
 //
 // A valid JSON string that is not valid as a Ref path (such as "" or "///") does not cause
 // UnmarshalJSON to return an error; instead, it stores the string in the Ref and the error
-// can be obtained from Ref.Err(). This is deliberate, so that the LaunchDarkly SDK will be
+// can be obtained from [Ref.Err]. This is deliberate, so that the LaunchDarkly SDK will be
 // able to parse a set of feature flag data even if one of the flags contains an invalid Ref.
 func (a *Ref) UnmarshalJSON(data []byte) error {
 	r := jreader.NewReader(data)
@@ -244,9 +244,9 @@ func (a *Ref) UnmarshalJSON(data []byte) error {
 
 // Performs unescaping of attribute reference path components:
 //
-// "~1" becomes "/"
-// "~0" becomes "~"
-// "~" followed by any character other than "0" or "1" is invalid
+//   - "~1" becomes "/"
+//   - "~0" becomes "~"
+//   - "~" followed by any character other than "0" or "1" is invalid
 //
 // The second return value is true if successful, or false if there was an invalid escape sequence.
 func unescapePath(path string) (string, bool) {
 
@@ -10,48 +10,50 @@ import (
 
 const defaultMultiBuilderCapacity = 3 // arbitrary value based on presumed likely use cases
 
-// MultiBuilder is a mutable object that uses the builder pattern to specify properties for a Context.
+// MultiBuilder is a mutable object that uses the builder pattern to create a multi-context,
+// as an alternative to [NewMulti].
 //
 // Use this type if you need to construct a Context that has multiple Kind values, each with its
-// own nested Context. To define a single-kind context, use Builder instead.
+// own nested [Context]. To define a single context, use [Builder] instead.
 //
-// Obtain an instance of MultiBuilder by calling NewMultiBuilder; then, call Add to specify the
-// nested Context for each Kind. MultiBuilder setters return a reference the same builder, so they
-// can be chained together:
+// Obtain an instance of MultiBuilder by calling [NewMultiBuilder]; then, call [MultiBuilder.Add] to
+// specify the nested [Context] for each Kind. Finally, call [MultiBuilder.Build]. MultiBuilder
+// setters return a reference to the same builder, so they can be chained together:
 //
 //	context := ldcontext.NewMultiBuilder().
-//	    Add(ldcontext.New("my-user-key")).
-//	    Add(ldcontext.NewBuilder("my-org-key").Kind("organization").Name("Org1").Build()).
-//	    Build()
+//		Add(ldcontext.New("my-user-key")).
+//		Add(ldcontext.NewBuilder("my-org-key").Kind("organization").Name("Org1").Build()).
+//		Build()
 //
-// A MultiBuilder should not be accessed by multiple goroutines at once. Once you have called Build(),
-// the resulting Context is immutable and is safe to use from multiple goroutines. Instances
-// created with Build() are not affected by subsequent actions taken on the MultiBuilder.
+// A MultiBuilder should not be accessed by multiple goroutines at once. Once you have called
+// [MultiBuilder.Build], the resulting Context is immutable and safe to use from multiple
+// goroutines.
 type MultiBuilder struct {
 	contexts            []Context
 	contextsCopyOnWrite bool
 }
 
-// NewMultiBuilder creates a MultiBuilder for building a Context.
+// NewMultiBuilder creates a MultiBuilder for building a multi-context.
 //
-// This method is for building a Context athat has multiple Kind values, each with its own
-// nested Context. To define a single-kind context, use NewBuilder() instead.
+// This method is for building a [Context] that has multiple [Context.Kind] values, each with its
+// own nested Context. To define a single context, use [NewBuilder] instead.
 func NewMultiBuilder() *MultiBuilder {
 	return &MultiBuilder{contexts: make([]Context, 0, defaultMultiBuilderCapacity)}
 }
 
 // Build creates a Context from the current MultiBuilder properties.
 //
-// The Context is immutable and will not be affected by any subsequent actions on the MultiBuilder.
+// The [Context] is immutable and will not be affected by any subsequent actions on the MultiBuilder.
 //
 // It is possible for a MultiBuilder to represent an invalid state. Instead of returning two
 // values (Context, error), the Builder always returns a Context and you can call Context.Err()
-// to see if it has an error. See Context.Err() for more information about invalid Context
+// to see if it has an error. See [Context.Err] for more information about invalid Context
 // conditions. Using a single-return-value syntax is more convenient for application code, since
 // in normal usage an application will never build an invalid Context.
 //
-// If only one context kind was added to the builder, Build returns a single-kind context rather
-// than a multi-kind context.
+// If only one context was added to the builder, Build returns that same context, rather than a
+// multi-context-- since there is no logical difference in LaunchDarkly between a single context and
+// a multi-context that only contains one context.
 func (m *MultiBuilder) Build() Context {
 	if len(m.contexts) == 0 {
 		return Context{defined: true, err: lderrors.ErrContextKindMultiWithNoKinds{}}
@@ -68,7 +70,7 @@ func (m *MultiBuilder) Build() Context {
 	// compute a fully qualified key.
 	sort.Slice(m.contexts, func(i, j int) bool { return m.contexts[i].Kind() < m.contexts[j].Kind() })
 
-	// Check for conditions that could make a multi-kind context invalid
+	// Check for conditions that could make a multi-context invalid
 	var individualErrors map[string]error
 	duplicates := false
 	for i, c := range m.contexts {
@@ -106,7 +108,7 @@ func (m *MultiBuilder) Build() Context {
 		multiContexts: m.contexts,
 	}
 
-	// Fully-qualified key for multi-kind is defined as "kind1:key1:kind2:key2" etc., where kinds are in
+	// Fully-qualified key for multi-context is defined as "kind1:key1:kind2:key2" etc., where kinds are in
 	// alphabetical order (we have already sorted them above) and keys are URL-encoded. In this case we
 	// do _not_ omit a default kind of "user".
 	for _, c := range m.contexts {
@@ -121,29 +123,29 @@ func (m *MultiBuilder) Build() Context {
 
 // TryBuild is an alternative to Build that returns any validation errors as a second value.
 //
-// As described in Build(), there are several ways the state of a Context could be invalid.
-// Since in normal usage it is possible to be confident that these will not occur, the Build()
-// method is designed for convenient use within expressions by returning a single Context
-// value, and any validation problems are contained within that value where they can be
-// detected by calling the context's Err() method. But, if you prefer to use the two-value
-// pattern that is common in Go, you can call TryBuild instead:
+// As described in [MultiBuilder.Build], there are several ways the state of a [Context] could
+// be invalid. Since in normal usage it is possible to be confident that these will not occur,
+// the Build method is designed for convenient use within expressions by returning a single
+// Context value, and any validation problems are contained within that value where they can be
+// detected by calling the context's [Context.Err] method. But, if you prefer to use the
+// two-value pattern that is common in Go, you can call TryBuild instead:
 //
 //	c, err := ldcontext.NewMultiBuilder().
-//	    Add(context1).Add(context2).
-//	    TryBuild()
+//		Add(context1).Add(context2).
+//		TryBuild()
 //	if err != nil {
-//	    // do whatever is appropriate if building the context failed
+//		// do whatever is appropriate if building the context failed
 //	}
 //
 // The two return values are the same as to 1. the Context that would be returned by Build(),
-// and 2. the result of calling Err() on that Context. So, the above example is exactly
+// and 2. the result of calling [Context.Err] on that Context. So, the above example is exactly
 // equivalent to:
 //
 //	c := ldcontext.NewMultiBuilder().
-//	    Add(context1).Add(context2).
-//	    Build()
+//		Add(context1).Add(context2).
+//		Build()
 //	if c.Err() != nil {
-//	    // do whatever is appropriate if building the context failed
+//		// do whatever is appropriate if building the context failed
 //	}
 //
 // Note that unlike some Go methods where the first return value is normally an
@@ -158,9 +160,9 @@ func (m *MultiBuilder) TryBuild() (Context, error) {
 // Add adds a nested context for a specific Kind to a MultiBuilder.
 //
 // It is invalid to add more than one context with the same Kind. This error is detected
-// when you call Build() or TryBuild().
+// when you call [MultiBuilder.Build] or [MultiBuilder.TryBuild].
 //
-// If the nested context is multi-kind, this is exactly equivalent to adding each of the
+// If the parameter is a multi-context, this is exactly equivalent to adding each of the
 // individual kinds from it separately. For instance, in the following example, "multi1" and
 // "multi2" end up being exactly the same:
 //
 
@@ -30,7 +30,7 @@ func TestMultiBuilder(t *testing.T) {
 		// other accessors are tested in context_test.go
 	})
 
-	t.Run("nested multi-kind contexts are flattened", func(t *testing.T) {
+	t.Run("nested multi-contexts are flattened", func(t *testing.T) {
 		sub1 := NewWithKind("kind1", "key1")
 		sub2 := NewWithKind("kind2", "key2")
 		sub3 := NewWithKind("kind3", "key3")