go/analysis/passes/nilness: add longer example to doc

Fixes Google Issue 331478795

Change-Id: I0258bdd6a50000effc66c4e1fe03f99e2720c0cc
Reviewed-on: https://go-review.googlesource.com/c/tools/+/575056
Reviewed-by: Ian Lance Taylor <[email protected]>
Auto-Submit: Alan Donovan <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: adonovan

go/analysis/passes/nilness/doc.go

@@ -42,4 +42,31 @@
 //	if p == nil {
 //		panic(p)
 //	}
+//
+// Sometimes the control flow may be quite complex, making bugs hard
+// to spot. In the example below, the err.Error expression is
+// guaranteed to panic because, after the first return, err must be
+// nil. The intervening loop is just a distraction.
+//
+//	...
+//	err := g.Wait()
+//	if err != nil {
+//		return err
+//	}
+//	partialSuccess := false
+//	for _, err := range errs {
+//		if err == nil {
+//			partialSuccess = true
+//			break
+//		}
+//	}
+//	if partialSuccess {
+//		reportStatus(StatusMessage{
+//			Code:   code.ERROR,
+//			Detail: err.Error(), // "nil dereference in dynamic method call"
+//		})
+//		return nil
+//	}
+//
+// ...
 package nilness

gopls/doc/analyzers.md

@@ -479,6 +479,33 @@ and:
 		panic(p)
 	}
 
+Sometimes the control flow may be quite complex, making bugs hard
+to spot. In the example below, the err.Error expression is
+guaranteed to panic because, after the first return, err must be
+nil. The intervening loop is just a distraction.
+
+	...
+	err := g.Wait()
+	if err != nil {
+		return err
+	}
+	partialSuccess := false
+	for _, err := range errs {
+		if err == nil {
+			partialSuccess = true
+			break
+		}
+	}
+	if partialSuccess {
+		reportStatus(StatusMessage{
+			Code:   code.ERROR,
+			Detail: err.Error(), // "nil dereference in dynamic method call"
+		})
+		return nil
+	}
+
+...
+
 [Full documentation](https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/nilness)
 
 **Enabled by default.**