From 808d19201c2f4fe39ae38e7358a46e8d4964731d Mon Sep 17 00:00:00 2001
From: TheDiveO <6920158+thediveo@users.noreply.github.com>
Date: Sat, 12 Nov 2022 12:34:14 +0100
Subject: [PATCH] fixes issue #600 (#606)

- improves documentation for HaveValue with respect to nil and negation.
---
 docs/index.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/docs/index.md b/docs/index.md
index cbc37fb23..cee1d91c6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1356,7 +1356,7 @@ Any other comparator is an error.
 
 #### 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.
+`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. It will fail if the pointer value is `nil`:
 
 ```go
 Expect(ACTUAL).To(HaveValue(MATCHER))
@@ -1372,6 +1372,12 @@ 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.
 
+Please note that negating the outcome of `HaveValue(nil)` won't suppress any error; for instance, in order to assert not having a specific value while still accepting `nil` the following matcher expression might be used:
+
+```go
+Or(BeNil(), Not(HaveValue(...)))
+```
+
 ### Working with HTTP responses
 
 #### HaveHTTPStatus(expected interface{})