all: fix various doc comment formatting nits

A run of lines that are indented with any number of spaces or tabs
format as a <pre> block. This commit fixes various doc comments
that format badly according to that (standard) rule.

For example, consider:

	// - List item.
	//   Second line.
	// - Another item.

Because the - lines are unindented, this is actually two paragraphs
separated by a one-line <pre> block. This CL rewrites it to:

	//  - List item.
	//    Second line.
	//  - Another item.

Today, that will format as a single <pre> block.
In a future release, we hope to format it as a bulleted list.

Various other minor fixes as well, all in preparation for reformatting.

For #51082.

Change-Id: I95cf06040d4186830e571cd50148be3bf8daf189
Reviewed-on: https://go-review.googlesource.com/c/go/+/384257
Trust: Russ Cox <rsc@golang.org>
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>

src/cmd/compile/internal/noder/unified.go

@@ -34,9 +34,9 @@ var localPkgReader *pkgReader
 //
 // The pipeline contains 2 steps:
 //
-// (1) Generate package export data "stub".
+//  1) Generate package export data "stub".
 //
-// (2) Generate package IR from package export data.
+//  2) Generate package IR from package export data.
 //
 // The package data "stub" at step (1) contains everything from the local package,
 // but nothing that have been imported. When we're actually writing out export data

src/cmd/compile/internal/reflectdata/reflect.go

