package analysisutil

import "golang.org/x/tools/go/analysis/passes/internal/analysisutil"

Package analysisutil defines various helper functions used by two or more packages beneath go/analysis.

Index ¶

• func ExtractDoc(content, name string) (string, error)
• func Format(fset *token.FileSet, x ast.Expr) string
• func HasSideEffects(info *types.Info, e ast.Expr) bool
• func Imports(pkg *types.Package, path string) bool
• func IsFunctionNamed(f *types.Func, pkgPath string, names ...string) bool
• func IsNamedType(t types.Type, pkgPath string, names ...string) bool
• func LineStart(f *token.File, line int) token.Pos
• func MustExtractDoc(content, name string) string
• func ReadFile(fset *token.FileSet, filename string) ([]byte, *token.File, error)

Functions ¶

func ExtractDoc ¶

func ExtractDoc(content, name string) (string, error)

ExtractDoc extracts a section of a package doc comment from the provided contents of an analyzer package's doc.go file.

A section is a portion of the comment between one heading and the next, using this form:

# Analyzer NAME

NAME: SUMMARY

Full description...

where NAME matches the name argument, and SUMMARY is a brief verb-phrase that describes the analyzer. The following lines, up until the next heading or the end of the comment, contain the full description. ExtractDoc returns the portion following the colon, which is the form expected by Analyzer.Doc.

Example:

# Analyzer printf

printf: checks consistency of calls to printf

The printf analyzer checks consistency of calls to printf.
Here is the complete description...

This notation allows a single doc comment to provide documentation for multiple analyzers, each in its own section. The HTML anchors generated for each heading are predictable.

It returns an error if the content was not a valid Go source file containing a package doc comment with a heading of the required form.

This machinery enables the package documentation (typically accessible via the web at https://pkg.go.dev/) and the command documentation (typically printed to a terminal) to be derived from the same source and formatted appropriately.

func Format ¶

func Format(fset *token.FileSet, x ast.Expr) string

Format returns a string representation of the expression.

func HasSideEffects ¶

func HasSideEffects(info *types.Info, e ast.Expr) bool

HasSideEffects reports whether evaluation of e has side effects.

func Imports ¶

func Imports(pkg *types.Package, path string) bool

Imports returns true if path is imported by pkg.

func IsFunctionNamed ¶

func IsFunctionNamed(f *types.Func, pkgPath string, names ...string) bool

IsFunctionNamed reports whether f is a top-level function defined in the given package and has one of the given names. It returns false if f is nil or a method.

func IsNamedType ¶

func IsNamedType(t types.Type, pkgPath string, names ...string) bool

IsNamedType reports whether t is the named type with the given package path and one of the given names. This function avoids allocating the concatenation of "pkg.Name", which is important for the performance of syntax matching.

func LineStart ¶

func LineStart(f *token.File, line int) token.Pos

LineStart returns the position of the start of the specified line within file f, or NoPos if there is no line of that number.

func MustExtractDoc ¶

func MustExtractDoc(content, name string) string

MustExtractDoc is like ExtractDoc but it panics on error.

To use, define a doc.go file such as:

// Package halting defines an analyzer of program termination.
//
// # Analyzer halting
//
// halting: reports whether execution will halt.
//
// The halting analyzer reports a diagnostic for functions
// that run forever. To suppress the diagnostics, try inserting
// a 'break' statement into each loop.
package halting

import _ "embed"

//go:embed doc.go
var doc string

And declare your analyzer as:

var Analyzer = &analysis.Analyzer{
	Name:             "halting",
	Doc:              analysisutil.MustExtractDoc(doc, "halting"),
	...
}

func ReadFile ¶

func ReadFile(fset *token.FileSet, filename string) ([]byte, *token.File, error)

ReadFile reads a file and adds it to the FileSet so that we can report errors against it using lineStart.

Source Files ¶

extractdoc.go util.go