[gopls-release-branch.0.18] gopls: tweak release notes Also, move gofix command into a package so that it can be "go run" from the release branch. Change-Id: I0a75c1ec4b00d22eef6c13c5162dd02ed9ef272f Reviewed-on: https://go-review.googlesource.com/c/tools/+/649318 Auto-Submit: Alan Donovan <adonovan@google.com> Reviewed-by: Jonathan Amsterdam <jba@google.com> LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com> (cherry picked from commit c0dbb60e4ba78287d76e623a94ae61616ff3c74c) Reviewed-on: https://go-review.googlesource.com/c/tools/+/650642 Reviewed-by: Robert Findley <rfindley@google.com>
diff --git a/gopls/doc/analyzers.md b/gopls/doc/analyzers.md index 68465f9..dde9559 100644 --- a/gopls/doc/analyzers.md +++ b/gopls/doc/analyzers.md
@@ -500,6 +500,15 @@ - replacing Split in "for range strings.Split(...)" by go1.24's more efficient SplitSeq; +To apply all modernization fixes en masse, you can use the +following command: + + $ go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -test ./... + +If the tool warns of conflicting fixes, you may need to run it more +than once until it has applied all fixes cleanly. This command is +not an officially supported interface and may change in the future. + Default: on. Package documentation: [modernize](https://pkg.go.dev/golang.org/x/tools/gopls/internal/analysis/modernize) @@ -962,12 +971,29 @@ that of any method of an interface type declared within the same package. -The tool may report a false positive for a declaration of an -unexported function that is referenced from another package using -the go:linkname mechanism, if the declaration's doc comment does -not also have a go:linkname comment. (Such code is in any case -strongly discouraged: linkname annotations, if they must be used at -all, should be used on both the declaration and the alias.) +The tool may report false positives in some situations, for +example: + + - For a declaration of an unexported function that is referenced + from another package using the go:linkname mechanism, if the + declaration's doc comment does not also have a go:linkname + comment. + + (Such code is in any case strongly discouraged: linkname + annotations, if they must be used at all, should be used on both + the declaration and the alias.) + + - For compiler intrinsics in the "runtime" package that, though + never referenced, are known to the compiler and are called + indirectly by compiled object code. + + - For functions called only from assembly. + + - For functions called only from files whose build tags are not + selected in the current build configuration. + +See https://github.com/golang/go/issues/71686 for discussion of +these limitations. The unusedfunc algorithm is not as precise as the golang.org/x/tools/cmd/deadcode tool, but it has the advantage that
diff --git a/gopls/doc/release/v0.18.0.md b/gopls/doc/release/v0.18.0.md index 8d641a2..ba2c018 100644 --- a/gopls/doc/release/v0.18.0.md +++ b/gopls/doc/release/v0.18.0.md
@@ -37,16 +37,22 @@ variables escape to the heap, and which array accesses require bounds checks. +TODO: add links to the complete manual for each item. + ## New `modernize` analyzer Gopls now reports when code could be simplified or clarified by using more modern features of Go, and provides a quick fix to apply the change. -Examples: +For example, a conditional assignment using an if/else statement may +be replaced by a call to the `min` or `max` built-in functions added +in Go 1.18. -- replacement of conditional assignment using an if/else statement by - a call to the `min` or `max` built-in functions added in Go 1.18; +Use this command to apply modernization fixes en masse: +``` +$ go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -test ./... +``` ## New `unusedfunc` analyzer @@ -97,6 +103,12 @@ ``` gopls will suggest replacing `Ptr` in your code with `Pointer`. +Use this command to apply such fixes en masse: + +``` +$ go run golang.org/x/tools/gopls/internal/analysis/gofix/cmd/gofix@latest -test ./... +``` + ## "Implementations" supports generics At long last, the "Go to Implementations" feature now fully supports
diff --git a/gopls/internal/analysis/gofix/main.go b/gopls/internal/analysis/gofix/cmd/gofix/main.go similarity index 83% rename from gopls/internal/analysis/gofix/main.go rename to gopls/internal/analysis/gofix/cmd/gofix/main.go index fde633f..d75978f 100644 --- a/gopls/internal/analysis/gofix/main.go +++ b/gopls/internal/analysis/gofix/cmd/gofix/main.go
@@ -1,10 +1,7 @@ -// Copyright 2023 The Go Authors. All rights reserved. +// Copyright 2025 The Go Authors. All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. -//go:build ignore -// +build ignore - // The inline command applies the inliner to the specified packages of // Go source code. Run with: //
diff --git a/gopls/internal/analysis/gofix/doc.go b/gopls/internal/analysis/gofix/doc.go index a0c6a08..ad8b067 100644 --- a/gopls/internal/analysis/gofix/doc.go +++ b/gopls/internal/analysis/gofix/doc.go
@@ -77,5 +77,9 @@ ) The proposal https://go.dev/issue/32816 introduces the "//go:fix" directives. + +You can use this (officially unsupported) command to apply gofix fixes en masse: + + $ go run golang.org/x/tools/gopls/internal/analysis/gofix/cmd/gofix@latest -test ./... */ package gofix
diff --git a/gopls/internal/analysis/modernize/doc.go b/gopls/internal/analysis/modernize/doc.go index 15aeab6..3759fdb 100644 --- a/gopls/internal/analysis/modernize/doc.go +++ b/gopls/internal/analysis/modernize/doc.go
@@ -32,4 +32,13 @@ // for i := range n {}, added in go1.22; // - replacing Split in "for range strings.Split(...)" by go1.24's // more efficient SplitSeq; +// +// To apply all modernization fixes en masse, you can use the +// following command: +// +// $ go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -test ./... +// +// If the tool warns of conflicting fixes, you may need to run it more +// than once until it has applied all fixes cleanly. This command is +// not an officially supported interface and may change in the future. package modernize
diff --git a/gopls/internal/analysis/unusedfunc/doc.go b/gopls/internal/analysis/unusedfunc/doc.go index 5946ed8..9e2fc81 100644 --- a/gopls/internal/analysis/unusedfunc/doc.go +++ b/gopls/internal/analysis/unusedfunc/doc.go
@@ -20,12 +20,29 @@ // that of any method of an interface type declared within the same // package. // -// The tool may report a false positive for a declaration of an -// unexported function that is referenced from another package using -// the go:linkname mechanism, if the declaration's doc comment does -// not also have a go:linkname comment. (Such code is in any case -// strongly discouraged: linkname annotations, if they must be used at -// all, should be used on both the declaration and the alias.) +// The tool may report false positives in some situations, for +// example: +// +// - For a declaration of an unexported function that is referenced +// from another package using the go:linkname mechanism, if the +// declaration's doc comment does not also have a go:linkname +// comment. +// +// (Such code is in any case strongly discouraged: linkname +// annotations, if they must be used at all, should be used on both +// the declaration and the alias.) +// +// - For compiler intrinsics in the "runtime" package that, though +// never referenced, are known to the compiler and are called +// indirectly by compiled object code. +// +// - For functions called only from assembly. +// +// - For functions called only from files whose build tags are not +// selected in the current build configuration. +// +// See https://github.com/golang/go/issues/71686 for discussion of +// these limitations. // // The unusedfunc algorithm is not as precise as the // golang.org/x/tools/cmd/deadcode tool, but it has the advantage that
diff --git a/gopls/internal/doc/api.json b/gopls/internal/doc/api.json index 8f10107..629e45f 100644 --- a/gopls/internal/doc/api.json +++ b/gopls/internal/doc/api.json
@@ -510,7 +510,7 @@ }, { "Name": "\"modernize\"", - "Doc": "simplify code by using modern constructs\n\nThis analyzer reports opportunities for simplifying and clarifying\nexisting code by using more modern features of Go, such as:\n\n - replacing an if/else conditional assignment by a call to the\n built-in min or max functions added in go1.21;\n - replacing sort.Slice(x, func(i, j int) bool) { return s[i] \u003c s[j] }\n by a call to slices.Sort(s), added in go1.21;\n - replacing interface{} by the 'any' type added in go1.18;\n - replacing append([]T(nil), s...) by slices.Clone(s) or\n slices.Concat(s), added in go1.21;\n - replacing a loop around an m[k]=v map update by a call\n to one of the Collect, Copy, Clone, or Insert functions\n from the maps package, added in go1.21;\n - replacing []byte(fmt.Sprintf...) by fmt.Appendf(nil, ...),\n added in go1.19;\n - replacing uses of context.WithCancel in tests with t.Context, added in\n go1.24;\n - replacing omitempty by omitzero on structs, added in go1.24;\n - replacing append(s[:i], s[i+1]...) by slices.Delete(s, i, i+1),\n added in go1.21\n - replacing a 3-clause for i := 0; i \u003c n; i++ {} loop by\n for i := range n {}, added in go1.22;\n - replacing Split in \"for range strings.Split(...)\" by go1.24's\n more efficient SplitSeq;", + "Doc": "simplify code by using modern constructs\n\nThis analyzer reports opportunities for simplifying and clarifying\nexisting code by using more modern features of Go, such as:\n\n - replacing an if/else conditional assignment by a call to the\n built-in min or max functions added in go1.21;\n - replacing sort.Slice(x, func(i, j int) bool) { return s[i] \u003c s[j] }\n by a call to slices.Sort(s), added in go1.21;\n - replacing interface{} by the 'any' type added in go1.18;\n - replacing append([]T(nil), s...) by slices.Clone(s) or\n slices.Concat(s), added in go1.21;\n - replacing a loop around an m[k]=v map update by a call\n to one of the Collect, Copy, Clone, or Insert functions\n from the maps package, added in go1.21;\n - replacing []byte(fmt.Sprintf...) by fmt.Appendf(nil, ...),\n added in go1.19;\n - replacing uses of context.WithCancel in tests with t.Context, added in\n go1.24;\n - replacing omitempty by omitzero on structs, added in go1.24;\n - replacing append(s[:i], s[i+1]...) by slices.Delete(s, i, i+1),\n added in go1.21\n - replacing a 3-clause for i := 0; i \u003c n; i++ {} loop by\n for i := range n {}, added in go1.22;\n - replacing Split in \"for range strings.Split(...)\" by go1.24's\n more efficient SplitSeq;\n\nTo apply all modernization fixes en masse, you can use the\nfollowing command:\n\n\t$ go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -test ./...\n\nIf the tool warns of conflicting fixes, you may need to run it more\nthan once until it has applied all fixes cleanly. This command is\nnot an officially supported interface and may change in the future.", "Default": "true" }, { @@ -630,7 +630,7 @@ }, { "Name": "\"unusedfunc\"", - "Doc": "check for unused functions and methods\n\nThe unusedfunc analyzer reports functions and methods that are\nnever referenced outside of their own declaration.\n\nA function is considered unused if it is unexported and not\nreferenced (except within its own declaration).\n\nA method is considered unused if it is unexported, not referenced\n(except within its own declaration), and its name does not match\nthat of any method of an interface type declared within the same\npackage.\n\nThe tool may report a false positive for a declaration of an\nunexported function that is referenced from another package using\nthe go:linkname mechanism, if the declaration's doc comment does\nnot also have a go:linkname comment. (Such code is in any case\nstrongly discouraged: linkname annotations, if they must be used at\nall, should be used on both the declaration and the alias.)\n\nThe unusedfunc algorithm is not as precise as the\ngolang.org/x/tools/cmd/deadcode tool, but it has the advantage that\nit runs within the modular analysis framework, enabling near\nreal-time feedback within gopls.", + "Doc": "check for unused functions and methods\n\nThe unusedfunc analyzer reports functions and methods that are\nnever referenced outside of their own declaration.\n\nA function is considered unused if it is unexported and not\nreferenced (except within its own declaration).\n\nA method is considered unused if it is unexported, not referenced\n(except within its own declaration), and its name does not match\nthat of any method of an interface type declared within the same\npackage.\n\nThe tool may report false positives in some situations, for\nexample:\n\n - For a declaration of an unexported function that is referenced\n from another package using the go:linkname mechanism, if the\n declaration's doc comment does not also have a go:linkname\n comment.\n\n (Such code is in any case strongly discouraged: linkname\n annotations, if they must be used at all, should be used on both\n the declaration and the alias.)\n\n - For compiler intrinsics in the \"runtime\" package that, though\n never referenced, are known to the compiler and are called\n indirectly by compiled object code.\n\n - For functions called only from assembly.\n\n - For functions called only from files whose build tags are not\n selected in the current build configuration.\n\nSee https://github.com/golang/go/issues/71686 for discussion of\nthese limitations.\n\nThe unusedfunc algorithm is not as precise as the\ngolang.org/x/tools/cmd/deadcode tool, but it has the advantage that\nit runs within the modular analysis framework, enabling near\nreal-time feedback within gopls.", "Default": "true" }, { @@ -1189,7 +1189,7 @@ }, { "Name": "modernize", - "Doc": "simplify code by using modern constructs\n\nThis analyzer reports opportunities for simplifying and clarifying\nexisting code by using more modern features of Go, such as:\n\n - replacing an if/else conditional assignment by a call to the\n built-in min or max functions added in go1.21;\n - replacing sort.Slice(x, func(i, j int) bool) { return s[i] \u003c s[j] }\n by a call to slices.Sort(s), added in go1.21;\n - replacing interface{} by the 'any' type added in go1.18;\n - replacing append([]T(nil), s...) by slices.Clone(s) or\n slices.Concat(s), added in go1.21;\n - replacing a loop around an m[k]=v map update by a call\n to one of the Collect, Copy, Clone, or Insert functions\n from the maps package, added in go1.21;\n - replacing []byte(fmt.Sprintf...) by fmt.Appendf(nil, ...),\n added in go1.19;\n - replacing uses of context.WithCancel in tests with t.Context, added in\n go1.24;\n - replacing omitempty by omitzero on structs, added in go1.24;\n - replacing append(s[:i], s[i+1]...) by slices.Delete(s, i, i+1),\n added in go1.21\n - replacing a 3-clause for i := 0; i \u003c n; i++ {} loop by\n for i := range n {}, added in go1.22;\n - replacing Split in \"for range strings.Split(...)\" by go1.24's\n more efficient SplitSeq;", + "Doc": "simplify code by using modern constructs\n\nThis analyzer reports opportunities for simplifying and clarifying\nexisting code by using more modern features of Go, such as:\n\n - replacing an if/else conditional assignment by a call to the\n built-in min or max functions added in go1.21;\n - replacing sort.Slice(x, func(i, j int) bool) { return s[i] \u003c s[j] }\n by a call to slices.Sort(s), added in go1.21;\n - replacing interface{} by the 'any' type added in go1.18;\n - replacing append([]T(nil), s...) by slices.Clone(s) or\n slices.Concat(s), added in go1.21;\n - replacing a loop around an m[k]=v map update by a call\n to one of the Collect, Copy, Clone, or Insert functions\n from the maps package, added in go1.21;\n - replacing []byte(fmt.Sprintf...) by fmt.Appendf(nil, ...),\n added in go1.19;\n - replacing uses of context.WithCancel in tests with t.Context, added in\n go1.24;\n - replacing omitempty by omitzero on structs, added in go1.24;\n - replacing append(s[:i], s[i+1]...) by slices.Delete(s, i, i+1),\n added in go1.21\n - replacing a 3-clause for i := 0; i \u003c n; i++ {} loop by\n for i := range n {}, added in go1.22;\n - replacing Split in \"for range strings.Split(...)\" by go1.24's\n more efficient SplitSeq;\n\nTo apply all modernization fixes en masse, you can use the\nfollowing command:\n\n\t$ go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -test ./...\n\nIf the tool warns of conflicting fixes, you may need to run it more\nthan once until it has applied all fixes cleanly. This command is\nnot an officially supported interface and may change in the future.", "URL": "https://pkg.go.dev/golang.org/x/tools/gopls/internal/analysis/modernize", "Default": true }, @@ -1333,7 +1333,7 @@ }, { "Name": "unusedfunc", - "Doc": "check for unused functions and methods\n\nThe unusedfunc analyzer reports functions and methods that are\nnever referenced outside of their own declaration.\n\nA function is considered unused if it is unexported and not\nreferenced (except within its own declaration).\n\nA method is considered unused if it is unexported, not referenced\n(except within its own declaration), and its name does not match\nthat of any method of an interface type declared within the same\npackage.\n\nThe tool may report a false positive for a declaration of an\nunexported function that is referenced from another package using\nthe go:linkname mechanism, if the declaration's doc comment does\nnot also have a go:linkname comment. (Such code is in any case\nstrongly discouraged: linkname annotations, if they must be used at\nall, should be used on both the declaration and the alias.)\n\nThe unusedfunc algorithm is not as precise as the\ngolang.org/x/tools/cmd/deadcode tool, but it has the advantage that\nit runs within the modular analysis framework, enabling near\nreal-time feedback within gopls.", + "Doc": "check for unused functions and methods\n\nThe unusedfunc analyzer reports functions and methods that are\nnever referenced outside of their own declaration.\n\nA function is considered unused if it is unexported and not\nreferenced (except within its own declaration).\n\nA method is considered unused if it is unexported, not referenced\n(except within its own declaration), and its name does not match\nthat of any method of an interface type declared within the same\npackage.\n\nThe tool may report false positives in some situations, for\nexample:\n\n - For a declaration of an unexported function that is referenced\n from another package using the go:linkname mechanism, if the\n declaration's doc comment does not also have a go:linkname\n comment.\n\n (Such code is in any case strongly discouraged: linkname\n annotations, if they must be used at all, should be used on both\n the declaration and the alias.)\n\n - For compiler intrinsics in the \"runtime\" package that, though\n never referenced, are known to the compiler and are called\n indirectly by compiled object code.\n\n - For functions called only from assembly.\n\n - For functions called only from files whose build tags are not\n selected in the current build configuration.\n\nSee https://github.com/golang/go/issues/71686 for discussion of\nthese limitations.\n\nThe unusedfunc algorithm is not as precise as the\ngolang.org/x/tools/cmd/deadcode tool, but it has the advantage that\nit runs within the modular analysis framework, enabling near\nreal-time feedback within gopls.", "URL": "https://pkg.go.dev/golang.org/x/tools/gopls/internal/analysis/unusedfunc", "Default": true },