From b8636ade4f58fa61c5c59e0fab994ed84794113a Mon Sep 17 00:00:00 2001
From: TheDiveO <6920158+thediveo@users.noreply.github.com>
Date: Wed, 21 Sep 2022 21:48:06 +0200
Subject: [PATCH] documentation updates for BeKeyOf and well-known non-leaky
 goroutines (#592)

---
 docs/index.md | 21 +++++++++++++++++++--
 matchers.go   |  2 +-
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 4c4881001..c54973137 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -970,10 +970,25 @@ succeeds if `ACTUAL` equals one of the elements passed into the matcher. When a
 #### BeKeyOf(m interface{})
 
 ```go
-Ω(ACTUAL).Should(BeKeyOf(ELEMENT))
+Ω(ACTUAL).Should(BeKeyOf(MAP))
 ```
 
-succeeds if `ACTUAL` equals one of the keys of the map passed into the matcher. `BeKeyOf` always uses the `Equal()` matcher under the hood to assert equality with a map key.
+succeeds if `ACTUAL` equals one of the keys of `MAP`. It is an error for `MAP` to be of any type other than a map. `BeKeyOf` always uses the `Equal()` matcher under the hood to assert equality of `ACTUAL` with a map key.
+
+`BeKeyOf` can be used in situations where it is not possible to rewrite an assertion to use the more idiomatic `HaveKey`: one use is in combination with `ContainElement` doubling as a filter. For instance, the following example asserts that all expected specific sprockets are present in a larger list of sprockets:
+
+```go
+var names = map[string]struct {
+	detail string
+}{
+	"edgy_emil":              {detail: "sprocket_project_A"},
+	"furious_freddy":         {detail: "sprocket_project_B"},
+}
+
+var canaries []Sprocket
+Expect(projects).To(ContainElement(HaveField("Name", BeKeyOf(names)), &canaries))
+Expect(canaries).To(HaveLen(len(names)))
+```
 
 #### ConsistOf(element ...interface{})
 
@@ -3264,6 +3279,8 @@ names of the topmost functions on their stacks (backtraces):
   inner functions),
   - the anonymous inner functions of
   `github.com/onsi/ginkgo/v2/internal/interrupt_handler.(*InterruptHandler).registerForInterrupts`,
+  - the creators `github.com/onsi/ginkgo/v2/internal.(*genericOutputInterceptor).ResumeIntercepting` and `github.com/onsi/ginkgo/v2/internal.(*genericOutputInterceptor).ResumeIntercepting...`,
+  - the creator `github.com/onsi/ginkgo/v2/internal.RegisterForProgressSignal`,
   - and finally
   `github.com/onsi/ginkgo/internal/specrunner.(*SpecRunner).registerForInterrupts`
   (for v1 support).
diff --git a/matchers.go b/matchers.go
index 458a23267..f9d9f2aad 100644
--- a/matchers.go
+++ b/matchers.go
@@ -318,7 +318,7 @@ func BeElementOf(elements ...interface{}) types.GomegaMatcher {
 }
 
 // BeKeyOf succeeds if actual is contained in the keys of the passed in map.
-// BeKeyOf() always uses Equal() to perform the match.
+// BeKeyOf() always uses Equal() to perform the match between actual and the map keys.
 //
 //	Expect("foo").Should(BeKeyOf(map[string]bool{"foo": true, "bar": false}))
 func BeKeyOf(element interface{}) types.GomegaMatcher {