doc.go

     1  // Copyright 2025 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Package inline defines an analyzer that inlines calls to functions
     7  and uses of constants marked with a "//go:fix inline" directive.
     8  
     9  # Analyzer inline
    10  
    11  inline: apply fixes based on 'go:fix inline' comment directives
    12  
    13  The inline analyzer inlines functions and constants that are marked for inlining.
    14  
    15  ## Functions
    16  
    17  Given a function that is marked for inlining, like this one:
    18  
    19  	//go:fix inline
    20  	func Square(x int) int { return Pow(x, 2) }
    21  
    22  this analyzer will recommend that calls to the function elsewhere, in the same
    23  or other packages, should be inlined.
    24  
    25  Inlining can be used to move off of a deprecated function:
    26  
    27  	// Deprecated: prefer Pow(x, 2).
    28  	//go:fix inline
    29  	func Square(x int) int { return Pow(x, 2) }
    30  
    31  It can also be used to move off of an obsolete package,
    32  as when the import path has changed or a higher major version is available:
    33  
    34  	package pkg
    35  
    36  	import pkg2 "pkg/v2"
    37  
    38  	//go:fix inline
    39  	func F() { pkg2.F(nil) }
    40  
    41  Replacing a call pkg.F() by pkg2.F(nil) can have no effect on the program,
    42  so this mechanism provides a low-risk way to update large numbers of calls.
    43  We recommend, where possible, expressing the old API in terms of the new one
    44  to enable automatic migration.
    45  
    46  The inliner takes care to avoid behavior changes, even subtle ones,
    47  such as changes to the order in which argument expressions are
    48  evaluated. When it cannot safely eliminate all parameter variables,
    49  it may introduce a "binding declaration" of the form
    50  
    51  	var params = args
    52  
    53  to evaluate argument expressions in the correct order and bind them to
    54  parameter variables. Since the resulting code transformation may be
    55  stylistically suboptimal, such inlinings may be disabled by specifying
    56  the -inline.allow_binding_decl=false flag to the analyzer driver.
    57  
    58  (In cases where it is not safe to "reduce" a call—that is, to replace
    59  a call f(x) by the body of function f, suitably substituted—the
    60  inliner machinery is capable of replacing f by a function literal,
    61  func(){...}(). However, the inline analyzer discards all such
    62  "literalizations" unconditionally, again on grounds of style.)
    63  
    64  A call to a function F from its dedicated test (TestF) is not inlined,
    65  since the purpose of the test is to exercise F itself, even when
    66  it's a deprecated function to which other calls should be inlined.
    67  This is not true for type aliases; see https://go.dev/issue/79271.
    68  See further discussion in https://go.dev/issue/79272.
    69  
    70  ## Constants
    71  
    72  Given a constant that is marked for inlining, like this one:
    73  
    74  	//go:fix inline
    75  	const Ptr = Pointer
    76  
    77  this analyzer will recommend that uses of Ptr should be replaced with Pointer.
    78  
    79  As with functions, inlining can be used to replace deprecated constants and
    80  constants in obsolete packages.
    81  
    82  A constant definition can be marked for inlining only if it refers to another
    83  named constant.
    84  
    85  The "//go:fix inline" comment must appear before a single const declaration on its own,
    86  as above; before a const declaration that is part of a group, as in this case:
    87  
    88  	const (
    89  	   C = 1
    90  	   //go:fix inline
    91  	   Ptr = Pointer
    92  	)
    93  
    94  or before a group, applying to every constant in the group:
    95  
    96  	//go:fix inline
    97  	const (
    98  		Ptr = Pointer
    99  	    Val = Value
   100  	)
   101  
   102  The proposal https://go.dev/issue/32816 introduces the "//go:fix inline" directives.
   103  
   104  You can use this command to apply inline fixes en masse:
   105  
   106  	$ go run golang.org/x/tools/go/analysis/passes/inline/cmd/inline@latest -fix ./...
   107  
   108  # Analyzer gofixdirective
   109  
   110  gofixdirective: validate uses of //go:fix comment directives
   111  
   112  The gofixdirective analyzer checks "//go:fix inline" directives for correctness.
   113  See the documentation for the gofix analyzer for more about "/go:fix inline".
   114  */
   115  package inline
   116
View as plain text