| commit | cb57b4c286444e6dbb13514e73962503f5afcf04 | [log] [tgz] |
|---|---|---|
| author | Alan Donovan <adonovan@google.com> | Wed Sep 17 12:01:49 2025 -0400 |
| committer | Gopher Robot <gobot@golang.org> | Fri Sep 19 15:09:05 2025 -0700 |
| tree | b2dc8ae09c8181466b14a692a88c71a25bc55c7e | |
| parent | ef565f56dbd203c71349cc46c11fcded860a3a0a [diff] |
gopls/internal/doc/generate: convert Analyzer.Doc to Markdown
The format of Analyzer.Doc fields is not specified, but in
practice all of gopls' analyzers (from x/tools and staticcheck)
use go/doc/comment form. Although this is similar to a subset
of Markdown, strictly it should be passed through the
comment.{Parser,Printer} machinery, for example to quote
Markdown metacharacters (*, [, etc) when they do not have
special meanings in the go/doc/comment subset.
This change adds this step to the doc generator.
A consequence is that ##, when used as a subheading in a
Go doc comment, will be escaped so that it appears literally.
This makes the rendering of analyzers.md consistent with
pkg.go.dev and gopls' internal doc viewer.
Unlike Markdown, Go doc comments have no concept of
subheadings (at least today), yet there are occasions
when a subheading is warranted, such as the docs for
internal/gofix. The meaning of a literal ## is clear enough,
even though it won't render as a heading nor appear in the ToC.
(Staticcheck's SA9004 analyzer also uses subheadings in its
doc string literal, but of the pre-go1.19 legacy variety.
However, internal/gofix cannot use this approach because,
in a doc comment, gofmt will helpfully convert it to a #
heading. Consequently, staticcheck gets to add subheadings
in the ToC, but our own analyzers do not.)
The output was verified in go doc, go doc -http (pkgsite),
and analyzers.md as rendered by go.dev/gopls/analyzers.
We should probably specify the form of Analyzer.Doc comments
more precisely.
Fixes golang/go#75199
Change-Id: I44f3e0fad9cdd5bdc77b34fa23147f4e0dce8a09
Reviewed-on: https://go-review.googlesource.com/c/tools/+/704735
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Auto-Submit: Alan Donovan <adonovan@google.com>
This repository provides the golang.org/x/tools module, comprising various tools and packages mostly for static analysis of Go programs, some of which are listed below. Use the “Go reference” link above for more information about any package.
It also contains the golang.org/x/tools/gopls module, whose root package is a language-server protocol (LSP) server for Go. An LSP server analyses the source code of a project and responds to requests from a wide range of editors such as VSCode and Vim, allowing them to support IDE-like functionality.
Selected commands:
cmd/goimports formats a Go program like go fmt and additionally inserts import statements for any packages required by the file after it is edited.cmd/callgraph prints the call graph of a Go program.cmd/digraph is a utility for manipulating directed graphs in textual notation.cmd/stringer generates declarations (including a String method) for “enum” types.cmd/toolstash is a utility to simplify working with multiple versions of the Go toolchain.These commands may be fetched with a command such as
go install golang.org/x/tools/cmd/goimports@latest
Selected packages:
go/ssa provides a static single-assignment form (SSA) intermediate representation (IR) for Go programs, similar to a typical compiler, for use by analysis tools.
go/packages provides a simple interface for loading, parsing, and type checking a complete Go program from source code.
go/analysis provides a framework for modular static analysis of Go programs.
go/callgraph provides call graphs of Go programs using a variety of algorithms with different trade-offs.
go/ast/inspector provides an optimized means of traversing a Go parse tree for use in analysis tools.
go/cfg provides a simple control-flow graph (CFG) for a Go function.
go/gcexportdata and go/gccgoexportdata read and write the binary files containing type information used by the standard and gccgo compilers.
go/types/objectpath provides a stable naming scheme for named entities (“objects”) in the go/types API.
Numerous other packages provide more esoteric functionality.
This repository uses Gerrit for code changes. To learn how to submit changes, see https://go.dev/doc/contribute.
The git repository is https://go.googlesource.com/tools.
The main issue tracker for the tools repository is located at https://go.dev/issues. Prefix your issue with “x/tools/(your subdir):” in the subject line, so it is easy to find.
This repository uses prettier to format JS and CSS files.
The version of prettier used is 1.18.2.
It is encouraged that all JS and CSS code be run through this before submitting a change. However, it is not a strict requirement enforced by CI.