go/analysis: add Analyser.URL and Diagnostic.URI fields

These fields allow the analyzer to provide links to
its online documentation.

Also:
- set URI field for all x/tools Analyzers.
- include these URIs in the gopls docs.

Fixes golang/go#57906

Change-Id: Iec0a34386d834edfae4e9161a18a1d14a7a43b74
Reviewed-on: https://go-review.googlesource.com/c/tools/+/476615
Reviewed-by: Robert Findley <[email protected]>
Run-TryBot: Alan Donovan <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>
gopls-CI: kokoro <[email protected]>

Author: adonovan

go/analysis/analysis.go

@@ -24,6 +24,10 @@ type Analyzer struct {
 	// (no capital or period, max ~60 letters).
 	Doc string
 
+	// URL holds an optional link to a web page with additional
+	// documentation for this analyzer.
+	URL string
+
 	// Flags defines any flags accepted by the analyzer.
 	// The manner in which these flags are exposed to the user
 	// depends on the driver which runs the analyzer.

go/analysis/diagnostic.go

@@ -20,6 +20,17 @@ type Diagnostic struct {
 	Category string    // optional
 	Message  string
 
+	// URL is the optional location of a web page that provides
+	// additional documentation for this diagnostic.
+	//
+	// If URL is empty but a Category is specified, then the
+	// Analysis driver should treat the URL as "#"+Category.
+	//
+	// The URL may be relative. If so, the base URL is that of the
+	// Analyzer that produced the diagnostic;
+	// see https://pkg.go.dev/net/url#URL.ResolveReference.
+	URL string
+
 	// SuggestedFixes contains suggested fixes for a diagnostic which can be used to perform
 	// edits to a file that address the diagnostic.
 	// TODO(matloob): Should multiple SuggestedFixes be allowed for a diagnostic?

go/analysis/passes/asmdecl/asmdecl.go

@@ -27,6 +27,7 @@ const Doc = "report mismatches between assembly files and Go declarations"
 var Analyzer = &analysis.Analyzer{
 	Name: "asmdecl",
 	Doc:  Doc,
+	URL:  "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/asmdecl",
 	Run:  run,
 }
 

go/analysis/passes/assign/assign.go

@@ -30,6 +30,7 @@ usually a mistake.`
 var Analyzer = &analysis.Analyzer{
 	Name:     "assign",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/assign",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/atomic/atomic.go

@@ -28,6 +28,7 @@ which are not atomic.`
 var Analyzer = &analysis.Analyzer{
 	Name:             "atomic",
 	Doc:              Doc,
+	URL:              "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/atomic",
 	Requires:         []*analysis.Analyzer{inspect.Analyzer},
 	RunDespiteErrors: true,
 	Run:              run,

go/analysis/passes/atomicalign/atomicalign.go

@@ -25,6 +25,7 @@ const Doc = "check for non-64-bits-aligned arguments to sync/atomic functions"
 var Analyzer = &analysis.Analyzer{
 	Name:     "atomicalign",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/atomicalign",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/bools/bools.go

@@ -22,6 +22,7 @@ const Doc = "check for common mistakes involving boolean operators"
 var Analyzer = &analysis.Analyzer{
 	Name:     "bools",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/bools",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/buildssa/buildssa.go

@@ -22,6 +22,7 @@ import (
 var Analyzer = &analysis.Analyzer{
 	Name:       "buildssa",
 	Doc:        "build SSA-form IR for later passes",
+	URL:        "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/buildssa",
 	Run:        run,
 	ResultType: reflect.TypeOf(new(SSA)),
 }

go/analysis/passes/buildtag/buildtag.go

@@ -25,6 +25,7 @@ const Doc = "check //go:build and // +build directives"
 var Analyzer = &analysis.Analyzer{
 	Name: "buildtag",
 	Doc:  Doc,
+	URL:  "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/buildtag",
 	Run:  runBuildTag,
 }
 

go/analysis/passes/cgocall/cgocall.go

@@ -35,6 +35,7 @@ or slice to C, either directly, or via a pointer, array, or struct.`
 var Analyzer = &analysis.Analyzer{
 	Name:             "cgocall",
 	Doc:              Doc,
+	URL:              "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/cgocall",
 	RunDespiteErrors: true,
 	Run:              run,
 }

go/analysis/passes/composite/composite.go

@@ -37,6 +37,7 @@ should be replaced by:
 var Analyzer = &analysis.Analyzer{
 	Name:             "composites",
 	Doc:              Doc,
+	URL:              "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/composites",
 	Requires:         []*analysis.Analyzer{inspect.Analyzer},
 	RunDespiteErrors: true,
 	Run:              run,

go/analysis/passes/copylock/copylock.go

@@ -29,6 +29,7 @@ values should be referred to through a pointer.`
 var Analyzer = &analysis.Analyzer{
 	Name:             "copylocks",
 	Doc:              Doc,
+	URL:              "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/copylocks",
 	Requires:         []*analysis.Analyzer{inspect.Analyzer},
 	RunDespiteErrors: true,
 	Run:              run,

go/analysis/passes/ctrlflow/ctrlflow.go

@@ -24,6 +24,7 @@ import (
 var Analyzer = &analysis.Analyzer{
 	Name:       "ctrlflow",
 	Doc:        "build a control-flow graph",
+	URL:        "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/ctrlflow",
 	Run:        run,
 	ResultType: reflect.TypeOf(new(CFGs)),
 	FactTypes:  []analysis.Fact{new(noReturn)},

go/analysis/passes/deepequalerrors/deepequalerrors.go

@@ -28,6 +28,7 @@ errors is discouraged.`
 var Analyzer = &analysis.Analyzer{
 	Name:     "deepequalerrors",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/deepequalerrors",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/directive/directive.go

@@ -36,6 +36,7 @@ buildtag analyzer.
 var Analyzer = &analysis.Analyzer{
 	Name: "directive",
 	Doc:  Doc,
+	URL:  "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/directive",
 	Run:  runDirective,
 }
 

go/analysis/passes/errorsas/errorsas.go

@@ -25,6 +25,7 @@ of the second argument is not a pointer to a type implementing error.`
 var Analyzer = &analysis.Analyzer{
 	Name:     "errorsas",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/errorsas",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/fieldalignment/fieldalignment.go

@@ -51,6 +51,7 @@ known as "false sharing" that slows down both goroutines.
 var Analyzer = &analysis.Analyzer{
 	Name:     "fieldalignment",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/fieldalignment",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/findcall/findcall.go

@@ -26,6 +26,7 @@ of a particular name.`
 var Analyzer = &analysis.Analyzer{
 	Name:             "findcall",
 	Doc:              Doc,
+	URL:              "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/findcall",
 	Run:              run,
 	RunDespiteErrors: true,
 	FactTypes:        []analysis.Fact{new(foundFact)},

go/analysis/passes/framepointer/framepointer.go

@@ -20,6 +20,7 @@ const Doc = "report assembly that clobbers the frame pointer before saving it"
 var Analyzer = &analysis.Analyzer{
 	Name: "framepointer",
 	Doc:  Doc,
+	URL:  "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/framepointer",
 	Run:  run,
 }
 

go/analysis/passes/httpresponse/httpresponse.go

@@ -35,6 +35,7 @@ diagnostic for such mistakes.`
 var Analyzer = &analysis.Analyzer{
 	Name:     "httpresponse",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/httpresponse",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/ifaceassert/ifaceassert.go

@@ -34,6 +34,7 @@ io.Reader, so this assertion cannot succeed.
 var Analyzer = &analysis.Analyzer{
 	Name:     "ifaceassert",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/ifaceassert",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/inspect/inspect.go

@@ -38,6 +38,7 @@ import (
 var Analyzer = &analysis.Analyzer{
 	Name:             "inspect",
 	Doc:              "optimize AST traversal for later passes",
+	URL:              "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/inspect",
 	Run:              run,
 	RunDespiteErrors: true,
 	ResultType:       reflect.TypeOf(new(inspector.Inspector)),

go/analysis/passes/loopclosure/loopclosure.go

@@ -78,6 +78,7 @@ See: https://golang.org/doc/go_faq.html#closures_and_goroutines`
 var Analyzer = &analysis.Analyzer{
 	Name:     "loopclosure",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/loopclosure",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/lostcancel/lostcancel.go

@@ -28,6 +28,7 @@ until its parent context is cancelled.
 var Analyzer = &analysis.Analyzer{
 	Name: "lostcancel",
 	Doc:  Doc,
+	URL:  "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/lostcancel",
 	Run:  run,
 	Requires: []*analysis.Analyzer{
 		inspect.Analyzer,

go/analysis/passes/nilfunc/nilfunc.go

@@ -24,6 +24,7 @@ A useless comparison is one like f == nil as opposed to f() == nil.`
 var Analyzer = &analysis.Analyzer{
 	Name:     "nilfunc",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/nilfunc",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/nilness/nilness.go

@@ -57,6 +57,7 @@ and:
 var Analyzer = &analysis.Analyzer{
 	Name:     "nilness",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/nilness",
 	Run:      run,
 	Requires: []*analysis.Analyzer{buildssa.Analyzer},
 }

go/analysis/passes/pkgfact/pkgfact.go

@@ -38,6 +38,7 @@ import (
 var Analyzer = &analysis.Analyzer{
 	Name:       "pkgfact",
 	Doc:        "gather name/value pairs from constant declarations",
+	URL:        "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/pkgfact",
 	Run:        run,
 	FactTypes:  []analysis.Fact{new(pairsFact)},
 	ResultType: reflect.TypeOf(map[string]string{}),

go/analysis/passes/printf/printf.go

@@ -35,6 +35,7 @@ func init() {
 var Analyzer = &analysis.Analyzer{
 	Name:       "printf",
 	Doc:        Doc,
+	URL:        "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/printf",
 	Requires:   []*analysis.Analyzer{inspect.Analyzer},
 	Run:        run,
 	ResultType: reflect.TypeOf((*Result)(nil)),

go/analysis/passes/reflectvaluecompare/reflectvaluecompare.go

@@ -39,6 +39,7 @@ Likely what is intended is:
 var Analyzer = &analysis.Analyzer{
 	Name:     "reflectvaluecompare",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/reflectvaluecompare",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/shadow/shadow.go

@@ -46,6 +46,7 @@ For example:
 var Analyzer = &analysis.Analyzer{
 	Name:     "shadow",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/shadow",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/shift/shift.go

@@ -29,6 +29,7 @@ const Doc = "check for shifts that equal or exceed the width of the integer"
 var Analyzer = &analysis.Analyzer{
 	Name:     "shift",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/shift",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/sigchanyzer/sigchanyzer.go

@@ -27,6 +27,7 @@ where c is an unbuffered channel, which can be at risk of missing the signal.`
 var Analyzer = &analysis.Analyzer{
 	Name:     "sigchanyzer",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/sigchanyzer",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/sortslice/analyzer.go

@@ -27,11 +27,13 @@ the interface{} value passed to sort.Slice is actually a slice.`
 var Analyzer = &analysis.Analyzer{
 	Name:     "sortslice",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/sortslice",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }
 
 func run(pass *analysis.Pass) (interface{}, error) {
+	// TODO(adonovan): opt: first check for import "sort".
 	inspect := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
 
 	nodeFilter := []ast.Node{

go/analysis/passes/stdmethods/stdmethods.go

@@ -40,6 +40,7 @@ Checked method names include:
 var Analyzer = &analysis.Analyzer{
 	Name:     "stdmethods",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/stdmethods",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/stringintconv/string.go

@@ -34,6 +34,7 @@ string representation of the value in the desired base.
 var Analyzer = &analysis.Analyzer{
 	Name:     "stringintconv",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/stringintconv",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/structtag/structtag.go

@@ -28,6 +28,7 @@ Also report certain struct tags (json, xml) used with unexported fields.`
 var Analyzer = &analysis.Analyzer{
 	Name:             "structtag",
 	Doc:              Doc,
+	URL:              "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/structtag",
 	Requires:         []*analysis.Analyzer{inspect.Analyzer},
 	RunDespiteErrors: true,
 	Run:              run,

go/analysis/passes/testinggoroutine/testinggoroutine.go

@@ -31,6 +31,7 @@ func TestFoo(t *testing.T) {
 var Analyzer = &analysis.Analyzer{
 	Name:     "testinggoroutine",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/testinggoroutine",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/tests/tests.go

@@ -33,6 +33,7 @@ for the conventions that are enforced for Tests, Benchmarks, and Examples.`
 var Analyzer = &analysis.Analyzer{
 	Name: "tests",
 	Doc:  Doc,
+	URL:  "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/tests",
 	Run:  run,
 }
 

go/analysis/passes/timeformat/timeformat.go

@@ -32,6 +32,7 @@ standards, and so it is more likely that 2006-01-02 (yyyy-mm-dd) was intended.
 var Analyzer = &analysis.Analyzer{
 	Name:     "timeformat",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/timeformat",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/unmarshal/unmarshal.go

@@ -25,6 +25,7 @@ in which the argument type is not a pointer or an interface.`
 var Analyzer = &analysis.Analyzer{
 	Name:     "unmarshal",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/unmarshal",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/unreachable/unreachable.go

@@ -26,6 +26,7 @@ infinite loop, or similar constructs.`
 var Analyzer = &analysis.Analyzer{
 	Name:             "unreachable",
 	Doc:              Doc,
+	URL:              "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/unreachable",
 	Requires:         []*analysis.Analyzer{inspect.Analyzer},
 	RunDespiteErrors: true,
 	Run:              run,

go/analysis/passes/unsafeptr/unsafeptr.go

@@ -28,6 +28,7 @@ invisible to stack copying and to the garbage collector.`
 var Analyzer = &analysis.Analyzer{
 	Name:     "unsafeptr",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/unsafeptr",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/unusedresult/unusedresult.go

@@ -35,6 +35,7 @@ The set of functions may be controlled using flags.`
 var Analyzer = &analysis.Analyzer{
 	Name:     "unusedresult",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/unusedresult",
 	Requires: []*analysis.Analyzer{inspect.Analyzer},
 	Run:      run,
 }

go/analysis/passes/unusedwrite/unusedwrite.go

@@ -45,6 +45,7 @@ Another example is about non-pointer receiver:
 var Analyzer = &analysis.Analyzer{
 	Name:     "unusedwrite",
 	Doc:      Doc,
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/unusedwrite",
 	Requires: []*analysis.Analyzer{buildssa.Analyzer},
 	Run:      run,
 }

go/analysis/passes/usesgenerics/usesgenerics.go

@@ -18,6 +18,7 @@ import (
 var Analyzer = &analysis.Analyzer{
 	Name:       "usesgenerics",
 	Doc:        Doc,
+	URL:        "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/usesgenerics",
 	Requires:   []*analysis.Analyzer{inspect.Analyzer},
 	Run:        run,
 	ResultType: reflect.TypeOf((*Result)(nil)),

gopls/doc/generate.go

@@ -516,6 +516,7 @@ func loadAnalyzers(m map[string]*source.Analyzer) []*source.AnalyzerJSON {
 		json = append(json, &source.AnalyzerJSON{
 			Name:    a.Analyzer.Name,
 			Doc:     a.Analyzer.Doc,
+			URL:     a.Analyzer.URL,
 			Default: a.Enabled,
 		})
 	}

gopls/internal/lsp/cache/analysis.go

@@ -1232,7 +1232,7 @@ func toGobDiagnostic(posToLocation func(start, end token.Pos) (protocol.Location
 		// Severity for analysis diagnostics is dynamic, based on user
 		// configuration per analyzer.
 		// Code and CodeHref are unset for Analysis diagnostics,
-		// TODO(rfindley): set Code fields if/when golang/go#57906 is accepted.
+		// TODO(rfindley): derive Code fields from diag.URL.
 		Source:         diag.Category,
 		Message:        diag.Message,
 		SuggestedFixes: fixes,