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,
 }