Use of hotlinking of Go identifiers

cmp/cmpopts/equate.go

@@ -16,10 +16,10 @@ import (
 
 func equateAlways(_, _ interface{}) bool { return true }
 
-// EquateEmpty returns a Comparer option that determines all maps and slices
+// EquateEmpty returns a [cmp.Comparer] option that determines all maps and slices
 // with a length of zero to be equal, regardless of whether they are nil.
 //
-// EquateEmpty can be used in conjunction with SortSlices and SortMaps.
+// EquateEmpty can be used in conjunction with [SortSlices] and [SortMaps].
 func EquateEmpty() cmp.Option {
 	return cmp.FilterValues(isEmpty, cmp.Comparer(equateAlways))
 }
@@ -31,7 +31,7 @@ func isEmpty(x, y interface{}) bool {
 		(vx.Len() == 0 && vy.Len() == 0)
 }
 
-// EquateApprox returns a Comparer option that determines float32 or float64
+// EquateApprox returns a [cmp.Comparer] option that determines float32 or float64
 // values to be equal if they are within a relative fraction or absolute margin.
 // This option is not used when either x or y is NaN or infinite.
 //
@@ -45,7 +45,7 @@ func isEmpty(x, y interface{}) bool {
 //
 //	|x-y| ≤ max(fraction*min(|x|, |y|), margin)
 //
-// EquateApprox can be used in conjunction with EquateNaNs.
+// EquateApprox can be used in conjunction with [EquateNaNs].
 func EquateApprox(fraction, margin float64) cmp.Option {
 	if margin < 0 || fraction < 0 || math.IsNaN(margin) || math.IsNaN(fraction) {
 		panic("margin or fraction must be a non-negative number")
@@ -73,10 +73,10 @@ func (a approximator) compareF32(x, y float32) bool {
 	return a.compareF64(float64(x), float64(y))
 }
 
-// EquateNaNs returns a Comparer option that determines float32 and float64
+// EquateNaNs returns a [cmp.Comparer] option that determines float32 and float64
 // NaN values to be equal.
 //
-// EquateNaNs can be used in conjunction with EquateApprox.
+// EquateNaNs can be used in conjunction with [EquateApprox].
 func EquateNaNs() cmp.Option {
 	return cmp.Options{
 		cmp.FilterValues(areNaNsF64s, cmp.Comparer(equateAlways)),
@@ -91,8 +91,8 @@ func areNaNsF32s(x, y float32) bool {
 	return areNaNsF64s(float64(x), float64(y))
 }
 
-// EquateApproxTime returns a Comparer option that determines two non-zero
-// time.Time values to be equal if they are within some margin of one another.
+// EquateApproxTime returns a [cmp.Comparer] option that determines two non-zero
+// [time.Time] values to be equal if they are within some margin of one another.
 // If both times have a monotonic clock reading, then the monotonic time
 // difference will be used. The margin must be non-negative.
 func EquateApproxTime(margin time.Duration) cmp.Option {
@@ -131,8 +131,8 @@ type anyError struct{}
 func (anyError) Error() string     { return "any error" }
 func (anyError) Is(err error) bool { return err != nil }
 
-// EquateErrors returns a Comparer option that determines errors to be equal
-// if errors.Is reports them to match. The AnyError error can be used to
+// EquateErrors returns a [cmp.Comparer] option that determines errors to be equal
+// if [errors.Is] reports them to match. The [AnyError] error can be used to
 // match any non-nil error.
 func EquateErrors() cmp.Option {
 	return cmp.FilterValues(areConcreteErrors, cmp.Comparer(compareErrors))

cmp/cmpopts/ignore.go

@@ -14,7 +14,7 @@ import (
 	"github.com/google/go-cmp/cmp/internal/function"
 )
 
-// IgnoreFields returns an Option that ignores fields of the
+// IgnoreFields returns an [cmp.Option] that ignores fields of the
 // given names on a single struct type. It respects the names of exported fields
 // that are forwarded due to struct embedding.
 // The struct type is specified by passing in a value of that type.
@@ -26,7 +26,7 @@ func IgnoreFields(typ interface{}, names ...string) cmp.Option {
 	return cmp.FilterPath(sf.filter, cmp.Ignore())
 }
 
-// IgnoreTypes returns an Option that ignores all values assignable to
+// IgnoreTypes returns an [cmp.Option] that ignores all values assignable to
 // certain types, which are specified by passing in a value of each type.
 func IgnoreTypes(typs ...interface{}) cmp.Option {
 	tf := newTypeFilter(typs...)
@@ -59,10 +59,10 @@ func (tf typeFilter) filter(p cmp.Path) bool {
 	return false
 }
 
-// IgnoreInterfaces returns an Option that ignores all values or references of
+// IgnoreInterfaces returns an [cmp.Option] that ignores all values or references of
 // values assignable to certain interface types. These interfaces are specified
 // by passing in an anonymous struct with the interface types embedded in it.
-// For example, to ignore sync.Locker, pass in struct{sync.Locker}{}.
+// For example, to ignore [sync.Locker], pass in struct{sync.Locker}{}.
 func IgnoreInterfaces(ifaces interface{}) cmp.Option {
 	tf := newIfaceFilter(ifaces)
 	return cmp.FilterPath(tf.filter, cmp.Ignore())
@@ -107,15 +107,15 @@ func (tf ifaceFilter) filter(p cmp.Path) bool {
 	return false
 }
 
-// IgnoreUnexported returns an Option that only ignores the immediate unexported
+// IgnoreUnexported returns an [cmp.Option] that only ignores the immediate unexported
 // fields of a struct, including anonymous fields of unexported types.
 // In particular, unexported fields within the struct's exported fields
 // of struct types, including anonymous fields, will not be ignored unless the
 // type of the field itself is also passed to IgnoreUnexported.
 //
 // Avoid ignoring unexported fields of a type which you do not control (i.e. a
 // type from another repository), as changes to the implementation of such types
-// may change how the comparison behaves. Prefer a custom Comparer instead.
+// may change how the comparison behaves. Prefer a custom [cmp.Comparer] instead.
 func IgnoreUnexported(typs ...interface{}) cmp.Option {
 	ux := newUnexportedFilter(typs...)
 	return cmp.FilterPath(ux.filter, cmp.Ignore())
@@ -148,7 +148,7 @@ func isExported(id string) bool {
 	return unicode.IsUpper(r)
 }
 
-// IgnoreSliceElements returns an Option that ignores elements of []V.
+// IgnoreSliceElements returns an [cmp.Option] that ignores elements of []V.
 // The discard function must be of the form "func(T) bool" which is used to
 // ignore slice elements of type V, where V is assignable to T.
 // Elements are ignored if the function reports true.
@@ -176,7 +176,7 @@ func IgnoreSliceElements(discardFunc interface{}) cmp.Option {
 	}, cmp.Ignore())
 }
 
-// IgnoreMapEntries returns an Option that ignores entries of map[K]V.
+// IgnoreMapEntries returns an [cmp.Option] that ignores entries of map[K]V.
 // The discard function must be of the form "func(T, R) bool" which is used to
 // ignore map entries of type K and V, where K and V are assignable to T and R.
 // Entries are ignored if the function reports true.

cmp/cmpopts/sort.go

@@ -13,7 +13,7 @@ import (
 	"github.com/google/go-cmp/cmp/internal/function"
 )
 
-// SortSlices returns a Transformer option that sorts all []V.
+// SortSlices returns a [cmp.Transformer] option that sorts all []V.
 // The less function must be of the form "func(T, T) bool" which is used to
 // sort any slice with element type V that is assignable to T.
 //
@@ -25,7 +25,7 @@ import (
 // The less function does not have to be "total". That is, if !less(x, y) and
 // !less(y, x) for two elements x and y, their relative order is maintained.
 //
-// SortSlices can be used in conjunction with EquateEmpty.
+// SortSlices can be used in conjunction with [EquateEmpty].
 func SortSlices(lessFunc interface{}) cmp.Option {
 	vf := reflect.ValueOf(lessFunc)
 	if !function.IsType(vf.Type(), function.Less) || vf.IsNil() {
@@ -82,21 +82,21 @@ func (ss sliceSorter) less(v reflect.Value, i, j int) bool {
 	return ss.fnc.Call([]reflect.Value{vx, vy})[0].Bool()
 }
 
-// SortMaps returns a Transformer option that flattens map[K]V types to be a
+// SortMaps returns a [cmp.Transformer] option that flattens map[K]V types to be a
 // sorted []struct{K, V}. The less function must be of the form
 // "func(T, T) bool" which is used to sort any map with key K that is
 // assignable to T.
 //
-// Flattening the map into a slice has the property that cmp.Equal is able to
-// use Comparers on K or the K.Equal method if it exists.
+// Flattening the map into a slice has the property that [cmp.Equal] is able to
+// use [cmp.Comparer] options on K or the K.Equal method if it exists.
 //
 // The less function must be:
 //   - Deterministic: less(x, y) == less(x, y)
 //   - Irreflexive: !less(x, x)
 //   - Transitive: if !less(x, y) and !less(y, z), then !less(x, z)
 //   - Total: if x != y, then either less(x, y) or less(y, x)
 //
-// SortMaps can be used in conjunction with EquateEmpty.
+// SortMaps can be used in conjunction with [EquateEmpty].
 func SortMaps(lessFunc interface{}) cmp.Option {
 	vf := reflect.ValueOf(lessFunc)
 	if !function.IsType(vf.Type(), function.Less) || vf.IsNil() {

cmp/cmpopts/xform.go

@@ -19,7 +19,7 @@ func (xf xformFilter) filter(p cmp.Path) bool {
 	return true
 }
 
-// AcyclicTransformer returns a Transformer with a filter applied that ensures
+// AcyclicTransformer returns a [cmp.Transformer] with a filter applied that ensures
 // that the transformer cannot be recursively applied upon its own output.
 //
 // An example use case is a transformer that splits a string by lines:
@@ -28,7 +28,7 @@ func (xf xformFilter) filter(p cmp.Path) bool {
 //		return strings.Split(s, "\n")
 //	})
 //
-// Had this been an unfiltered Transformer instead, this would result in an
+// Had this been an unfiltered [cmp.Transformer] instead, this would result in an
 // infinite cycle converting a string to []string to [][]string and so on.
 func AcyclicTransformer(name string, xformFunc interface{}) cmp.Option {
 	xf := xformFilter{cmp.Transformer(name, xformFunc)}

cmp/compare.go

@@ -5,7 +5,7 @@
 // Package cmp determines equality of values.
 //
 // This package is intended to be a more powerful and safer alternative to
-// reflect.DeepEqual for comparing whether two values are semantically equal.
+// [reflect.DeepEqual] for comparing whether two values are semantically equal.
 // It is intended to only be used in tests, as performance is not a goal and
 // it may panic if it cannot compare the values. Its propensity towards
 // panicking means that its unsuitable for production environments where a
@@ -18,16 +18,17 @@
 //     For example, an equality function may report floats as equal so long as
 //     they are within some tolerance of each other.
 //
-//   - Types with an Equal method may use that method to determine equality.
-//     This allows package authors to determine the equality operation
-//     for the types that they define.
+//   - Types with an Equal method (e.g., [time.Time.Equal]) may use that method
+//     to determine equality. This allows package authors to determine
+//     the equality operation for the types that they define.
 //
 //   - If no custom equality functions are used and no Equal method is defined,
 //     equality is determined by recursively comparing the primitive kinds on
-//     both values, much like reflect.DeepEqual. Unlike reflect.DeepEqual,
+//     both values, much like [reflect.DeepEqual]. Unlike [reflect.DeepEqual],
 //     unexported fields are not compared by default; they result in panics
-//     unless suppressed by using an Ignore option (see cmpopts.IgnoreUnexported)
-//     or explicitly compared using the Exporter option.
+//     unless suppressed by using an [Ignore] option
+//     (see [github.com/google/go-cmp/cmp/cmpopts.IgnoreUnexported])
+//     or explicitly compared using the [Exporter] option.
 package cmp
 
 import (
@@ -45,14 +46,14 @@ import (
 // Equal reports whether x and y are equal by recursively applying the
 // following rules in the given order to x and y and all of their sub-values:
 //
-//   - Let S be the set of all Ignore, Transformer, and Comparer options that
+//   - Let S be the set of all [Ignore], [Transformer], and [Comparer] options that
 //     remain after applying all path filters, value filters, and type filters.
-//     If at least one Ignore exists in S, then the comparison is ignored.
-//     If the number of Transformer and Comparer options in S is non-zero,
+//     If at least one [Ignore] exists in S, then the comparison is ignored.
+//     If the number of [Transformer] and [Comparer] options in S is non-zero,
 //     then Equal panics because it is ambiguous which option to use.
-//     If S contains a single Transformer, then use that to transform
+//     If S contains a single [Transformer], then use that to transform
 //     the current values and recursively call Equal on the output values.
-//     If S contains a single Comparer, then use that to compare the current values.
+//     If S contains a single [Comparer], then use that to compare the current values.
 //     Otherwise, evaluation proceeds to the next rule.
 //
 //   - If the values have an Equal method of the form "(T) Equal(T) bool" or
@@ -66,21 +67,22 @@ import (
 //     Functions are only equal if they are both nil, otherwise they are unequal.
 //
 // Structs are equal if recursively calling Equal on all fields report equal.
-// If a struct contains unexported fields, Equal panics unless an Ignore option
-// (e.g., cmpopts.IgnoreUnexported) ignores that field or the Exporter option
-// explicitly permits comparing the unexported field.
+// If a struct contains unexported fields, Equal panics unless an [Ignore] option
+// (e.g., [github.com/google/go-cmp/cmp/cmpopts.IgnoreUnexported]) ignores that field
+// or the [Exporter] option explicitly permits comparing the unexported field.
 //
 // Slices are equal if they are both nil or both non-nil, where recursively
 // calling Equal on all non-ignored slice or array elements report equal.
 // Empty non-nil slices and nil slices are not equal; to equate empty slices,
-// consider using cmpopts.EquateEmpty.
+// consider using [github.com/google/go-cmp/cmp/cmpopts.EquateEmpty].
 //
 // Maps are equal if they are both nil or both non-nil, where recursively
 // calling Equal on all non-ignored map entries report equal.
 // Map keys are equal according to the == operator.
-// To use custom comparisons for map keys, consider using cmpopts.SortMaps.
+// To use custom comparisons for map keys, consider using
+// [github.com/google/go-cmp/cmp/cmpopts.SortMaps].
 // Empty non-nil maps and nil maps are not equal; to equate empty maps,
-// consider using cmpopts.EquateEmpty.
+// consider using [github.com/google/go-cmp/cmp/cmpopts.EquateEmpty].
 //
 // Pointers and interfaces are equal if they are both nil or both non-nil,
 // where they have the same underlying concrete type and recursively

cmp/example_test.go

@@ -61,7 +61,8 @@ func ExampleDiff_testing() {
 // comparer on floats that determines two values to be equal if they are within
 // some range of each other.
 //
-// This example is for demonstrative purposes; use cmpopts.EquateApprox instead.
+// This example is for demonstrative purposes;
+// use [github.com/google/go-cmp/cmp/cmpopts.EquateApprox] instead.
 func ExampleOption_approximateFloats() {
 	// This Comparer only operates on float64.
 	// To handle float32s, either define a similar function for that type
@@ -89,7 +90,8 @@ func ExampleOption_approximateFloats() {
 // Normal floating-point arithmetic defines == to be false when comparing
 // NaN with itself. In certain cases, this is not the desired property.
 //
-// This example is for demonstrative purposes; use cmpopts.EquateNaNs instead.
+// This example is for demonstrative purposes;
+// use [github.com/google/go-cmp/cmp/cmpopts.EquateNaNs] instead.
 func ExampleOption_equalNaNs() {
 	// This Comparer only operates on float64.
 	// To handle float32s, either define a similar function for that type
@@ -117,7 +119,7 @@ func ExampleOption_equalNaNs() {
 // to restrict the scope of the comparison so that they are composable.
 //
 // This example is for demonstrative purposes;
-// use cmpopts.EquateNaNs and cmpopts.EquateApprox instead.
+// use [github.com/google/go-cmp/cmp/cmpopts.EquateApprox] instead.
 func ExampleOption_equalNaNsAndApproximateFloats() {
 	alwaysEqual := cmp.Comparer(func(_, _ interface{}) bool { return true })
 
@@ -156,7 +158,8 @@ func ExampleOption_equalNaNsAndApproximateFloats() {
 // Sometimes, an empty map or slice is considered equal to an allocated one
 // of zero length.
 //
-// This example is for demonstrative purposes; use cmpopts.EquateEmpty instead.
+// This example is for demonstrative purposes;
+// use [github.com/google/go-cmp/cmp/cmpopts.EquateEmpty] instead.
 func ExampleOption_equalEmpty() {
 	alwaysEqual := cmp.Comparer(func(_, _ interface{}) bool { return true })
 
@@ -190,7 +193,8 @@ func ExampleOption_equalEmpty() {
 // regardless of the order that they appear in. Transformations can be used
 // to sort the slice.
 //
-// This example is for demonstrative purposes; use cmpopts.SortSlices instead.
+// This example is for demonstrative purposes;
+// use [github.com/google/go-cmp/cmp/cmpopts.SortSlices] instead.
 func ExampleOption_sortedSlice() {
 	// This Transformer sorts a []int.
 	trans := cmp.Transformer("Sort", func(in []int) []int {