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 <[email protected]>
Reviewed-by: Jonathan Amsterdam <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: adonovan

gopls/doc/analyzers.md

@@ -500,6 +500,15 @@ existing code by using more modern features of Go, such as:
   - 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 @@ A method is considered unused if it is unexported, not referenced
 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

gopls/doc/release/v0.18.0.md

@@ -37,16 +37,22 @@ details to be reported as diagnostics. For example, it indicates which
 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 @@ const Ptr = Pointer
 ```
 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

gopls/internal/analysis/gofix/main.go renamed to 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:
 //

gopls/internal/analysis/gofix/doc.go

@@ -77,5 +77,9 @@ or before a group, applying to every constant in the group:
 	)
 
 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

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

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

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