docs: Receive(POINTER, MATCHER)

Signed-off-by: thediveo <[email protected]>

Author: thediveo

docs/index.md

@@ -877,7 +877,7 @@ Finally, as a corollary: it is an error to check whether or not a send-only chan
 #### Receive()
 
 ```go
-Ω(ACTUAL).Should(Receive(<optionalPointer>))
+Ω(ACTUAL).Should(Receive(<optionalPointer>, <optionalMatcher>))
 ```
 
 succeeds if there is a message to be received on actual. Actual must be a channel (and cannot be a send-only channel) -- anything else is an error.
@@ -930,6 +930,14 @@ Eventually(bagelChan).Should(Receive(&receivedBagel))
 
 Of course, this could have been written as `receivedBagel := <-bagelChan` - however using `Receive` makes it easy to avoid hanging the test suite should nothing ever come down the channel. The pointer can point to any variable whose type is assignable from the channel element type, or if the channel type is an interface and the underlying type is assignable to the pointer.
 
+Sometimes, you might need to *grab* the object that *matches* certain criteria:
+
+```go
+var receivedBagel Bagel
+Eventually(bagelChan).Should(Receive(&receivedBagel, HaveField("Kind", "sesame")))
+Ω(receivedBagel.Contents()).Should(ContainElement("cream cheese"))
+```
+
 Finally, `Receive` *never* blocks.  `Eventually(c).Should(Receive())` repeatedly polls `c` in a non-blocking fashion.  That means that you cannot use this pattern to verify that a *non-blocking send* has occurred on the channel - [more details at this GitHub issue](https://github.com/onsi/gomega/issues/82).
 
 #### BeSent(value interface{})