internal/refactor/inline/analyzer: document
For golang/go#32816.
Change-Id: Ibcde7c94377efb2f07b8bab507a1aab18a410ef9
Reviewed-on: https://go-review.googlesource.com/c/tools/+/646495
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
diff --git a/gopls/doc/analyzers.md b/gopls/doc/analyzers.md
index 2749152..fa88224 100644
--- a/gopls/doc/analyzers.md
+++ b/gopls/doc/analyzers.md
@@ -377,9 +377,11 @@
Package documentation: [infertypeargs](https://pkg.go.dev/golang.org/x/tools/gopls/internal/analysis/infertypeargs)
<a id='inline'></a>
-## `inline`: inline calls to functions with "//go:fix inline" doc comment
+## `inline`: inline functions and forward constants
+The inline analyzer inlines functions that are marked for inlining
+and forwards constants that are marked for forwarding.
Default: on.
diff --git a/gopls/internal/doc/api.json b/gopls/internal/doc/api.json
index 74a6159..9379733 100644
--- a/gopls/internal/doc/api.json
+++ b/gopls/internal/doc/api.json
@@ -495,7 +495,7 @@
},
{
"Name": "\"inline\"",
- "Doc": "inline calls to functions with \"//go:fix inline\" doc comment",
+ "Doc": "inline functions and forward constants\n\nThe inline analyzer inlines functions that are marked for inlining\nand forwards constants that are marked for forwarding.",
"Default": "true"
},
{
@@ -1171,7 +1171,7 @@
},
{
"Name": "inline",
- "Doc": "inline calls to functions with \"//go:fix inline\" doc comment",
+ "Doc": "inline functions and forward constants\n\nThe inline analyzer inlines functions that are marked for inlining\nand forwards constants that are marked for forwarding.",
"URL": "https://pkg.go.dev/golang.org/x/tools/internal/refactor/inline/analyzer",
"Default": true
},
diff --git a/internal/refactor/inline/analyzer/analyzer.go b/internal/refactor/inline/analyzer/analyzer.go
index 9583b2f..5426a6a 100644
--- a/internal/refactor/inline/analyzer/analyzer.go
+++ b/internal/refactor/inline/analyzer/analyzer.go
@@ -11,21 +11,24 @@
"go/types"
"slices"
+ _ "embed"
+
"golang.org/x/tools/go/analysis"
"golang.org/x/tools/go/analysis/passes/inspect"
"golang.org/x/tools/go/ast/inspector"
"golang.org/x/tools/go/types/typeutil"
+ "golang.org/x/tools/internal/analysisinternal"
"golang.org/x/tools/internal/diff"
"golang.org/x/tools/internal/refactor/inline"
"golang.org/x/tools/internal/typesinternal"
)
-// TODO(jba): replace with better doc.
-const Doc = `inline calls to functions with "//go:fix inline" doc comment`
+//go:embed doc.go
+var doc string
var Analyzer = &analysis.Analyzer{
Name: "inline",
- Doc: Doc,
+ Doc: analysisinternal.MustExtractDoc(doc, "inline"),
URL: "https://pkg.go.dev/golang.org/x/tools/internal/refactor/inline/analyzer",
Run: run,
FactTypes: []analysis.Fact{new(goFixInlineFuncFact), new(goFixForwardConstFact)},
diff --git a/internal/refactor/inline/analyzer/doc.go b/internal/refactor/inline/analyzer/doc.go
new file mode 100644
index 0000000..a4ac0f3
--- /dev/null
+++ b/internal/refactor/inline/analyzer/doc.go
@@ -0,0 +1,83 @@
+// 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.
+
+/*
+Package analyzer defines an Analyzer that inlines calls to functions
+marked with a "//go:fix inline" doc comment,
+and forwards uses of constants
+marked with a "//go:fix forward" doc comment.
+
+# Analyzer inline
+
+inline: inline functions and forward constants
+
+The inline analyzer inlines functions that are marked for inlining
+and forwards constants that are marked for forwarding.
+
+# Functions
+
+Given a function that is marked for inlining, like this one:
+
+ //go:fix inline
+ func Square(x int) int { return Pow(x, 2) }
+
+this analyzer will recommend that calls to the function elsewhere, in the same
+or other packages, should be inlined.
+
+Inlining can be used to move off of a deprecated function:
+
+ // Deprecated: prefer Pow(x, 2).
+ //go:fix inline
+ func Square(x int) int { return Pow(x, 2) }
+
+It can also be used to move off of an obsolete package,
+as when the import path has changed or a higher major version is available:
+
+ package pkg
+
+ import pkg2 "pkg/v2"
+
+ //go:fix inline
+ func F() { pkg2.F(nil) }
+
+Replacing a call pkg.F() by pkg2.F(nil) can have no effect on the program,
+so this mechanism provides a low-risk way to update large numbers of calls.
+We recommend, where possible, expressing the old API in terms of the new one
+to enable automatic migration.
+
+# Constants
+
+Given a constant that is marked for forwarding, like this one:
+
+ //go:fix forward
+ const Ptr = Pointer
+
+this analyzer will recommend that uses of Ptr should be replaced with Pointer.
+
+As with inlining, forwarding can be used to replace deprecated constants and
+constants in obsolete packages.
+
+A constant definition can be marked for forwarding only if it refers to another
+named constant.
+
+The "//go:fix forward" comment must appear before a single const declaration on its own,
+as above; before a const declaration that is part of a group, as in this case:
+
+ const (
+ C = 1
+ //go:fix forward
+ Ptr = Pointer
+ )
+
+or before a group, applying to every constant in the group:
+
+ //go:fix forward
+ const (
+ Ptr = Pointer
+ Val = Value
+ )
+
+The proposal https://go.dev/issue/32816 introduces the "//go:fix" directives.
+*/
+package analyzer
