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

@@ -11,7 +11,7 @@ Instructions mnemonics mapping rules
 1. Most instructions use width suffixes of instruction names to indicate operand width rather than
 using different register names.
 
-  Examples:
+Examples:
     ADC R24, R14, R12          <=>     adc x12, x24
     ADDW R26->24, R21, R15     <=>     add w15, w21, w26, asr #24
     FCMPS F2, F3               <=>     fcmp s3, s2
@@ -20,7 +20,7 @@ using different register names.
 
 2. Go uses .P and .W suffixes to indicate post-increment and pre-increment.
 
-  Examples:
+Examples:
     MOVD.P -8(R10), R8         <=>      ldr x8, [x10],#-8
     MOVB.W 16(R16), R10        <=>      ldrsb x10, [x16,#16]!
     MOVBU.W 16(R16), R10       <=>      ldrb x10, [x16,#16]!
@@ -39,7 +39,7 @@ ldrsh, sturh, strh =>  MOVH.
 5. Go adds a V prefix for most floating-point and SIMD instructions, except cryptographic extension
 instructions and floating-point(scalar) instructions.
 
-  Examples:
+Examples:
     VADD V5.H8, V18.H8, V9.H8         <=>      add v9.8h, v18.8h, v5.8h
     VLD1.P (R6)(R11), [V31.D1]        <=>      ld1 {v31.1d}, [x6], x11
     VFMLA V29.S2, V20.S2, V14.S2      <=>      fmla v14.2s, v20.2s, v29.2s
@@ -52,7 +52,7 @@ Go asm supports the PCALIGN directive, which indicates that the next instruction
 to a specified boundary by padding with NOOP instruction. The alignment value supported on arm64
 must be a power of 2 and in the range of [8, 2048].
 
-  Examples:
+Examples:
     PCALIGN $16
     MOVD $2, R0          // This instruction is aligned with 16 bytes.
     PCALIGN $1024
@@ -63,7 +63,8 @@ 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:
+
+Examples:
     TEXT ·Add(SB),$40-16
     MOVD $2, R0
     PCALIGN $32
@@ -79,7 +80,7 @@ have the same alignment as the first hand-written instruction.
 
 In the following example, PCALIGN at the entry of the function Add will align its address to 2048 bytes.
 
-  Examples:
+Examples:
     TEXT ·Add(SB),NOSPLIT|NOFRAME,$0
       PCALIGN $2048
       MOVD $1, R0
@@ -91,7 +92,7 @@ In the following example, PCALIGN at the entry of the function Add will align it
 Go asm uses VMOVQ/VMOVD/VMOVS to move 128-bit, 64-bit and 32-bit constants into vector registers, respectively.
 And for a 128-bit interger, it take two 64-bit operands, for the low and high parts separately.
 
-  Examples:
+Examples:
     VMOVS $0x11223344, V0
     VMOVD $0x1122334455667788, V1
     VMOVQ $0x1122334455667788, $0x99aabbccddeeff00, V2   // V2=0x99aabbccddeeff001122334455667788
@@ -104,7 +105,7 @@ is the 16-bit unsigned immediate, in the range 0 to 65535; For the 32-bit varian
 
 The current Go assembler does not accept zero shifts, such as "op $0, Rd" and "op $(0<<(16|32|48)), Rd" instructions.
 
-  Examples:
+Examples:
     MOVK $(10<<32), R20     <=>      movk x20, #10, lsl #32
     MOVZW $(20<<16), R8     <=>      movz w8, #20, lsl #16
     MOVK $(0<<16), R10 will be reported as an error by the assembler.
@@ -121,7 +122,7 @@ Special Cases.
 related to real ARM64 instruction. NOOP serves for the hardware nop instruction. NOOP is an alias of
 HINT $0.
 
-  Examples:
+Examples:
     VMOV V13.B[1], R20      <=>      mov x20, v13.b[1]
     VMOV V13.H[1], R20      <=>      mov w20, v13.h[1]
     JMP (R3)                <=>      br x3
@@ -146,7 +147,7 @@ Argument mapping rules
 
 Go reverses the arguments of most instructions.
 
-    Examples:
+Examples:
       ADD R11.SXTB<<1, RSP, R25      <=>      add x25, sp, w11, sxtb #1
       VADD V16, V19, V14             <=>      add d14, d19, d16
 
@@ -155,32 +156,32 @@ Special Cases.
 (1) Argument order is the same as in the GNU ARM64 syntax: cbz, cbnz and some store instructions,
 such as str, stur, strb, sturb, strh, sturh stlr, stlrb. stlrh, st1.
 
-  Examples:
+Examples:
     MOVD R29, 384(R19)    <=>    str x29, [x19,#384]
     MOVB.P R30, 30(R4)    <=>    strb w30, [x4],#30
     STLRH R21, (R19)      <=>    stlrh w21, [x19]
 
 (2) MADD, MADDW, MSUB, MSUBW, SMADDL, SMSUBL, UMADDL, UMSUBL <Rm>, <Ra>, <Rn>, <Rd>
 
-  Examples:
+Examples:
     MADD R2, R30, R22, R6       <=>    madd x6, x22, x2, x30
     SMSUBL R10, R3, R17, R27    <=>    smsubl x27, w17, w10, x3
 
 (3) FMADDD, FMADDS, FMSUBD, FMSUBS, FNMADDD, FNMADDS, FNMSUBD, FNMSUBS <Fm>, <Fa>, <Fn>, <Fd>
 
-  Examples:
+Examples:
     FMADDD F30, F20, F3, F29    <=>    fmadd d29, d3, d30, d20
     FNMSUBS F7, F25, F7, F22    <=>    fnmsub s22, s7, s7, s25
 
 (4) BFI, BFXIL, SBFIZ, SBFX, UBFIZ, UBFX $<lsb>, <Rn>, $<width>, <Rd>
 
-  Examples:
+Examples:
     BFIW $16, R20, $6, R0      <=>    bfi w0, w20, #16, #6
     UBFIZ $34, R26, $5, R20    <=>    ubfiz x20, x26, #34, #5
 
 (5) FCCMPD, FCCMPS, FCCMPED, FCCMPES <cond>, Fm. Fn, $<nzcv>
 
-  Examples:
+Examples:
     FCCMPD AL, F8, F26, $0     <=>    fccmp d26, d8, #0x0, al
     FCCMPS VS, F29, F4, $4     <=>    fccmp s4, s29, #0x4, vs
     FCCMPED LE, F20, F5, $13   <=>    fccmpe d5, d20, #0xd, le
@@ -188,20 +189,20 @@ such as str, stur, strb, sturb, strh, sturh stlr, stlrb. stlrh, st1.
 
 (6) CCMN, CCMNW, CCMP, CCMPW <cond>, <Rn>, $<imm>, $<nzcv>
 
-  Examples:
+Examples:
     CCMP MI, R22, $12, $13     <=>    ccmp x22, #0xc, #0xd, mi
     CCMNW AL, R1, $11, $8      <=>    ccmn w1, #0xb, #0x8, al
 
 (7) CCMN, CCMNW, CCMP, CCMPW <cond>, <Rn>, <Rm>, $<nzcv>
 
-  Examples:
+Examples:
     CCMN VS, R13, R22, $10     <=>    ccmn x13, x22, #0xa, vs
     CCMPW HS, R19, R14, $11    <=>    ccmp w19, w14, #0xb, cs
 
 (9) CSEL, CSELW, CSNEG, CSNEGW, CSINC, CSINCW <cond>, <Rn>, <Rm>, <Rd> ;
 FCSELD, FCSELS <cond>, <Fn>, <Fm>, <Fd>
 
-  Examples:
+Examples:
     CSEL GT, R0, R19, R1        <=>    csel x1, x0, x19, gt
     CSNEGW GT, R7, R17, R8      <=>    csneg w8, w7, w17, gt
     FCSELD EQ, F15, F18, F16    <=>    fcsel d16, d15, d18, eq
@@ -211,13 +212,13 @@ FCSELD, FCSELS <cond>, <Fn>, <Fm>, <Fd>
 
 (11) STLXR, STLXRW, STXR, STXRW, STLXRB, STLXRH, STXRB, STXRH  <Rf>, (<Rn|RSP>), <Rs>
 
-  Examples:
+Examples:
     STLXR ZR, (R15), R16    <=>    stlxr w16, xzr, [x15]
     STXRB R9, (R21), R19    <=>    stxrb w19, w9, [x21]
 
 (12) STLXP, STLXPW, STXP, STXPW (<Rf1>, <Rf2>), (<Rn|RSP>), <Rs>
 
-  Examples:
+Examples:
     STLXP (R17, R19), (R4), R5      <=>    stlxp w5, x17, x19, [x4]
     STXPW (R30, R25), (R22), R13    <=>    stxp w13, w30, w25, [x22]
 
@@ -227,28 +228,28 @@ FCSELD, FCSELS <cond>, <Fn>, <Fm>, <Fd>
 
 Optionally-shifted immediate.
 
-  Examples:
+Examples:
     ADD $(3151<<12), R14, R20     <=>    add x20, x14, #0xc4f, lsl #12
     ADDW $1864, R25, R6           <=>    add w6, w25, #0x748
 
 Optionally-shifted registers are written as <Rm>{<shift><amount>}.
 The <shift> can be <<(lsl), >>(lsr), ->(asr), @>(ror).
 
-  Examples:
+Examples:
     ADD R19>>30, R10, R24     <=>    add x24, x10, x19, lsr #30
     ADDW R26->24, R21, R15    <=>    add w15, w21, w26, asr #24
 
 Extended registers are written as <Rm>{.<extend>{<<<amount>}}.
 <extend> can be UXTB, UXTH, UXTW, UXTX, SXTB, SXTH, SXTW or SXTX.
 
-  Examples:
+Examples:
     ADDS R19.UXTB<<4, R9, R26     <=>    adds x26, x9, w19, uxtb #4
     ADDSW R14.SXTX, R14, R6       <=>    adds w6, w14, w14, sxtx
 
 Memory references: [<Xn|SP>{,#0}] is written as (Rn|RSP), a base register and an immediate
 offset is written as imm(Rn|RSP), a base register and an offset register is written as (Rn|RSP)(Rm).
 
-  Examples:
+Examples:
     LDAR (R22), R9                  <=>    ldar x9, [x22]
     LDP 28(R17), (R15, R23)         <=>    ldp x15, x23, [x17,#28]
     MOVWU (R4)(R12<<2), R8          <=>    ldr w8, [x4, x12, lsl #2]
@@ -257,12 +258,12 @@ offset is written as imm(Rn|RSP), a base register and an offset register is writ
 
 Register pairs are written as (Rt1, Rt2).
 
-  Examples:
+Examples:
     LDP.P -240(R11), (R12, R26)    <=>    ldp x12, x26, [x11],#-240
 
 Register with arrangement and register with arrangement and index.
 
-  Examples:
+Examples:
     VADD V5.H8, V18.H8, V9.H8                     <=>    add v9.8h, v18.8h, v5.8h
     VLD1 (R2), [V21.B16]                          <=>    ld1 {v21.16b}, [x2]
     VST1.P V9.S[1], (R16)(R21)                    <=>    st1 {v9.s}[1], [x16], x28

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

@@ -23,58 +23,62 @@ In the examples below, the Go assembly is on the left, PPC64 assembly on the rig
 
 1. Operand ordering
 
-  In Go asm, the last operand (right) is the target operand, but with PPC64 asm,
+In Go asm, the last operand (right) is the target operand, but with PPC64 asm,
-  the first operand (left) is the target. The order of the remaining operands is
+the first operand (left) is the target. The order of the remaining operands is
-  not consistent: in general opcodes with 3 operands that perform math or logical
+not consistent: in general opcodes with 3 operands that perform math or logical
-  operations have their operands in reverse order. Opcodes for vector instructions
+operations have their operands in reverse order. Opcodes for vector instructions
-  and those with more than 3 operands usually have operands in the same order except
+and those with more than 3 operands usually have operands in the same order except
-  for the target operand, which is first in PPC64 asm and last in Go asm.
+for the target operand, which is first in PPC64 asm and last in Go asm.
+
+Example:
 
-  Example:
   ADD R3, R4, R5		<=>	add r5, r4, r3
 
 2. Constant operands
 
-  In Go asm, an operand that starts with '$' indicates a constant value. If the
+In Go asm, an operand that starts with '$' indicates a constant value. If the
-  instruction using the constant has an immediate version of the opcode, then an
+instruction using the constant has an immediate version of the opcode, then an
-  immediate value is used with the opcode if possible.
+immediate value is used with the opcode if possible.
+
+Example:
 
-  Example:
   ADD $1, R3, R4		<=> 	addi r4, r3, 1
 
 3. Opcodes setting condition codes
 
-  In PPC64 asm, some instructions other than compares have variations that can set
+In PPC64 asm, some instructions other than compares have variations that can set
-  the condition code where meaningful. This is indicated by adding '.' to the end
+the condition code where meaningful. This is indicated by adding '.' to the end
-  of the PPC64 instruction. In Go asm, these instructions have 'CC' at the end of
+of the PPC64 instruction. In Go asm, these instructions have 'CC' at the end of
-  the opcode. The possible settings of the condition code depend on the instruction.
+the opcode. The possible settings of the condition code depend on the instruction.
-  CR0 is the default for fixed-point instructions; CR1 for floating point; CR6 for
+CR0 is the default for fixed-point instructions; CR1 for floating point; CR6 for
-  vector instructions.
+vector instructions.
+
+Example:
 
-  Example:
   ANDCC R3, R4, R5		<=>	and. r5, r3, r4 (set CR0)
 
 4. Loads and stores from memory
 
-  In Go asm, opcodes starting with 'MOV' indicate a load or store. When the target
+In Go asm, opcodes starting with 'MOV' indicate a load or store. When the target
-  is a memory reference, then it is a store; when the target is a register and the
+is a memory reference, then it is a store; when the target is a register and the
-  source is a memory reference, then it is a load.
+source is a memory reference, then it is a load.
 
-  MOV{B,H,W,D} variations identify the size as byte, halfword, word, doubleword.
+MOV{B,H,W,D} variations identify the size as byte, halfword, word, doubleword.
 
-  Adding 'Z' to the opcode for a load indicates zero extend; if omitted it is sign extend.
+Adding 'Z' to the opcode for a load indicates zero extend; if omitted it is sign extend.
-  Adding 'U' to a load or store indicates an update of the base register with the offset.
+Adding 'U' to a load or store indicates an update of the base register with the offset.
-  Adding 'BR' to an opcode indicates byte-reversed load or store, or the order opposite
+Adding 'BR' to an opcode indicates byte-reversed load or store, or the order opposite
-  of the expected endian order. If 'BR' is used then zero extend is assumed.
+of the expected endian order. If 'BR' is used then zero extend is assumed.
 
-  Memory references n(Ra) indicate the address in Ra + n. When used with an update form
+Memory references n(Ra) indicate the address in Ra + n. When used with an update form
-  of an opcode, the value in Ra is incremented by n.
+of an opcode, the value in Ra is incremented by n.
 
-  Memory references (Ra+Rb) or (Ra)(Rb) indicate the address Ra + Rb, used by indexed
+Memory references (Ra+Rb) or (Ra)(Rb) indicate the address Ra + Rb, used by indexed
-  loads or stores. Both forms are accepted. When used with an update then the base register
+loads or stores. Both forms are accepted. When used with an update then the base register
-  is updated by the value in the index register.
+is updated by the value in the index register.
+
+Examples:
 
-  Examples:
   MOVD (R3), R4		<=>	ld r4,0(r3)
   MOVW (R3), R4		<=>	lwa r4,0(r3)
   MOVWZU 4(R3), R4		<=>	lwzu r4,4(r3)
@@ -92,36 +96,37 @@ In the examples below, the Go assembly is on the left, PPC64 assembly on the rig
 
 4. Compares
 
-  When an instruction does a compare or other operation that might
+When an instruction does a compare or other operation that might
-  result in a condition code, then the resulting condition is set
+result in a condition code, then the resulting condition is set
-  in a field of the condition register. The condition register consists
+in a field of the condition register. The condition register consists
-  of 8 4-bit fields named CR0 - CR7. When a compare instruction
+of 8 4-bit fields named CR0 - CR7. When a compare instruction
-  identifies a CR then the resulting condition is set in that field
+identifies a CR then the resulting condition is set in that field
-  to be read by a later branch or isel instruction. Within these fields,
+to be read by a later branch or isel instruction. Within these fields,
-  bits are set to indicate less than, greater than, or equal conditions.
+bits are set to indicate less than, greater than, or equal conditions.
 
-  Once an instruction sets a condition, then a subsequent branch, isel or
+Once an instruction sets a condition, then a subsequent branch, isel or
-  other instruction can read the condition field and operate based on the
+other instruction can read the condition field and operate based on the
-  bit settings.
+bit settings.
+
+Examples:
 
-  Examples:
   CMP R3, R4			<=>	cmp r3, r4	(CR0 assumed)
   CMP R3, R4, CR1		<=>	cmp cr1, r3, r4
 
-  Note that the condition register is the target operand of compare opcodes, so
+Note that the condition register is the target operand of compare opcodes, so
-  the remaining operands are in the same order for Go asm and PPC64 asm.
+the remaining operands are in the same order for Go asm and PPC64 asm.
-  When CR0 is used then it is implicit and does not need to be specified.
+When CR0 is used then it is implicit and does not need to be specified.
 
 5. Branches
 
-  Many branches are represented as a form of the BC instruction. There are
+Many branches are represented as a form of the BC instruction. There are
-  other extended opcodes to make it easier to see what type of branch is being
+other extended opcodes to make it easier to see what type of branch is being
-  used.
+used.
 
-  The following is a brief description of the BC instruction and its commonly
+The following is a brief description of the BC instruction and its commonly
-  used operands.
+used operands.
 
-  BC op1, op2, op3
+BC op1, op2, op3
 
   op1: type of branch
       16 -> bctr (branch on ctr)
@@ -147,7 +152,7 @@ In the examples below, the Go assembly is on the left, PPC64 assembly on the rig
 
   op3: branch target
 
-  Examples:
+Examples:
 
   BC 12, 0, target		<=>	blt cr0, target
   BC 12, 2, target		<=>	beq cr0, target
@@ -163,39 +168,39 @@ In the examples below, the Go assembly is on the left, PPC64 assembly on the rig
   BLT target			<=>	blt target (cr0 default)
   BGE CR7, target		<=>	bge cr7, target
 
-  Refer to the ISA for more information on additional values for the BC instruction,
+Refer to the ISA for more information on additional values for the BC instruction,
-  how to handle OVG information, and much more.
+how to handle OVG information, and much more.
 
 5. Align directive
 
-  Starting with Go 1.12, Go asm supports the PCALIGN directive, which indicates
+Starting with Go 1.12, Go asm supports the PCALIGN directive, which indicates
-  that the next instruction should be aligned to the specified value. Currently
+that the next instruction should be aligned to the specified value. Currently
-  8 and 16 are the only supported values, and a maximum of 2 NOPs will be added
+8 and 16 are the only supported values, and a maximum of 2 NOPs will be added
-  to align the code. That means in the case where the code is aligned to 4 but
+to align the code. That means in the case where the code is aligned to 4 but
-  PCALIGN $16 is at that location, the code will only be aligned to 8 to avoid
+PCALIGN $16 is at that location, the code will only be aligned to 8 to avoid
-  adding 3 NOPs.
+adding 3 NOPs.
 
-  The purpose of this directive is to improve performance for cases like loops
+The purpose of this directive is to improve performance for cases like loops
-  where better alignment (8 or 16 instead of 4) might be helpful. This directive
+where better alignment (8 or 16 instead of 4) might be helpful. This directive
-  exists in PPC64 assembler and is frequently used by PPC64 assembler writers.
+exists in PPC64 assembler and is frequently used by PPC64 assembler writers.
 
-  PCALIGN $16
+PCALIGN $16
-  PCALIGN $8
+PCALIGN $8
 
-  Functions in Go are aligned to 16 bytes, as is the case in all other compilers
+Functions in Go are aligned to 16 bytes, as is the case in all other compilers
-  for PPC64.
+for PPC64.
 
 6. Shift instructions
 
-  The simple scalar shifts on PPC64 expect a shift count that fits in 5 bits for
+The simple scalar shifts on PPC64 expect a shift count that fits in 5 bits for
-  32-bit values or 6 bit for 64-bit values. If the shift count is a constant value
+32-bit values or 6 bit for 64-bit values. If the shift count is a constant value
-  greater than the max then the assembler sets it to the max for that size (31 for
+greater than the max then the assembler sets it to the max for that size (31 for
-  32 bit values, 63 for 64 bit values). If the shift count is in a register, then
+32 bit values, 63 for 64 bit values). If the shift count is in a register, then
-  only the low 5 or 6 bits of the register will be used as the shift count. The
+only the low 5 or 6 bits of the register will be used as the shift count. The
-  Go compiler will add appropriate code to compare the shift value to achieve the
+Go compiler will add appropriate code to compare the shift value to achieve the
-  the correct result, and the assembler does not add extra checking.
+the correct result, and the assembler does not add extra checking.
 
-  Examples:
+Examples:
 
   SRAD $8,R3,R4		=>	sradi r4,r3,8
   SRD $8,R3,R4		=>	rldicl r4,r3,56,8
@@ -204,17 +209,17 @@ In the examples below, the Go assembly is on the left, PPC64 assembly on the rig
   SRW $40,R4,R5		=>	rlwinm r5,r4,0,0,31
   SLW $12,R4,R5		=>	rlwinm r5,r4,12,0,19
 
-  Some non-simple shifts have operands in the Go assembly which don't map directly
+Some non-simple shifts have operands in the Go assembly which don't map directly
-  onto operands in the PPC64 assembly. When an operand in a shift instruction in the
+onto operands in the PPC64 assembly. When an operand in a shift instruction in the
-  Go assembly is a bit mask, that mask is represented as a start and end bit in the
+Go assembly is a bit mask, that mask is represented as a start and end bit in the
-  PPC64 assembly instead of a mask. See the ISA for more detail on these types of shifts.
+PPC64 assembly instead of a mask. See the ISA for more detail on these types of shifts.
-  Here are a few examples:
+Here are a few examples:
 
   RLWMI $7,R3,$65535,R6 	=>	rlwimi r6,r3,7,16,31
   RLDMI $0,R4,$7,R6 		=>	rldimi r6,r4,0,61
 
-  More recently, Go opcodes were added which map directly onto the PPC64 opcodes. It is
+More recently, Go opcodes were added which map directly onto the PPC64 opcodes. It is
-  recommended to use the newer opcodes to avoid confusion.
+recommended to use the newer opcodes to avoid confusion.
 
   RLDICL $0,R4,$15,R6		=>	rldicl r6,r4,0,15
   RLDICR $0,R4,$15,R6		=>	rldicr r6.r4,0,15
@@ -223,7 +228,7 @@ Register naming
 
 1. Special register usage in Go asm
 
-  The following registers should not be modified by user Go assembler code.
+The following registers should not be modified by user Go assembler code.
 
   R0: Go code expects this register to contain the value 0.
   R1: Stack pointer
@@ -231,7 +236,7 @@ Register naming
   R13: TLS pointer
   R30: g (goroutine)
 
-  Register names:
+Register names:
 
   Rn is used for general purpose registers. (0-31)
   Fn is used for floating point registers. (0-31)

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,8 +549,9 @@ func elfMipsAbiFlags(sh *ElfShdr, startva uint64, resoff uint64) int {
 	return n
 }
 
-//typedef struct
+// Layout is given by this C definition:
-//{
+//  typedef struct
+//  {
 //    /* Version of flags structure.  */
 //    uint16_t version;
 //    /* The level of the ISA: 1-5, 32, 64.  */
@@ -572,7 +573,7 @@ func elfMipsAbiFlags(sh *ElfShdr, startva uint64, resoff uint64) int {
 //    /* Mask of general flags.  */
 //    uint32_t flags1;
 //    uint32_t flags2;
-//} Elf_Internal_ABIFlags_v0;
+//  } Elf_Internal_ABIFlags_v0;
 func elfWriteMipsAbiFlags(ctxt *Link) int {
 	sh := elfshname(".MIPS.abiflags")
 	ctxt.Out.SeekSet(int64(sh.Off))

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:\