55// Package cmp determines equality of values.
66//
77// This package is intended to be a more powerful and safer alternative to
8- // reflect.DeepEqual for comparing whether two values are semantically equal.
8+ // [ reflect.DeepEqual] for comparing whether two values are semantically equal.
99// It is intended to only be used in tests, as performance is not a goal and
1010// it may panic if it cannot compare the values. Its propensity towards
1111// panicking means that its unsuitable for production environments where a
1818// For example, an equality function may report floats as equal so long as
1919// they are within some tolerance of each other.
2020//
21- // - Types with an Equal method may use that method to determine equality.
22- // This allows package authors to determine the equality operation
23- // for the types that they define.
21+ // - Types with an Equal method (e.g., [time.Time.Equal]) may use that method
22+ // to determine equality. This allows package authors to determine
23+ // the equality operation for the types that they define.
2424//
2525// - If no custom equality functions are used and no Equal method is defined,
2626// equality is determined by recursively comparing the primitive kinds on
27- // both values, much like reflect.DeepEqual. Unlike reflect.DeepEqual,
27+ // both values, much like [ reflect.DeepEqual] . Unlike [ reflect.DeepEqual] ,
2828// unexported fields are not compared by default; they result in panics
29- // unless suppressed by using an Ignore option (see cmpopts.IgnoreUnexported)
30- // or explicitly compared using the Exporter option.
29+ // unless suppressed by using an [Ignore] option
30+ // (see [github.com/google/go-cmp/cmp/cmpopts.IgnoreUnexported])
31+ // or explicitly compared using the [Exporter] option.
3132package cmp
3233
3334import (
@@ -45,14 +46,14 @@ import (
4546// Equal reports whether x and y are equal by recursively applying the
4647// following rules in the given order to x and y and all of their sub-values:
4748//
48- // - Let S be the set of all Ignore, Transformer, and Comparer options that
49+ // - Let S be the set of all [ Ignore], [ Transformer] , and [ Comparer] options that
4950// remain after applying all path filters, value filters, and type filters.
50- // If at least one Ignore exists in S, then the comparison is ignored.
51- // If the number of Transformer and Comparer options in S is non-zero,
51+ // If at least one [ Ignore] exists in S, then the comparison is ignored.
52+ // If the number of [ Transformer] and [ Comparer] options in S is non-zero,
5253// then Equal panics because it is ambiguous which option to use.
53- // If S contains a single Transformer, then use that to transform
54+ // If S contains a single [ Transformer] , then use that to transform
5455// the current values and recursively call Equal on the output values.
55- // If S contains a single Comparer, then use that to compare the current values.
56+ // If S contains a single [ Comparer] , then use that to compare the current values.
5657// Otherwise, evaluation proceeds to the next rule.
5758//
5859// - If the values have an Equal method of the form "(T) Equal(T) bool" or
@@ -66,21 +67,22 @@ import (
6667// Functions are only equal if they are both nil, otherwise they are unequal.
6768//
6869// Structs are equal if recursively calling Equal on all fields report equal.
69- // If a struct contains unexported fields, Equal panics unless an Ignore option
70- // (e.g., cmpopts.IgnoreUnexported) ignores that field or the Exporter option
71- // explicitly permits comparing the unexported field.
70+ // If a struct contains unexported fields, Equal panics unless an [ Ignore] option
71+ // (e.g., [github.com/google/go-cmp/cmp/ cmpopts.IgnoreUnexported] ) ignores that field
72+ // or the [Exporter] option explicitly permits comparing the unexported field.
7273//
7374// Slices are equal if they are both nil or both non-nil, where recursively
7475// calling Equal on all non-ignored slice or array elements report equal.
7576// Empty non-nil slices and nil slices are not equal; to equate empty slices,
76- // consider using cmpopts.EquateEmpty.
77+ // consider using [github.com/google/go-cmp/cmp/ cmpopts.EquateEmpty] .
7778//
7879// Maps are equal if they are both nil or both non-nil, where recursively
7980// calling Equal on all non-ignored map entries report equal.
8081// Map keys are equal according to the == operator.
81- // To use custom comparisons for map keys, consider using cmpopts.SortMaps.
82+ // To use custom comparisons for map keys, consider using
83+ // [github.com/google/go-cmp/cmp/cmpopts.SortMaps].
8284// Empty non-nil maps and nil maps are not equal; to equate empty maps,
83- // consider using cmpopts.EquateEmpty.
85+ // consider using [github.com/google/go-cmp/cmp/ cmpopts.EquateEmpty] .
8486//
8587// Pointers and interfaces are equal if they are both nil or both non-nil,
8688// where they have the same underlying concrete type and recursively
0 commit comments