gopls/doc/generate: treat LinksInHover as an enum

This CL defines a type for the true|false|"gopls" type used
by linksInHover, and adds a special case to the doc+api generator
to treat it as an enum, so that VS Code will present a better
value-chooser UI for it.

Also, document the type grammar used in the docs.

Updates golang/go#68057

Change-Id: I9e334fbc94dcbdc70657d8e64f67fb807e69cbf8
Reviewed-on: https://go-review.googlesource.com/c/tools/+/593656
Reviewed-by: Robert Findley <rfindley@google.com>
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Alan Donovan <adonovan@google.com>

gopls/doc/generate/generate.go

@@ -12,7 +12,7 @@
 //
 // Run it with this command:
 //
-//	$ cd gopls/doc && go generate
+//	$ cd gopls/internal/doc && go generate
 package main
 
 import (
@@ -323,7 +323,7 @@ func loadOptions(category reflect.Value, optsType types.Object, pkg *packages.Pa
 
 // loadEnums returns a description of gopls' settings enum types based on static analysis.
 func loadEnums(pkg *packages.Package) (map[types.Type][]doc.EnumValue, error) {
-	enums := map[types.Type][]doc.EnumValue{}
+	enums := make(map[types.Type][]doc.EnumValue)
 	for _, name := range pkg.Types.Scope().Names() {
 		obj := pkg.Types.Scope().Lookup(name)
 		cnst, ok := obj.(*types.Const)
@@ -344,6 +344,15 @@ func loadEnums(pkg *packages.Package) (map[types.Type][]doc.EnumValue, error) {
 		}
 		enums[obj.Type()] = append(enums[obj.Type()], v)
 	}
+
+	// linksInHover is a one-off edge case (true | false | "gopls")
+	// that doesn't warrant a general solution (e.g. struct tag).
+	enums[pkg.Types.Scope().Lookup("LinksInHoverEnum").Type()] = []doc.EnumValue{
+		{Value: "false", Doc: "false: do not show links"},
+		{Value: "true", Doc: "true: show links to the `linkTarget` domain"},
+		{Value: `"gopls"`, Doc: "`\"gopls\"`: show links to gopls' internal documentation viewer"},
+	}
+
 	return enums, nil
 }
 
@@ -693,14 +702,6 @@ func rewriteSettings(prevContent []byte, api *doc.API) ([]byte, error) {
 
 				// heading
 				//
-				// TODO(adonovan): We should display not the Go type (e.g.
-				// `time.Duration`, `map[Enum]bool`) for each setting,
-				// but its JSON type, since that's the actual interface.
-				// We need a better way to derive accurate JSON type descriptions
-				// from Go types. eg. "a string parsed as if by
-				// `time.Duration.Parse`". (`time.Duration` is an integer, not
-				// a string!)
-				//
 				// We do not display the undocumented dotted-path alias
 				// (h.title + "." + opt.Name) used by VS Code only.
 				fmt.Fprintf(&buf, "### `%s` *%v*\n\n", opt.Name, opt.Type)

gopls/doc/settings.md

@@ -439,15 +439,15 @@ documentation links in hover.
 Default: `"pkg.go.dev"`.
 
 <a id='linksInHover'></a>
-### `linksInHover` *any*
+### `linksInHover` *enum*
 
-linksInHover controls the presence of documentation links
-in hover markdown.
+linksInHover controls the presence of documentation links in hover markdown.
 
-Its legal values are:
-- `false`, for no links;
-- `true`, for links to the `linkTarget` domain; or
-- `"gopls"`, for links to gopls' internal documentation viewer.
+Must be one of:
+
+* false: do not show links
+* true: show links to the `linkTarget` domain
+* `"gopls"`: show links to gopls' internal documentation viewer
 
 Default: `true`.
 

gopls/internal/doc/api.go

@@ -29,7 +29,7 @@ type API struct {
 
 type Option struct {
 	Name       string
-	Type       string
+	Type       string // T = bool | string | int | enum | any | []T | map[T]T | time.Duration
 	Doc        string
 	EnumKeys   EnumKeys
 	EnumValues []EnumValue

gopls/internal/doc/api.json

@@ -154,13 +154,26 @@
 			},
 			{
 				"Name": "linksInHover",
-				"Type": "any",
-				"Doc": "linksInHover controls the presence of documentation links\nin hover markdown.\n\nIts legal values are:\n- `false`, for no links;\n- `true`, for links to the `linkTarget` domain; or\n- `\"gopls\"`, for links to gopls' internal documentation viewer.\n",
+				"Type": "enum",
+				"Doc": "linksInHover controls the presence of documentation links in hover markdown.\n",
 				"EnumKeys": {
 					"ValueType": "",
 					"Keys": null
 				},
-				"EnumValues": null,
+				"EnumValues": [
+					{
+						"Value": "false",
+						"Doc": "false: do not show links"
+					},
+					{
+						"Value": "true",
+						"Doc": "true: show links to the `linkTarget` domain"
+					},
+					{
+						"Value": "\"gopls\"",
+						"Doc": "`\"gopls\"`: show links to gopls' internal documentation viewer"
+					}
+				],
 				"Default": "true",
 				"Status": "",
 				"Hierarchy": "ui.documentation"

gopls/internal/settings/settings.go

@@ -355,16 +355,20 @@ type DocumentationOptions struct {
 	// documentation links in hover.
 	LinkTarget string
 
-	// LinksInHover controls the presence of documentation links
-	// in hover markdown.
-	//
-	// Its legal values are:
-	// - `false`, for no links;
-	// - `true`, for links to the `linkTarget` domain; or
-	// - `"gopls"`, for links to gopls' internal documentation viewer.
-	LinksInHover any
+	// LinksInHover controls the presence of documentation links in hover markdown.
+	LinksInHover LinksInHoverEnum
 }
 
+// LinksInHoverEnum has legal values:
+//
+// - `false`, for no links;
+// - `true`, for links to the `linkTarget` domain; or
+// - `"gopls"`, for links to gopls' internal documentation viewer.
+//
+// Note: this type has special logic in loadEnums in generate.go.
+// Be sure to reflect enum and doc changes there!
+type LinksInHoverEnum any
+
 // Note: FormattingOptions must be comparable with reflect.DeepEqual.
 type FormattingOptions struct {
 	// Local is the equivalent of the `goimports -local` flag, which puts