Update BeComparableTo documentation

Author: onsi

docs/index.md

@@ -659,6 +659,14 @@ When both `ACTUAL` and `EXPECTED` are a very long strings, it will attempt to pr
 
 > For asserting equality between numbers of different types, you'll want to use the [`BeNumerically()`](#benumericallycomparator-string-compareto-interface) matcher.
 
+#### BeComparableTo(expected interface{}, options ...cmp.Option)
+
+```go
+Ω(ACTUAL).Should(BeComparableTo(EXPECTED, options ...cmp.Option))
+```
+
+uses [`gocmp.Equal`](http://github.com/google/go-cmp) from `github.com/google/go-cmp` to compare `ACTUAL` with `EXPECTED`.  This performs a deep object comparison like `reflect.DeepEqual` but offers a few additional configuration options.  Learn more at the [go-cmp godocs](https://pkg.go.dev/github.com/google/go-cmp).
+
 #### BeEquivalentTo(expected interface{})
 
 ```go

matchers.go

@@ -27,7 +27,8 @@ func BeEquivalentTo(expected interface{}) types.GomegaMatcher {
 	}
 }
 
-// BeComparableTo uses gocmp.Equal to compare. You can pass cmp.Option as options.
+// BeComparableTo uses gocmp.Equal from github.com/google/go-cmp (instead of reflect.DeepEqual) to perform a deep comparison.
+// You can pass cmp.Option as options.
 // It is an error for actual and expected to be nil.  Use BeNil() instead.
 func BeComparableTo(expected interface{}, opts ...cmp.Option) types.GomegaMatcher {
 	return &matchers.BeComparableToMatcher{