From 955b6ffa23392faabba24e4eb9f448cb891f60ec Mon Sep 17 00:00:00 2001
From: TheDiveO <TheDiveO@users.noreply.github.com>
Date: Wed, 15 Dec 2021 20:53:30 +0100
Subject: [PATCH] document HaveValue matcher (#486)

---
 _includes/gomega_sidebar.html |  9 +++++++++
 index.md                      | 20 ++++++++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/_includes/gomega_sidebar.html b/_includes/gomega_sidebar.html
index 2366e1a7d..fafbd6404 100644
--- a/_includes/gomega_sidebar.html
+++ b/_includes/gomega_sidebar.html
@@ -201,6 +201,15 @@ <h2>
                 </ul>
             </li>
 
+            <li>
+                <a href="#working-with-values">Working with Values</a>
+                <ul class="nav">
+                    <li>
+                        <a href="#havevaluematcher-typesgomegamatcher"><code>HaveValue(...)</code></a>
+                    </li>
+                </ul>
+            </li>
+
             <li>
                 <a href="#working-with-http-responses">Working with HTTP responses</a>
                 <ul class="nav">
diff --git a/index.md b/index.md
index cf4bcc6de..25820d8bb 100644
--- a/index.md
+++ b/index.md
@@ -1121,6 +1121,26 @@ There are six supported comparators:
 
 Any other comparator is an error.
 
+### Working with Values
+
+#### HaveValue(matcher types.GomegaMatcher)
+
+`HaveValue` applies `MATCHER` to the value that results from dereferencing `ACTUAL` in case of a pointer or an interface, or otherwise `ACTUAL` itself. Pointers and interfaces are dereferenced multiple times as necessary, with a limit of at most 31 dereferences.
+
+```go
+    Expect(ACTUAL).To(HaveValue(MATCHER))
+```
+
+For instance:
+
+```go
+    i := 42
+    Expect(&i).To(HaveValue(Equal(42)))
+    Expect(i).To(HaveValue(Equal(42)))
+```
+
+`HaveValue` can be used, for instance, in tests and custom matchers where the it doesn't matter (as opposed to `PointTo`) if a value first needs to be dereferenced or not. This is especially useful to custom matchers that are to be used in mixed contexts of pointers as well as non-pointers.
+
 ### Working with HTTP responses
 
 #### HaveHTTPStatus(expected interface{})