gopls/internal/settings: include deprecation message in api-json

- gopls api-json will return deprecation message as additional
property of a configuration.
- go generate ./... will parse the comment of a given field as
doc(entire doc comment) and deprecation message(introduced by
prefix "Deprecated: "). Follow pattern defined in
https://go.dev/wiki/Deprecated.

VSCode-Go side CL 643056.

For golang/vscode-go#3632

Change-Id: Ia6a67948c75dd51b5cb76bbd6d7385b95ea979e4
Reviewed-on: https://go-review.googlesource.com/c/tools/+/642998
Auto-Submit: Hongxiang Jiang <hxjiang@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Findley <rfindley@google.com>

Author: h9jiang

gopls/doc/generate/generate.go

@@ -44,6 +44,7 @@ import (
 	"golang.org/x/tools/gopls/internal/mod"
 	"golang.org/x/tools/gopls/internal/settings"
 	"golang.org/x/tools/gopls/internal/util/safetoken"
+	internalastutil "golang.org/x/tools/internal/astutil"
 )
 
 func main() {
@@ -221,11 +222,13 @@ func loadOptions(category reflect.Value, optsType types.Object, pkg *packages.Pa
 		if len(path) < 2 {
 			return nil, fmt.Errorf("could not find AST node for field %v", typesField)
 		}
+
 		// The AST field gives us the doc.
 		astField, ok := path[1].(*ast.Field)
 		if !ok {
 			return nil, fmt.Errorf("unexpected AST path %v", path)
 		}
+		description, deprecation := astField.Doc.Text(), internalastutil.Deprecation(astField.Doc)
 
 		// The reflect field gives us the default value.
 		reflectField := category.FieldByName(typesField.Name())
@@ -285,14 +288,15 @@ func loadOptions(category reflect.Value, optsType types.Object, pkg *packages.Pa
 		status := reflectStructField.Tag.Get("status")
 
 		opts = append(opts, &doc.Option{
-			Name:       name,
-			Type:       typ,
-			Doc:        lowerFirst(astField.Doc.Text()),
-			Default:    def,
-			EnumKeys:   enumKeys,
-			EnumValues: enums[typesField.Type()],
-			Status:     status,
-			Hierarchy:  hierarchy,
+			Name:               name,
+			Type:               typ,
+			Doc:                lowerFirst(description),
+			Default:            def,
+			EnumKeys:           enumKeys,
+			EnumValues:         enums[typesField.Type()],
+			Status:             status,
+			Hierarchy:          hierarchy,
+			DeprecationMessage: lowerFirst(strings.TrimPrefix(deprecation, "Deprecated: ")),
 		})
 	}
 	return opts, nil

gopls/doc/settings.md

@@ -208,6 +208,9 @@ Default: `false`.
 
 noSemanticString turns off the sending of the semantic token 'string'
 
+Deprecated: Use SemanticTokenTypes["string"] = false instead. See
+golang/vscode-go#3632
+
 Default: `false`.
 
 <a id='noSemanticNumber'></a>
@@ -217,6 +220,9 @@ Default: `false`.
 
 noSemanticNumber turns off the sending of the semantic token 'number'
 
+Deprecated: Use SemanticTokenTypes["number"] = false instead. See
+golang/vscode-go#3632.
+
 Default: `false`.
 
 <a id='semanticTokenTypes'></a>

gopls/internal/analysis/deprecated/deprecated.go

@@ -19,6 +19,7 @@ import (
 	"golang.org/x/tools/go/analysis/passes/inspect"
 	"golang.org/x/tools/go/ast/inspector"
 	"golang.org/x/tools/internal/analysisinternal"
+	internalastutil "golang.org/x/tools/internal/astutil"
 )
 
 //go:embed doc.go
@@ -155,26 +156,8 @@ type deprecatedNames struct {
 // them both as Facts and the return value. This is a simplified copy
 // of staticcheck's fact_deprecated analyzer.
 func collectDeprecatedNames(pass *analysis.Pass, ins *inspector.Inspector) (deprecatedNames, error) {
-	extractDeprecatedMessage := func(docs []*ast.CommentGroup) string {
-		for _, doc := range docs {
-			if doc == nil {
-				continue
-			}
-			parts := strings.Split(doc.Text(), "\n\n")
-			for _, part := range parts {
-				if !strings.HasPrefix(part, "Deprecated: ") {
-					continue
-				}
-				alt := part[len("Deprecated: "):]
-				alt = strings.Replace(alt, "\n", " ", -1)
-				return strings.TrimSpace(alt)
-			}
-		}
-		return ""
-	}
-
 	doDocs := func(names []*ast.Ident, docs *ast.CommentGroup) {
-		alt := extractDeprecatedMessage([]*ast.CommentGroup{docs})
+		alt := strings.TrimPrefix(internalastutil.Deprecation(docs), "Deprecated: ")
 		if alt == "" {
 			return
 		}
@@ -185,19 +168,21 @@ func collectDeprecatedNames(pass *analysis.Pass, ins *inspector.Inspector) (depr
 		}
 	}
 
-	var docs []*ast.CommentGroup
-	for _, f := range pass.Files {
-		docs = append(docs, f.Doc)
-	}
-	if alt := extractDeprecatedMessage(docs); alt != "" {
-		// Don't mark package syscall as deprecated, even though
-		// it is. A lot of people still use it for simple
-		// constants like SIGKILL, and I am not comfortable
-		// telling them to use x/sys for that.
-		if pass.Pkg.Path() != "syscall" {
-			pass.ExportPackageFact(&deprecationFact{alt})
+	// Is package deprecated?
+	//
+	// Don't mark package syscall as deprecated, even though
+	// it is. A lot of people still use it for simple
+	// constants like SIGKILL, and I am not comfortable
+	// telling them to use x/sys for that.
+	if pass.Pkg.Path() != "syscall" {
+		for _, f := range pass.Files {
+			if depr := internalastutil.Deprecation(f.Doc); depr != "" {
+				pass.ExportPackageFact(&deprecationFact{depr})
+				break
+			}
 		}
 	}
+
 	nodeFilter := []ast.Node{
 		(*ast.GenDecl)(nil),
 		(*ast.FuncDecl)(nil),

gopls/internal/doc/api.go

@@ -27,14 +27,15 @@ type API struct {
 }
 
 type Option struct {
-	Name       string
-	Type       string // T = bool | string | int | enum | any | []T | map[T]T | time.Duration
-	Doc        string
-	EnumKeys   EnumKeys
-	EnumValues []EnumValue
-	Default    string
-	Status     string
-	Hierarchy  string
+	Name               string
+	Type               string // T = bool | string | int | enum | any | []T | map[T]T | time.Duration
+	Doc                string
+	EnumKeys           EnumKeys
+	EnumValues         []EnumValue
+	Default            string
+	Status             string
+	Hierarchy          string
+	DeprecationMessage string
 }
 
 type EnumKeys struct {