The use of `reflect.DeepEqual()` inside `Eq()` matcher is not trivial but not documented.

[your-diary]

After reading both of the function name (i.e. Eq()) and its doc comments (text + examples), one cannot infer the result of this simple code:

s1 := "hello"
s2 := "hello"
t.Log(&s1 == &s2)                  //=> false
t.Log(gomock.Eq(&s1).Matches(&s2)) //=> ???

Actually ??? is true because reflect.DeepEqual() is called inside Eq() matcher: source

Is this behavior guaranteed but not just documented? In other words, it this a documentation bug? Or is this an implementation bug?

---

After reading all of these three, there is still an ambiguity what is "equality":

• The name of the function is just "Eq" (not something like DeepEq)

• Its document just says

  Eq returns a matcher that matches on equality.

• Its example is

  Eq(5).Matches(5) // returns true
  Eq(5).Matches(4) // returns false