go/analysis/passes/errorsas: add example of invalid errors.As use

Change-Id: I09ea4efab1631bc46f740d2e2bb5546a6a6a6922
Reviewed-on: https://go-review.googlesource.com/c/tools/+/773920
LUCI-TryBot-Result: golang-scoped@luci-project-accounts.iam.gserviceaccount.com <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
Reviewed-by: Cherry Mui <cherryyz@google.com>

Author: mateusz834

go/analysis/passes/errorsas/errorsas.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The errorsas package defines an Analyzer that checks that the second argument to
-// errors.As is a pointer to a type implementing error.
+// Package errorsas defines an Analyzer that checks that the second argument to
+// [errors.As] is a pointer to a type implementing error.
 package errorsas
 
 import (
@@ -19,7 +19,12 @@ import (
 const Doc = `report passing non-pointer or non-error values to errors.As
 
 The errorsas analyzer reports calls to errors.As where the type
-of the second argument is not a pointer to a type implementing error.`
+of the second argument is not a pointer to a type implementing error.
+For example:
+
+	var unwrappedErr net.DNSError
+	errors.As(err, unwrappedErr) // should use &unwrappedErr, DNSError.Error has a pointer reciever
+`
 
 var Analyzer = &analysis.Analyzer{
 	Name:     "errorsas",

gopls/doc/analyzers.md

@@ -3139,7 +3139,10 @@ Package documentation: [embedlit](https://pkg.go.dev/golang.org/x/tools/go/analy
 <a id='errorsas'></a>
 ## `errorsas`: report passing non-pointer or non-error values to errors.As
 
-The errorsas analyzer reports calls to errors.As where the type of the second argument is not a pointer to a type implementing error.
+The errorsas analyzer reports calls to errors.As where the type of the second argument is not a pointer to a type implementing error. For example:
+
+	var unwrappedErr net.DNSError
+	errors.As(err, unwrappedErr) // should use &unwrappedErr, DNSError.Error has a pointer reciever
 
 
 Default: on.

gopls/internal/doc/api.json

@@ -1462,7 +1462,7 @@
 						},
 						{
 							"Name": "\"errorsas\"",
-							"Doc": "report passing non-pointer or non-error values to errors.As\n\nThe errorsas analyzer reports calls to errors.As where the type\nof the second argument is not a pointer to a type implementing error.",
+							"Doc": "report passing non-pointer or non-error values to errors.As\n\nThe errorsas analyzer reports calls to errors.As where the type\nof the second argument is not a pointer to a type implementing error.\nFor example:\n\n\tvar unwrappedErr net.DNSError\n\terrors.As(err, unwrappedErr) // should use \u0026unwrappedErr, DNSError.Error has a pointer reciever\n",
 							"Default": "true",
 							"Status": ""
 						},
@@ -3421,7 +3421,7 @@
 		},
 		{
 			"Name": "errorsas",
-			"Doc": "report passing non-pointer or non-error values to errors.As\n\nThe errorsas analyzer reports calls to errors.As where the type\nof the second argument is not a pointer to a type implementing error.",
+			"Doc": "report passing non-pointer or non-error values to errors.As\n\nThe errorsas analyzer reports calls to errors.As where the type\nof the second argument is not a pointer to a type implementing error.\nFor example:\n\n\tvar unwrappedErr net.DNSError\n\terrors.As(err, unwrappedErr) // should use \u0026unwrappedErr, DNSError.Error has a pointer reciever\n",
 			"URL": "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/errorsas",
 			"Default": true
 		},