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 <iant@google.com>
Auto-Submit: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

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.**

gopls/internal/settings/api_json.go

@@ -340,7 +340,7 @@ var GeneratedAPIJSON = &APIJSON{
 						},
 						{
 							Name:    "\"nilness\"",
-							Doc:     "check for redundant or impossible nil comparisons\n\nThe nilness checker inspects the control-flow graph of each function in\na package and reports nil pointer dereferences, degenerate nil\npointers, and panics with nil values. A degenerate comparison is of the form\nx==nil or x!=nil where x is statically known to be nil or non-nil. These are\noften a mistake, especially in control flow related to errors. Panics with nil\nvalues are checked because they are not detectable by\n\n\tif r := recover(); r != nil {\n\nThis check reports conditions such as:\n\n\tif f == nil { // impossible condition (f is a function)\n\t}\n\nand:\n\n\tp := &v\n\t...\n\tif p != nil { // tautological condition\n\t}\n\nand:\n\n\tif p == nil {\n\t\tprint(*p) // nil dereference\n\t}\n\nand:\n\n\tif p == nil {\n\t\tpanic(p)\n\t}",
+							Doc:     "check for redundant or impossible nil comparisons\n\nThe nilness checker inspects the control-flow graph of each function in\na package and reports nil pointer dereferences, degenerate nil\npointers, and panics with nil values. A degenerate comparison is of the form\nx==nil or x!=nil where x is statically known to be nil or non-nil. These are\noften a mistake, especially in control flow related to errors. Panics with nil\nvalues are checked because they are not detectable by\n\n\tif r := recover(); r != nil {\n\nThis check reports conditions such as:\n\n\tif f == nil { // impossible condition (f is a function)\n\t}\n\nand:\n\n\tp := &v\n\t...\n\tif p != nil { // tautological condition\n\t}\n\nand:\n\n\tif p == nil {\n\t\tprint(*p) // nil dereference\n\t}\n\nand:\n\n\tif p == nil {\n\t\tpanic(p)\n\t}\n\nSometimes the control flow may be quite complex, making bugs hard\nto spot. In the example below, the err.Error expression is\nguaranteed to panic because, after the first return, err must be\nnil. The intervening loop is just a distraction.\n\n\t...\n\terr := g.Wait()\n\tif err != nil {\n\t\treturn err\n\t}\n\tpartialSuccess := false\n\tfor _, err := range errs {\n\t\tif err == nil {\n\t\t\tpartialSuccess = true\n\t\t\tbreak\n\t\t}\n\t}\n\tif partialSuccess {\n\t\treportStatus(StatusMessage{\n\t\t\tCode:   code.ERROR,\n\t\t\tDetail: err.Error(), // \"nil dereference in dynamic method call\"\n\t\t})\n\t\treturn nil\n\t}\n\n...",
 							Default: "true",
 						},
 						{
@@ -1121,7 +1121,7 @@ var GeneratedAPIJSON = &APIJSON{
 		},
 		{
 			Name:    "nilness",
-			Doc:     "check for redundant or impossible nil comparisons\n\nThe nilness checker inspects the control-flow graph of each function in\na package and reports nil pointer dereferences, degenerate nil\npointers, and panics with nil values. A degenerate comparison is of the form\nx==nil or x!=nil where x is statically known to be nil or non-nil. These are\noften a mistake, especially in control flow related to errors. Panics with nil\nvalues are checked because they are not detectable by\n\n\tif r := recover(); r != nil {\n\nThis check reports conditions such as:\n\n\tif f == nil { // impossible condition (f is a function)\n\t}\n\nand:\n\n\tp := &v\n\t...\n\tif p != nil { // tautological condition\n\t}\n\nand:\n\n\tif p == nil {\n\t\tprint(*p) // nil dereference\n\t}\n\nand:\n\n\tif p == nil {\n\t\tpanic(p)\n\t}",
+			Doc:     "check for redundant or impossible nil comparisons\n\nThe nilness checker inspects the control-flow graph of each function in\na package and reports nil pointer dereferences, degenerate nil\npointers, and panics with nil values. A degenerate comparison is of the form\nx==nil or x!=nil where x is statically known to be nil or non-nil. These are\noften a mistake, especially in control flow related to errors. Panics with nil\nvalues are checked because they are not detectable by\n\n\tif r := recover(); r != nil {\n\nThis check reports conditions such as:\n\n\tif f == nil { // impossible condition (f is a function)\n\t}\n\nand:\n\n\tp := &v\n\t...\n\tif p != nil { // tautological condition\n\t}\n\nand:\n\n\tif p == nil {\n\t\tprint(*p) // nil dereference\n\t}\n\nand:\n\n\tif p == nil {\n\t\tpanic(p)\n\t}\n\nSometimes the control flow may be quite complex, making bugs hard\nto spot. In the example below, the err.Error expression is\nguaranteed to panic because, after the first return, err must be\nnil. The intervening loop is just a distraction.\n\n\t...\n\terr := g.Wait()\n\tif err != nil {\n\t\treturn err\n\t}\n\tpartialSuccess := false\n\tfor _, err := range errs {\n\t\tif err == nil {\n\t\t\tpartialSuccess = true\n\t\t\tbreak\n\t\t}\n\t}\n\tif partialSuccess {\n\t\treportStatus(StatusMessage{\n\t\t\tCode:   code.ERROR,\n\t\t\tDetail: err.Error(), // \"nil dereference in dynamic method call\"\n\t\t})\n\t\treturn nil\n\t}\n\n...",
 			URL:     "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/nilness",
 			Default: true,
 		},