@@ -667,10 +667,10 @@ var kinds = []int{
 // tflag is documented in reflect/type.go.
 //
 // tflag values must be kept in sync with copies in:
-//	cmd/compile/internal/reflectdata/reflect.go
+//	- cmd/compile/internal/reflectdata/reflect.go
-//	cmd/link/internal/ld/decodesym.go
+//	- cmd/link/internal/ld/decodesym.go
-//	reflect/type.go
+//	- reflect/type.go
-//	runtime/type.go
+//	- runtime/type.go
 const (
 	tflagUncommon      = 1 << 0
 	tflagExtraStar     = 1 << 1

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

@@ -105,6 +105,7 @@ func (e Edge) String() string {
 	return fmt.Sprintf("{%v,%d}", e.b, e.i)
 }
 
+// BlockKind is the kind of SSA block.
 //     kind          controls        successors
 //   ------------------------------------------
 //     Exit      [return mem]                []

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

@@ -24,10 +24,10 @@ import (
 
 // Compile is the main entry point for this package.
 // Compile modifies f so that on return:
-//   · all Values in f map to 0 or 1 assembly instructions of the target architecture
+//   - all Values in f map to 0 or 1 assembly instructions of the target architecture
-//   · the order of f.Blocks is the order to emit the Blocks
+//   - the order of f.Blocks is the order to emit the Blocks
-//   · the order of b.Values is the order to emit the Values in each Block
+//   - the order of b.Values is the order to emit the Values in each Block
-//   · f has a non-nil regAlloc field
+//   - f has a non-nil regAlloc field
 func Compile(f *Func) {
 	// TODO: debugging - set flags to control verbosity of compiler,
 	// which phases to dump IR before/after, etc.
@@ -250,8 +250,8 @@ var GenssaDump map[string]bool = make(map[string]bool) // names of functions to
 // version is used as a regular expression to match the phase name(s).
 //
 // Special cases that have turned out to be useful:
-//  ssa/check/on enables checking after each phase
+//  - ssa/check/on enables checking after each phase
-//  ssa/all/time enables time reporting for all phases
+//  - ssa/all/time enables time reporting for all phases
 //
 // See gc/lex.go for dissection of the option string.
 // Example uses:

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

@@ -207,8 +207,8 @@ func (t SparseTree) isAncestor(x, y *Block) bool {
 // domorder returns a value for dominator-oriented sorting.
 // Block domination does not provide a total ordering,
 // but domorder two has useful properties.
-// (1) If domorder(x) > domorder(y) then x does not dominate y.
+//  1. If domorder(x) > domorder(y) then x does not dominate y.
-// (2) If domorder(x) < domorder(y) and domorder(y) < domorder(z) and x does not dominate y,
+//  2. If domorder(x) < domorder(y) and domorder(y) < domorder(z) and x does not dominate y,
 //     then x does not dominate z.
 // Property (1) means that blocks sorted by domorder always have a maximal dominant block first.
 // Property (2) allows searches for dominated blocks to exit early.

src/cmd/compile/internal/syntax/parser.go

@@ -1022,6 +1022,8 @@ func (p *parser) operand(keep_parens bool) Expr {
 	// as well (operand is only called from pexpr).
 }
 
+// pexpr parses a PrimaryExpr.
+//
 //	PrimaryExpr =
 //		Operand |
 //		Conversion |
@@ -2519,6 +2521,8 @@ func (p *parser) commClause() *CommClause {
 	return c
 }
 
+// stmtOrNil parses a statement if one is present, or else returns nil.
+//
 //	Statement =
 //		Declaration | LabeledStmt | SimpleStmt |
 //		GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt |

src/cmd/compile/internal/types2/infer.go

@@ -21,9 +21,8 @@ const useConstraintTypeInference = true
 // If successful, infer returns the complete list of type arguments, one for each type parameter.
 // Otherwise the result is nil and appropriate errors will be reported.
 //
-// Inference proceeds as follows:
+// Inference proceeds as follows. Starting with given type arguments:
 //
-//   Starting with given type arguments
 //   1) apply FTI (function type inference) with typed arguments,
 //   2) apply CTI (constraint type inference),
 //   3) apply FTI with untyped function arguments,

src/cmd/compile/internal/types2/object.go

@@ -343,7 +343,7 @@ func NewParam(pos syntax.Pos, pkg *Package, name string, typ Type) *Var {
 
 // NewField returns a new variable representing a struct field.
 // For embedded fields, the name is the unqualified type name
-/// under which the field is accessible.
+// under which the field is accessible.
 func NewField(pos syntax.Pos, pkg *Package, name string, typ Type, embedded bool) *Var {
 	return &Var{object: object{nil, pos, pkg, name, typ, 0, colorFor(typ), nopos}, embedded: embedded, isField: true}
 }

src/cmd/go/script_test.go

@@ -1373,7 +1373,9 @@ type command struct {
 // parse parses a single line as a list of space-separated arguments
 // subject to environment variable expansion (but not resplitting).
 // Single quotes around text disable splitting and expansion.
-// To embed a single quote, double it: 'Don''t communicate by sharing memory.'
+// To embed a single quote, double it:
+//
+//	'Don''t communicate by sharing memory.'
 func (ts *testScript) parse(line string) command {
 	ts.line = line
 

src/cmd/internal/obj/arm64/doc.go

@@ -63,6 +63,7 @@ its address will be aligned to the same or coarser boundary, which is the maximu
 alignment values.
 
 In the following example, the function Add is aligned with 128 bytes.
+
 Examples:
     TEXT ·Add(SB),$40-16
     MOVD $2, R0

src/cmd/internal/obj/ppc64/doc.go

@@ -31,6 +31,7 @@ In the examples below, the Go assembly is on the left, PPC64 assembly on the rig
 for the target operand, which is first in PPC64 asm and last in Go asm.
 
 Example:
+
   ADD R3, R4, R5		<=>	add r5, r4, r3
 
 2. Constant operands
@@ -40,6 +41,7 @@ In the examples below, the Go assembly is on the left, PPC64 assembly on the rig
 immediate value is used with the opcode if possible.
 
 Example:
+
   ADD $1, R3, R4		<=> 	addi r4, r3, 1
 
 3. Opcodes setting condition codes
@@ -52,6 +54,7 @@ In the examples below, the Go assembly is on the left, PPC64 assembly on the rig
 vector instructions.
 
 Example:
+
   ANDCC R3, R4, R5		<=>	and. r5, r3, r4 (set CR0)
 
 4. Loads and stores from memory
@@ -75,6 +78,7 @@ In the examples below, the Go assembly is on the left, PPC64 assembly on the rig
 is updated by the value in the index register.
 
 Examples:
+
   MOVD (R3), R4		<=>	ld r4,0(r3)
   MOVW (R3), R4		<=>	lwa r4,0(r3)
   MOVWZU 4(R3), R4		<=>	lwzu r4,4(r3)
@@ -105,6 +109,7 @@ In the examples below, the Go assembly is on the left, PPC64 assembly on the rig
 bit settings.
 
 Examples:
+
   CMP R3, R4			<=>	cmp r3, r4	(CR0 assumed)
   CMP R3, R4, CR1		<=>	cmp cr1, r3, r4
 

src/cmd/internal/obj/riscv/cpu.go

@@ -276,15 +276,11 @@ const (
 )
 
 // RISC-V mnemonics, as defined in the "opcodes" and "opcodes-pseudo" files
-// from:
+// at https://github.com/riscv/riscv-opcodes.
-//
-//    https://github.com/riscv/riscv-opcodes
 //
 // As well as some pseudo-mnemonics (e.g. MOV) used only in the assembler.
 //
-// See also "The RISC-V Instruction Set Manual" at:
+// See also "The RISC-V Instruction Set Manual" at https://riscv.org/specifications/.
-//
-//    https://riscv.org/specifications/
 //
 // If you modify this table, you MUST run 'go generate' to regenerate anames.go!
 const (

src/cmd/internal/obj/riscv/obj.go

@@ -323,9 +323,7 @@ func setPCs(p *obj.Prog, pc int64) int64 {
 // FixedFrameSize makes other packages aware of the space allocated for RA.
 //
 // A nicer version of this diagram can be found on slide 21 of the presentation
-// attached to:
+// attached to https://golang.org/issue/16922#issuecomment-243748180.
-//
-//   https://golang.org/issue/16922#issuecomment-243748180
 //
 func stackOffset(a *obj.Addr, stacksize int64) {
 	switch a.Name {

src/cmd/link/internal/ld/elf.go

@@ -549,6 +549,7 @@ func elfMipsAbiFlags(sh *ElfShdr, startva uint64, resoff uint64) int {
 	return n
 }
 
+// Layout is given by this C definition:
 //  typedef struct
 //  {
 //    /* Version of flags structure.  */

src/compress/flate/huffman_code.go

@@ -118,18 +118,19 @@ func (h *huffmanEncoder) bitLength(freq []int32) int {
 
 const maxBitsLimit = 16
 
-// Return the number of literals assigned to each bit size in the Huffman encoding
+// bitCounts computes the number of literals assigned to each bit size in the Huffman encoding.
-//
+// It is only called when list.length >= 3.
-// This method is only called when list.length >= 3
 // The cases of 0, 1, and 2 literals are handled by special case code.
 //
-// list  An array of the literals with non-zero frequencies
+// list is an array of the literals with non-zero frequencies
 // and their associated frequencies. The array is in order of increasing
-//             frequency, and has as its last element a special element with frequency
+// frequency and has as its last element a special element with frequency
-//             MaxInt32
+// MaxInt32.
-// maxBits     The maximum number of bits that should be used to encode any literal.
+//
-//             Must be less than 16.
+// maxBits is the maximum number of bits that should be used to encode any literal.
-// return      An integer array in which array[i] indicates the number of literals
+// It must be less than 16.
+//
+// bitCounts retruns an integer slice in which slice[i] indicates the number of literals
 // that should be encoded in i bits.
 func (h *huffmanEncoder) bitCounts(list []literalNode, maxBits int32) []int32 {
 	if maxBits >= maxBitsLimit {
@@ -269,7 +270,7 @@ func (h *huffmanEncoder) assignEncodingAndSize(bitCount []int32, list []literalN
 
 // Update this Huffman Code object to be the minimum code for the specified frequency count.
 //
-// freq  An array of frequencies, in which frequency[i] gives the frequency of literal i.
+// freq is an array of frequencies, in which freq[i] gives the frequency of literal i.
 // maxBits  The maximum number of bits to use for any literal.
 func (h *huffmanEncoder) generate(freq []int32, maxBits int32) {
 	if h.freqcache == nil {

src/crypto/cipher/gcm.go

@@ -13,7 +13,7 @@ import (
 
 // AEAD is a cipher mode providing authenticated encryption with associated
 // data. For a description of the methodology, see
-//	https://en.wikipedia.org/wiki/Authenticated_encryption
+// https://en.wikipedia.org/wiki/Authenticated_encryption.
 type AEAD interface {
 	// NonceSize returns the size of the nonce that must be passed to Seal
 	// and Open.

src/crypto/elliptic/p256.go

@@ -283,6 +283,7 @@ var p256Zero31 = [p256Limbs]uint32{two31m3, two30m2, two31m2, two30p13m2, two31m
 //
 // On entry: in[0,2,...] < 2**30, in[1,3,...] < 2**29 and
 // in2[0,2,...] < 2**30, in2[1,3,...] < 2**29.
+//
 // On exit: out[0,2,...] < 2**30, out[1,3,...] < 2**29.
 func p256Diff(out, in, in2 *[p256Limbs]uint32) {
 	var carry uint32

src/crypto/x509/x509.go

@@ -265,7 +265,6 @@ func (algo PublicKeyAlgorithm) String() string {
 //		iso(1) member-body(2) us(840) ansi-x962(10045)
 //		signatures(4) ecdsa-with-SHA1(1)}
 //
-//
 // RFC 4055 5 PKCS #1 Version 1.5
 //
 //	sha256WithRSAEncryption OBJECT IDENTIFIER ::= { pkcs-1 11 }
@@ -292,11 +291,9 @@ func (algo PublicKeyAlgorithm) String() string {
 //	ecdsa-with-SHA512 OBJECT IDENTIFIER ::= { iso(1) member-body(2)
 //		us(840) ansi-X9-62(10045) signatures(4) ecdsa-with-SHA2(3) 4 }
 //
-//
 // RFC 8410 3 Curve25519 and Curve448 Algorithm Identifiers
 //
 //	id-Ed25519   OBJECT IDENTIFIER ::= { 1 3 101 112 }
-
 var (
 	oidSignatureMD2WithRSA      = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 1, 2}
 	oidSignatureMD5WithRSA      = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 1, 4}

src/debug/gosym/pclntab_test.go

@@ -271,13 +271,12 @@ func TestPCLine(t *testing.T) {
 // read115Executable returns a hello world executable compiled by Go 1.15.
 //
 // The file was compiled in /tmp/hello.go:
-// [BEGIN]
+//
 //	package main
 //
 //	func main() {
 //		println("hello")
 //	}
-// [END]
 func read115Executable(tb testing.TB) []byte {
 	zippedDat, err := os.ReadFile("testdata/pcln115.gz")
 	if err != nil {

src/fmt/doc.go

@@ -115,10 +115,11 @@ with %q, invalid Unicode code points are changed to the Unicode replacement
 character, U+FFFD, as in strconv.QuoteRune.
 
 Other flags:
-	+	always print a sign for numeric values;
+
+	'+'	always print a sign for numeric values;
 		guarantee ASCII-only output for %q (%+q)
-	-	pad with spaces on the right rather than the left (left-justify the field)
+	'-'	pad with spaces on the right rather than the left (left-justify the field)
-	#	alternate format: add leading 0b for binary (%#b), 0 for octal (%#o),
+	'#'	alternate format: add leading 0b for binary (%#b), 0 for octal (%#o),
 		0x or 0X for hex (%#x or %#X); suppress 0x for %p (%#p);
 		for %q, print a raw (backquoted) string if strconv.CanBackquote
 		returns true;
@@ -127,7 +128,7 @@ Other flags:
 		write e.g. U+0078 'x' if the character is printable for %U (%#U).
 	' '	(space) leave a space for elided sign in numbers (% d);
 		put spaces between bytes printing strings or slices in hex (% x, % X)
-	0	pad with leading zeros rather than spaces;
+	'0'	pad with leading zeros rather than spaces;
 		for numbers, this moves the padding after the sign;
 		ignored for strings, byte slices and byte arrays
 

src/go/doc/comment.go

@@ -28,8 +28,11 @@ var (
 	unicodeQuoteReplacer = strings.NewReplacer("``", ulquo, "''", urquo)
 )
 
-// Escape comment text for HTML. If nice is set,
+// Escape comment text for HTML. If nice is set, also replace:
-// also turn `` into “ and '' into ”.
+//
+//	`` -> “
+//	'' -> ”
+//
 func commentEscape(w io.Writer, text string, nice bool) {
 	if nice {
 		// In the first pass, we convert `` and '' into their unicode equivalents.
@@ -93,8 +96,10 @@ var (
 // into a link). Go identifiers that appear in the words map are italicized; if
 // the corresponding map value is not the empty string, it is considered a URL
 // and the word is converted into a link. If nice is set, the remaining text's
-// appearance is improved where it makes sense (e.g., `` is turned into “
+// appearance is improved where it makes sense, such as replacing:
-// and '' into ”).
+//
+//	`` -> “
+//	'' -> ”
 func emphasize(w io.Writer, line string, words map[string]string, nice bool) {
 	for {
 		m := matchRx.FindStringSubmatchIndex(line)

src/go/types/object.go

@@ -297,7 +297,7 @@ func NewParam(pos token.Pos, pkg *Package, name string, typ Type) *Var {
 
 // NewField returns a new variable representing a struct field.
 // For embedded fields, the name is the unqualified type name
-/// under which the field is accessible.
+// under which the field is accessible.
 func NewField(pos token.Pos, pkg *Package, name string, typ Type, embedded bool) *Var {
 	return &Var{object: object{nil, pos, pkg, name, typ, 0, colorFor(typ), token.NoPos}, embedded: embedded, isField: true}
 }

src/math/big/nat.go

@@ -363,6 +363,7 @@ func karatsuba(z, x, y nat) {
 }
 
 // alias reports whether x and y share the same base array.
+//
 // Note: alias assumes that the capacity of underlying arrays
 // is never changed for nat values; i.e. that there are
 // no 3-operand slice expressions in this code (or worse,

src/net/smtp/smtp_test.go

@@ -1104,6 +1104,7 @@ func sendMail(hostPort string) error {
 }
 
 // localhostCert is a PEM-encoded TLS cert generated from src/crypto/tls:
+//
 //	go run generate_cert.go --rsa-bits 1024 --host 127.0.0.1,::1,example.com \
 //		--ca --start-date "Jan 1 00:00:00 1970" --duration=1000000h
 var localhostCert = []byte(`

src/os/file_windows.go

@@ -401,7 +401,7 @@ func openSymlink(path string) (syscall.Handle, error) {
 // normaliseLinkPath converts absolute paths returned by
 // DeviceIoControl(h, FSCTL_GET_REPARSE_POINT, ...)
 // into paths acceptable by all Windows APIs.
-// For example, it coverts
+// For example, it converts
 //  \??\C:\foo\bar into C:\foo\bar
 //  \??\UNC\foo\bar into \\foo\bar
 //  \??\Volume{abc}\ into C:\