all: gofmt main repo

[This CL is part of a sequence implementing the proposal #51082.
The design doc is at https://go.dev/s/godocfmt-design.]

Run the updated gofmt, which reformats doc comments,
on the main repository. Vendored files are excluded.

For #51082.

Change-Id: I7332f099b60f716295fb34719c98c04eb1a85407
Reviewed-on: https://go-review.googlesource.com/c/go/+/384268
Reviewed-by: Jonathan Amsterdam <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>

misc/cgo/gmp/gmp.go

@@ -333,10 +333,9 @@ func (z *Int) Abs(x *Int) *Int {
 
 // CmpInt compares x and y. The result is
 //
-// -1 if x < y
-// 0 if x == y
-// +1 if x > y
-//
+// -1 if x < y
+// 0 if x == y
+// +1 if x > y
 func CmpInt(x, y *Int) int {
  x.doinit()
  y.doinit()

misc/ios/go_ios_exec.go

@@ -13,9 +13,11 @@
 // binary.
 //
 // This script requires that three environment variables be set:
-// GOIOS_DEV_ID: The codesigning developer id or certificate identifier
-// GOIOS_APP_ID: The provisioning app id prefix. Must support wildcard app ids.
-// GOIOS_TEAM_ID: The team id that owns the app id prefix.
+//
+// GOIOS_DEV_ID: The codesigning developer id or certificate identifier
+// GOIOS_APP_ID: The provisioning app id prefix. Must support wildcard app ids.
+// GOIOS_TEAM_ID: The team id that owns the app id prefix.
+//
 // $GOROOT/misc/ios contains a script, detect.go, that attempts to autodetect these.
 package main
 

src/archive/tar/common.go

@@ -221,9 +221,11 @@ func (s sparseEntry) endOffset() int64 { return s.Offset + s.Length }
 // that the file has no data in it, which is rather odd.
 //
 // As an example, if the underlying raw file contains the 10-byte data:
+//
 // var compactFile = "abcdefgh"
 //
 // And the sparse map has the following entries:
+//
 // var spd sparseDatas = []sparseEntry{
 // {Offset: 2, Length: 5}, // Data fragment for 2..6
 // {Offset: 18, Length: 3}, // Data fragment for 18..20
@@ -235,6 +237,7 @@ func (s sparseEntry) endOffset() int64 { return s.Offset + s.Length }
 // }
 //
 // Then the content of the resulting sparse file with a Header.Size of 25 is:
+//
 // var sparseFile = "\x00"*2 + "abcde" + "\x00"*11 + "fgh" + "\x00"*4
 type (
  sparseDatas []sparseEntry
@@ -293,9 +296,9 @@ func alignSparseEntries(src []sparseEntry, size int64) []sparseEntry {
 // The input must have been already validated.
 //
 // This function mutates src and returns a normalized map where:
-// * adjacent fragments are coalesced together
-// * only the last fragment may be empty
-// * the endOffset of the last fragment is the total size
+// - adjacent fragments are coalesced together
+// - only the last fragment may be empty
+// - the endOffset of the last fragment is the total size
 func invertSparseEntries(src []sparseEntry, size int64) []sparseEntry {
  dst := src[:0]
  var pre sparseEntry

src/archive/tar/reader.go

@@ -336,9 +336,9 @@ func parsePAX(r io.Reader) (map[string]string, error) {
 // header in case further processing is required.
 //
 // The err will be set to io.EOF only when one of the following occurs:
-// * Exactly 0 bytes are read and EOF is hit.
-// * Exactly 1 block of zeros is read and EOF is hit.
-// * At least 2 blocks of zeros are read.
+// - Exactly 0 bytes are read and EOF is hit.
+// - Exactly 1 block of zeros is read and EOF is hit.
+// - At least 2 blocks of zeros are read.
 func (tr *Reader) readHeader() (*Header, *block, error) {
  // Two blocks of zero bytes marks the end of the archive.
  if _, err := io.ReadFull(tr.r, tr.blk[:]); err != nil {

src/archive/tar/strconv.go

@@ -306,6 +306,7 @@ func formatPAXRecord(k, v string) (string, error) {
 
 // validPAXRecord reports whether the key-value pair is valid where each
 // record is formatted as:
+//
 // "%d %s=%s\n" % (size, key, value)
 //
 // Keys and values should be UTF-8, but the number of bad writers out there

src/builtin/builtin.go

@@ -137,9 +137,12 @@ type ComplexType complex64
 // new elements. If it does not, a new underlying array will be allocated.
 // Append returns the updated slice. It is therefore necessary to store the
 // result of append, often in the variable holding the slice itself:
+//
 // slice = append(slice, elem1, elem2)
 // slice = append(slice, anotherSlice...)
+//
 // As a special case, it is legal to append a string to a byte slice, like this:
+//
 // slice = append([]byte("hello "), "world"...)
 func append(slice []Type, elems ...Type) []Type
 
@@ -156,24 +159,28 @@ func copy(dst, src []Type) int
 func delete(m map[Type]Type1, key Type)
 
 // The len built-in function returns the length of v, according to its type:
+//
 // Array: the number of elements in v.
 // Pointer to array: the number of elements in *v (even if v is nil).
 // Slice, or map: the number of elements in v; if v is nil, len(v) is zero.
 // String: the number of bytes in v.
 // Channel: the number of elements queued (unread) in the channel buffer;
 // if v is nil, len(v) is zero.
+//
 // For some arguments, such as a string literal or a simple array expression, the
 // result can be a constant. See the Go language specification's "Length and
 // capacity" section for details.
 func len(v Type) int
 
 // The cap built-in function returns the capacity of v, according to its type:
+//
 // Array: the number of elements in v (same as len(v)).
 // Pointer to array: the number of elements in *v (same as len(v)).
 // Slice: the maximum length the slice can reach when resliced;
 // if v is nil, cap(v) is zero.
 // Channel: the channel buffer capacity, in units of elements;
 // if v is nil, cap(v) is zero.
+//
 // For some arguments, such as a simple array expression, the result can be a
 // constant. See the Go language specification's "Length and capacity" section for
 // details.
@@ -184,6 +191,7 @@ func cap(v Type) int
 // value. Unlike new, make's return type is the same as the type of its
 // argument, not a pointer to it. The specification of the result depends on
 // the type:
+//
 // Slice: The size specifies the length. The capacity of the slice is
 // equal to its length. A second integer argument may be provided to
 // specify a different capacity; it must be no smaller than the
@@ -225,7 +233,9 @@ func imag(c ComplexType) FloatType
 // the last sent value is received. After the last value has been received
 // from a closed channel c, any receive from c will succeed without
 // blocking, returning the zero value for the channel element. The form
+//
 // x, ok := <-c
+//
 // will also set ok to false for a closed channel.
 func close(c chan<- Type)
 

src/bytes/bytes.go

@@ -372,9 +372,10 @@ func genSplit(s, sep []byte, sepSave, n int) [][]byte {
 // the subslices between those separators.
 // If sep is empty, SplitN splits after each UTF-8 sequence.
 // The count determines the number of subslices to return:
-// n > 0: at most n subslices; the last subslice will be the unsplit remainder.
-// n == 0: the result is nil (zero subslices)
-// n < 0: all subslices
+//
+// n > 0: at most n subslices; the last subslice will be the unsplit remainder.
+// n == 0: the result is nil (zero subslices)
+// n < 0: all subslices
 //
 // To split around the first instance of a separator, see Cut.
 func SplitN(s, sep []byte, n int) [][]byte { return genSplit(s, sep, 0, n) }
@@ -383,9 +384,10 @@ func SplitN(s, sep []byte, n int) [][]byte { return genSplit(s, sep, 0, n) }
 // returns a slice of those subslices.
 // If sep is empty, SplitAfterN splits after each UTF-8 sequence.
 // The count determines the number of subslices to return:
-// n > 0: at most n subslices; the last subslice will be the unsplit remainder.
-// n == 0: the result is nil (zero subslices)
-// n < 0: all subslices
+//
+// n > 0: at most n subslices; the last subslice will be the unsplit remainder.
+// n == 0: the result is nil (zero subslices)
+// n < 0: all subslices
 func SplitAfterN(s, sep []byte, n int) [][]byte {
  return genSplit(s, sep, len(sep), n)
 }

src/cmd/addr2line/main.go

@@ -6,6 +6,7 @@
 // just enough to support pprof.
 //
 // Usage:
+//
 // go tool addr2line binary
 //
 // Addr2line reads hexadecimal addresses, one per line and with optional 0x prefix,

src/cmd/asm/doc.go

@@ -3,11 +3,11 @@
 // license that can be found in the LICENSE file.
 
 /*
-Asm, typically invoked as ``go tool asm'', assembles the source file into an object
+Asm, typically invoked as “go tool asm”, assembles the source file into an object
 file named for the basename of the argument source file with a .o suffix. The
 object file can then be combined with other objects into a package archive.
 
-Command Line
+# Command Line
 
 Usage:
 

src/cmd/asm/internal/asm/parse.go

@@ -162,7 +162,7 @@ func (p *Parser) nextToken() lex.ScanToken {
 
 // line consumes a single assembly line from p.lex of the form
 //
-// {label:} WORD[.cond] [ arg {, arg} ] (';' | '\n')
+// {label:} WORD[.cond] [ arg {, arg} ] (';' | '\n')
 //
 // It adds any labels to p.pendingLabels and returns the word, cond,
 // operand list, and true. If there is an error or EOF, it returns
@@ -891,7 +891,7 @@ func (p *Parser) symRefAttrs(name string, issueError bool) (bool, obj.ABI) {
 // constrained form of the operand syntax that's always SB-based,
 // non-static, and has at most a simple integer offset:
 //
-// [$|*]sym[<abi>][+Int](SB)
+// [$|*]sym[<abi>][+Int](SB)
 func (p *Parser) funcAddress() (string, obj.ABI, bool) {
  switch p.peek() {
  case '$', '*':
@@ -1041,9 +1041,13 @@ func (p *Parser) registerIndirect(a *obj.Addr, prefix rune) {
 //
 // For 386/AMD64 register list specifies 4VNNIW-style multi-source operand.
 // For range of 4 elements, Intel manual uses "+3" notation, for example:
+//
 // VP4DPWSSDS zmm1{k1}{z}, zmm2+3, m128
+//
 // Given asm line:
+//
 // VP4DPWSSDS Z5, [Z10-Z13], (AX)
+//
 // zmm2 is Z10, and Z13 is the only valid value for it (Z10+3).
 // Only simple ranges are accepted, like [Z0-Z3].
 //

src/cmd/buildid/doc.go

@@ -6,6 +6,7 @@
 Buildid displays or updates the build ID stored in a Go package or binary.
 
 Usage:
+
  go tool buildid [-w] file
 
 By default, buildid prints the build ID found in the named file.

src/cmd/cgo/doc.go

@@ -3,10 +3,9 @@
 // license that can be found in the LICENSE file.
 
 /*
-
 Cgo enables the creation of Go packages that call C code.
 
-Using cgo with the go command
+# Using cgo with the go command
 
 To use cgo write normal Go code that imports a pseudo-package "C".
 The Go code can then refer to types such as C.size_t, variables such
@@ -91,11 +90,11 @@ file. This allows pre-compiled static libraries to be included in the package
 directory and linked properly.
 For example if package foo is in the directory /go/src/foo:
 
- // #cgo LDFLAGS: -L${SRCDIR}/libs -lfoo
+ // #cgo LDFLAGS: -L${SRCDIR}/libs -lfoo
 
 Will be expanded to:
 
- // #cgo LDFLAGS: -L/go/src/foo/libs -lfoo
+ // #cgo LDFLAGS: -L/go/src/foo/libs -lfoo
 
 When the Go tool sees that one or more Go files use the special import
 "C", it will look for other non-Go files in the directory and compile
@@ -139,7 +138,7 @@ or you can set the CC environment variable any time you run the go tool.
 The CXX_FOR_TARGET, CXX_FOR_${GOOS}_${GOARCH}, and CXX
 environment variables work in a similar way for C++ code.
 
-Go references to C
+# Go references to C
 
 Within the Go file, C's struct field names that are keywords in Go
 can be accessed by prefixing them with an underscore: if x points at a C
@@ -291,7 +290,7 @@ the helper function crashes the program, like when Go itself runs out
 of memory. Because C.malloc cannot fail, it has no two-result form
 that returns errno.
 
-C references to Go
+# C references to Go
 
 Go functions can be exported for use by C code in the following way:
 
@@ -327,7 +326,7 @@ definitions and declarations, then the two output files will produce
 duplicate symbols and the linker will fail. To avoid this, definitions
 must be placed in preambles in other files, or in C source files.
 
-Passing pointers
+# Passing pointers
 
 Go is a garbage collected language, and the garbage collector needs to
 know the location of every pointer to Go memory. Because of this,
@@ -398,7 +397,7 @@ passing uninitialized C memory to Go code if the Go code is going to
 store pointer values in it. Zero out the memory in C before passing it
 to Go.
 
-Special cases
+# Special cases
 
 A few special C types which would normally be represented by a pointer
 type in Go are instead represented by a uintptr. Those include:
@@ -449,9 +448,10 @@ to auto-update code from Go 1.14 and earlier:
 
  go tool fix -r eglconf <pkg>
 
-Using cgo directly
+# Using cgo directly
 
 Usage:
+
  go tool cgo [cgo options] [-- compiler options] gofiles...
 
 Cgo transforms the specified input Go source files into several output

src/cmd/cgo/gcc.go

@@ -114,11 +114,11 @@ func (p *Package) addToFlag(flag string, args []string) {
 //
 // For example, the following string:
 //
-// `a b:"c d" 'e''f' "g\""`
+// `a b:"c d" 'e''f' "g\""`
 //
 // Would be parsed as:
 //
-// []string{"a", "b:c d", "ef", `g"`}
+// []string{"a", "b:c d", "ef", `g"`}
 func splitQuoted(s string) (r []string, err error) {
  var args []string
  arg := make([]rune, len(s))
@@ -1137,13 +1137,19 @@ func (p *Package) mangle(f *File, arg *ast.Expr, addPosition bool) (ast.Expr, bo
 
 // checkIndex checks whether arg has the form &a[i], possibly inside
 // type conversions. If so, then in the general case it writes
-// _cgoIndexNN := a
-// _cgoNN := &cgoIndexNN[i] // with type conversions, if any
+//
+// _cgoIndexNN := a
+// _cgoNN := &cgoIndexNN[i] // with type conversions, if any
+//
 // to sb, and writes
-// _cgoCheckPointer(_cgoNN, _cgoIndexNN)
+//
+// _cgoCheckPointer(_cgoNN, _cgoIndexNN)
+//
 // to sbCheck, and returns true. If a is a simple variable or field reference,
 // it writes
-// _cgoIndexNN := &a
+//
+// _cgoIndexNN := &a
+//
 // and dereferences the uses of _cgoIndexNN. Taking the address avoids
 // making a copy of an array.
 //
@@ -1191,10 +1197,14 @@ func (p *Package) checkIndex(sb, sbCheck *bytes.Buffer, arg ast.Expr, i int) boo
 
 // checkAddr checks whether arg has the form &x, possibly inside type
 // conversions. If so, it writes
-// _cgoBaseNN := &x
-// _cgoNN := _cgoBaseNN // with type conversions, if any
+//
+// _cgoBaseNN := &x
+// _cgoNN := _cgoBaseNN // with type conversions, if any
+//
 // to sb, and writes
-// _cgoCheckPointer(_cgoBaseNN, true)
+//
+// _cgoCheckPointer(_cgoBaseNN, true)
+//
 // to sbCheck, and returns true. This tells _cgoCheckPointer to check
 // just the contents of the pointer being passed, not any other part
 // of the memory allocation. This is run after checkIndex, which looks

src/cmd/compile/internal/amd64/ssa.go

@@ -111,7 +111,9 @@ func moveByType(t *types.Type) obj.As {
 }
 
 // opregreg emits instructions for
-// dest := dest(To) op src(From)
+//
+// dest := dest(To) op src(From)
+//
 // and also returns the created obj.Prog so it
 // may be further adjusted (offset, scale, etc).
 func opregreg(s *ssagen.State, op obj.As, dest, src int16) *obj.Prog {

src/cmd/compile/internal/inline/inl.go

@@ -522,7 +522,8 @@ func InlineCalls(fn *ir.Func) {
 // but then you may as well do it here. so this is cleaner and
 // shorter and less complicated.
 // The result of inlnode MUST be assigned back to n, e.g.
-// n.Left = inlnode(n.Left)
+//
+// n.Left = inlnode(n.Left)
 func inlnode(n ir.Node, maxCost int32, inlMap map[*ir.Func]bool, edit func(ir.Node) ir.Node) ir.Node {
  if n == nil {
  return n
@@ -657,7 +658,8 @@ var NewInline = func(call *ir.CallExpr, fn *ir.Func, inlIndex int) *ir.InlinedCa
 // inlined function body, and (List, Rlist) contain the (input, output)
 // parameters.
 // The result of mkinlcall MUST be assigned back to n, e.g.
-// n.Left = mkinlcall(n.Left, fn, isddd)
+//
+// n.Left = mkinlcall(n.Left, fn, isddd)
 func mkinlcall(n *ir.CallExpr, fn *ir.Func, maxCost int32, inlMap map[*ir.Func]bool, edit func(ir.Node) ir.Node) ir.Node {
  if fn.Inl == nil {
  if logopt.Enabled() {