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>

23 files changed, 167 insertions, 163 deletions

diff --git a/src/cmd/compile/internal/abi/abiutils.go b/src/cmd/compile/internal/abi/abiutils.go
index 529150a390..07ece87c41 100644
--- a/src/cmd/compile/internal/abi/abiutils.go
+++ b/src/cmd/compile/internal/abi/abiutils.go
@@ -788,12 +788,12 @@ func (state *assignState) assignParamOrReturn(pt *types.Type, n types.Object, is
 // field. For things that are not structs (or structs without padding)
 // it returns a list of zeros. Example:
 //
-// type small struct {
-//   x uint16
-//   y uint8
-//   z int32
-//   w int32
-// }
+//	type small struct {
+//		x uint16
+//		y uint8
+//		z int32
+//		w int32
+//	}
 //
 // For this struct we would return a list [0, 1, 0, 0], meaning that
 // we have one byte of padding after the second field, and no bytes of
diff --git a/src/cmd/compile/internal/ir/expr.go b/src/cmd/compile/internal/ir/expr.go
index 82132005f9..b5c0983d6a 100644
--- a/src/cmd/compile/internal/ir/expr.go
+++ b/src/cmd/compile/internal/ir/expr.go
@@ -951,11 +951,11 @@ var IsIntrinsicCall = func(*CallExpr) bool { return false }
 // instead of computing both. SameSafeExpr assumes that l and r are
 // used in the same statement or expression. In order for it to be
 // safe to reuse l or r, they must:
-// * be the same expression
-// * not have side-effects (no function calls, no channel ops);
-//   however, panics are ok
-// * not cause inappropriate aliasing; e.g. two string to []byte
-//   conversions, must result in two distinct slices
+//  * be the same expression
+//  * not have side-effects (no function calls, no channel ops);
+//    however, panics are ok
+//  * not cause inappropriate aliasing; e.g. two string to []byte
+//    conversions, must result in two distinct slices
 //
 // The handling of OINDEXMAP is subtle. OINDEXMAP can occur both
 // as an lvalue (map assignment) and an rvalue (map access). This is
diff --git a/src/cmd/compile/internal/noder/unified.go b/src/cmd/compile/internal/noder/unified.go
index ca01c0da95..f45c4a7ea8 100644
--- a/src/cmd/compile/internal/noder/unified.go
+++ b/src/cmd/compile/internal/noder/unified.go
@@ -34,38 +34,38 @@ 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
 // to the output files (see writeNewExport function), we run the "linker", which does
 // a few things:
 //
-// + Updates compiler extensions data (e.g., inlining cost, escape analysis results).
+//  + Updates compiler extensions data (e.g., inlining cost, escape analysis results).
 //
-// + Handles re-exporting any transitive dependencies.
+//  + Handles re-exporting any transitive dependencies.
 //
-// + Prunes out any unnecessary details (e.g., non-inlineable functions, because any
-//   downstream importers only care about inlinable functions).
+//  + Prunes out any unnecessary details (e.g., non-inlineable functions, because any
+//    downstream importers only care about inlinable functions).
 //
 // The source files are typechecked twice, once before writing export data
 // using types2 checker, once after read export data using gc/typecheck.
 // This duplication of work will go away once we always use types2 checker,
 // we can remove the gc/typecheck pass. The reason it is still here:
 //
-// + It reduces engineering costs in maintaining a fork of typecheck
-//   (e.g., no need to backport fixes like CL 327651).
+//  + It reduces engineering costs in maintaining a fork of typecheck
+//    (e.g., no need to backport fixes like CL 327651).
 //
-// + It makes it easier to pass toolstash -cmp.
+//  + It makes it easier to pass toolstash -cmp.
 //
-// + Historically, we would always re-run the typechecker after import, even though
-//   we know the imported data is valid. It's not ideal, but also not causing any
-//   problem either.
+//  + Historically, we would always re-run the typechecker after import, even though
+//    we know the imported data is valid. It's not ideal, but also not causing any
+//    problem either.
 //
-// + There's still transformation that being done during gc/typecheck, like rewriting
-//   multi-valued function call, or transform ir.OINDEX -> ir.OINDEXMAP.
+//  + There's still transformation that being done during gc/typecheck, like rewriting
+//    multi-valued function call, or transform ir.OINDEX -> ir.OINDEXMAP.
 //
 // Using syntax+types2 tree, which already has a complete representation of generics,
 // the unified IR has the full typed AST for doing introspection during step (1).
diff --git a/src/cmd/compile/internal/reflectdata/reflect.go b/src/cmd/compile/internal/reflectdata/reflect.go
index c49444179e..908f81865e 100644
--- a/src/cmd/compile/internal/reflectdata/reflect.go
+++ b/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/link/internal/ld/decodesym.go
-//	reflect/type.go
-//	runtime/type.go
+//	- cmd/compile/internal/reflectdata/reflect.go
+//	- cmd/link/internal/ld/decodesym.go
+//	- reflect/type.go
+//	- runtime/type.go
 const (
 	tflagUncommon      = 1 << 0
 	tflagExtraStar     = 1 << 1
diff --git a/src/cmd/compile/internal/ssa/block.go b/src/cmd/compile/internal/ssa/block.go
index 6ff3188f9b..4d21ade3e3 100644
--- a/src/cmd/compile/internal/ssa/block.go
+++ b/src/cmd/compile/internal/ssa/block.go
@@ -76,10 +76,10 @@ type Block struct {
 //   d.Preds = [?, {b,1}, ?]
 // These indexes allow us to edit the CFG in constant time.
 // In addition, it informs phi ops in degenerate cases like:
-// b:
-//    if k then c else c
-// c:
-//    v = Phi(x, y)
+//  b:
+//     if k then c else c
+//  c:
+//     v = Phi(x, y)
 // Then the indexes tell you whether x is chosen from
 // the if or else branch from b.
 //   b.Succs = [{c,0},{c,1}]
@@ -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]                []
diff --git a/src/cmd/compile/internal/ssa/branchelim.go b/src/cmd/compile/internal/ssa/branchelim.go
index be5f9e0a8b..59773ef31b 100644
--- a/src/cmd/compile/internal/ssa/branchelim.go
+++ b/src/cmd/compile/internal/ssa/branchelim.go
@@ -11,11 +11,11 @@ import "cmd/internal/src"
 //
 // Search for basic blocks that look like
 //
-// bb0            bb0
-//  | \          /   \
-//  | bb1  or  bb1   bb2    <- trivial if/else blocks
-//  | /          \   /
-// bb2            bb3
+//  bb0            bb0
+//   | \          /   \
+//   | bb1  or  bb1   bb2    <- trivial if/else blocks
+//   | /          \   /
+//  bb2            bb3
 //
 // where the intermediate blocks are mostly empty (with no side-effects);
 // rewrite Phis in the postdominator as CondSelects.
diff --git a/src/cmd/compile/internal/ssa/compile.go b/src/cmd/compile/internal/ssa/compile.go
index f87ea5b893..d006bf9a3b 100644
--- a/src/cmd/compile/internal/ssa/compile.go
+++ b/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
-//   · 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
-//   · f has a non-nil regAlloc field
+//   - 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 b.Values is the order to emit the Values in each Block
+//   - 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/all/time enables time reporting for all phases
+//  - ssa/check/on enables checking after each phase
+//  - ssa/all/time enables time reporting for all phases
 //
 // See gc/lex.go for dissection of the option string.
 // Example uses:
diff --git a/src/cmd/compile/internal/ssa/func.go b/src/cmd/compile/internal/ssa/func.go
index 7728a395e0..0b5392f0f0 100644
--- a/src/cmd/compile/internal/ssa/func.go
+++ b/src/cmd/compile/internal/ssa/func.go
@@ -820,12 +820,12 @@ func (f *Func) invalidateCFG() {
 }
 
 // DebugHashMatch reports whether environment variable evname
-// 1) is empty (this is a special more-quickly implemented case of 3)
-// 2) is "y" or "Y"
-// 3) is a suffix of the sha1 hash of name
-// 4) is a suffix of the environment variable
-//    fmt.Sprintf("%s%d", evname, n)
-//    provided that all such variables are nonempty for 0 <= i <= n
+//  1) is empty (this is a special more-quickly implemented case of 3)
+//  2) is "y" or "Y"
+//  3) is a suffix of the sha1 hash of name
+//  4) is a suffix of the environment variable
+//     fmt.Sprintf("%s%d", evname, n)
+//     provided that all such variables are nonempty for 0 <= i <= n
 // Otherwise it returns false.
 // When true is returned the message
 //  "%s triggered %s\n", evname, name
diff --git a/src/cmd/compile/internal/ssa/fuse_branchredirect.go b/src/cmd/compile/internal/ssa/fuse_branchredirect.go
index 751dca7468..27449db55a 100644
--- a/src/cmd/compile/internal/ssa/fuse_branchredirect.go
+++ b/src/cmd/compile/internal/ssa/fuse_branchredirect.go
@@ -8,21 +8,21 @@ package ssa
 // of an If block can be derived from its predecessor If block, in
 // some such cases, we can redirect the predecessor If block to the
 // corresponding successor block directly. For example:
-// p:
-//   v11 = Less64 <bool> v10 v8
-//   If v11 goto b else u
-// b: <- p ...
-//   v17 = Leq64 <bool> v10 v8
-//   If v17 goto s else o
+//  p:
+//    v11 = Less64 <bool> v10 v8
+//    If v11 goto b else u
+//  b: <- p ...
+//    v17 = Leq64 <bool> v10 v8
+//    If v17 goto s else o
 // We can redirect p to s directly.
 //
 // The implementation here borrows the framework of the prove pass.
-// 1, Traverse all blocks of function f to find If blocks.
-// 2,   For any If block b, traverse all its predecessors to find If blocks.
-// 3,     For any If block predecessor p, update relationship p->b.
-// 4,     Traverse all successors of b.
-// 5,       For any successor s of b, try to update relationship b->s, if a
-//          contradiction is found then redirect p to another successor of b.
+//  1, Traverse all blocks of function f to find If blocks.
+//  2,   For any If block b, traverse all its predecessors to find If blocks.
+//  3,     For any If block predecessor p, update relationship p->b.
+//  4,     Traverse all successors of b.
+//  5,       For any successor s of b, try to update relationship b->s, if a
+//           contradiction is found then redirect p to another successor of b.
 func fuseBranchRedirect(f *Func) bool {
 	ft := newFactsTable(f)
 	ft.checkpoint()
diff --git a/src/cmd/compile/internal/ssa/location.go b/src/cmd/compile/internal/ssa/location.go
index b575febd72..d69db404ed 100644
--- a/src/cmd/compile/internal/ssa/location.go
+++ b/src/cmd/compile/internal/ssa/location.go
@@ -46,19 +46,19 @@ func (r *Register) GCNum() int16 {
 // variable that has been decomposed into multiple stack slots.
 // As an example, a string could have the following configurations:
 //
-//           stack layout              LocalSlots
+//            stack layout              LocalSlots
 //
-// Optimizations are disabled. s is on the stack and represented in its entirety.
-// [ ------- s string ---- ] { N: s, Type: string, Off: 0 }
+//  Optimizations are disabled. s is on the stack and represented in its entirety.
+//  [ ------- s string ---- ] { N: s, Type: string, Off: 0 }
 //
-// s was not decomposed, but the SSA operates on its parts individually, so
-// there is a LocalSlot for each of its fields that points into the single stack slot.
-// [ ------- s string ---- ] { N: s, Type: *uint8, Off: 0 }, {N: s, Type: int, Off: 8}
+//  s was not decomposed, but the SSA operates on its parts individually, so
+//  there is a LocalSlot for each of its fields that points into the single stack slot.
+//  [ ------- s string ---- ] { N: s, Type: *uint8, Off: 0 }, {N: s, Type: int, Off: 8}
 //
-// s was decomposed. Each of its fields is in its own stack slot and has its own LocalSLot.
-// [ ptr *uint8 ] [ len int] { N: ptr, Type: *uint8, Off: 0, SplitOf: parent, SplitOffset: 0},
-//                           { N: len, Type: int, Off: 0, SplitOf: parent, SplitOffset: 8}
-//                           parent = &{N: s, Type: string}
+//  s was decomposed. Each of its fields is in its own stack slot and has its own LocalSLot.
+//  [ ptr *uint8 ] [ len int] { N: ptr, Type: *uint8, Off: 0, SplitOf: parent, SplitOffset: 0},
+//                            { N: len, Type: int, Off: 0, SplitOf: parent, SplitOffset: 8}
+//                            parent = &{N: s, Type: string}
 type LocalSlot struct {
 	N    *ir.Name    // an ONAME *ir.Name representing a stack location.
 	Type *types.Type // type of slot
diff --git a/src/cmd/compile/internal/ssa/loopbce.go b/src/cmd/compile/internal/ssa/loopbce.go
index 5a4bc1d60a..206aab2c5e 100644
--- a/src/cmd/compile/internal/ssa/loopbce.go
+++ b/src/cmd/compile/internal/ssa/loopbce.go
@@ -66,18 +66,18 @@ func parseIndVar(ind *Value) (min, inc, nxt *Value) {
 //
 // Look for variables and blocks that satisfy the following
 //
-// loop:
-//   ind = (Phi min nxt),
-//   if ind < max
-//     then goto enter_loop
-//     else goto exit_loop
+//  loop:
+//    ind = (Phi min nxt),
+//    if ind < max
+//      then goto enter_loop
+//      else goto exit_loop
 //
-//   enter_loop:
-//	do something
-//      nxt = inc + ind
-//	goto loop
+//    enter_loop:
+// 	do something
+//       nxt = inc + ind
+// 	goto loop
 //
-// exit_loop:
+//  exit_loop:
 //
 //
 // TODO: handle 32 bit operations
diff --git a/src/cmd/compile/internal/ssa/phiopt.go b/src/cmd/compile/internal/ssa/phiopt.go
index 745c61cb86..0357442ae9 100644
--- a/src/cmd/compile/internal/ssa/phiopt.go
+++ b/src/cmd/compile/internal/ssa/phiopt.go
@@ -15,12 +15,12 @@ package ssa
 //
 // In SSA code this appears as
 //
-// b0
-//   If b -> b1 b2
-// b1
-//   Plain -> b2
-// b2
-//   x = (OpPhi (ConstBool [true]) (ConstBool [false]))
+//  b0
+//    If b -> b1 b2
+//  b1
+//    Plain -> b2
+//  b2
+//    x = (OpPhi (ConstBool [true]) (ConstBool [false]))
 //
 // In this case we can replace x with a copy of b.
 func phiopt(f *Func) {
diff --git a/src/cmd/compile/internal/ssa/prove.go b/src/cmd/compile/internal/ssa/prove.go
index 98af586cab..d0c9a190ad 100644
--- a/src/cmd/compile/internal/ssa/prove.go
+++ b/src/cmd/compile/internal/ssa/prove.go
@@ -27,17 +27,17 @@ const (
 //
 // E.g.
 //
-// r := relation(...)
+//  r := relation(...)
 //
-// if v < w {
-//   newR := r & lt
-// }
-// if v >= w {
-//   newR := r & (eq|gt)
-// }
-// if v != w {
-//   newR := r & (lt|gt)
-// }
+//  if v < w {
+//    newR := r & lt
+//  }
+//  if v >= w {
+//    newR := r & (eq|gt)
+//  }
+//  if v != w {
+//    newR := r & (lt|gt)
+//  }
 type relation uint
 
 const (
diff --git a/src/cmd/compile/internal/ssa/sparsetree.go b/src/cmd/compile/internal/ssa/sparsetree.go
index be914c8644..732bb8e321 100644
--- a/src/cmd/compile/internal/ssa/sparsetree.go
+++ b/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.
-// (2) If domorder(x) < domorder(y) and domorder(y) < domorder(z) and 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,
 //     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.
diff --git a/src/cmd/compile/internal/ssa/writebarrier.go b/src/cmd/compile/internal/ssa/writebarrier.go
index 5120cd1086..21eee12c85 100644
--- a/src/cmd/compile/internal/ssa/writebarrier.go
+++ b/src/cmd/compile/internal/ssa/writebarrier.go
@@ -80,11 +80,11 @@ func needwb(v *Value, zeroes map[ID]ZeroRegion) bool {
 // when necessary (the condition above). It rewrites store ops to branches
 // and runtime calls, like
 //
-// if writeBarrier.enabled {
-//   gcWriteBarrier(ptr, val)	// Not a regular Go call
-// } else {
-//   *ptr = val
-// }
+//	if writeBarrier.enabled {
+//		gcWriteBarrier(ptr, val)	// Not a regular Go call
+//	} else {
+//		*ptr = val
+//	}
 //
 // A sequence of WB stores for many pointer fields of a single type will
 // be emitted together, with a single branch.
diff --git a/src/cmd/compile/internal/syntax/parser.go b/src/cmd/compile/internal/syntax/parser.go
index 39ea0cc224..6574b01371 100644
--- a/src/cmd/compile/internal/syntax/parser.go
+++ b/src/cmd/compile/internal/syntax/parser.go
@@ -1022,22 +1022,24 @@ func (p *parser) operand(keep_parens bool) Expr {
 	// as well (operand is only called from pexpr).
 }
 
-// PrimaryExpr =
-// 	Operand |
-// 	Conversion |
-// 	PrimaryExpr Selector |
-// 	PrimaryExpr Index |
-// 	PrimaryExpr Slice |
-// 	PrimaryExpr TypeAssertion |
-// 	PrimaryExpr Arguments .
+// pexpr parses a PrimaryExpr.
 //
-// Selector       = "." identifier .
-// Index          = "[" Expression "]" .
-// Slice          = "[" ( [ Expression ] ":" [ Expression ] ) |
-//                      ( [ Expression ] ":" Expression ":" Expression )
-//                  "]" .
-// TypeAssertion  = "." "(" Type ")" .
-// Arguments      = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" .
+//	PrimaryExpr =
+//		Operand |
+//		Conversion |
+//		PrimaryExpr Selector |
+//		PrimaryExpr Index |
+//		PrimaryExpr Slice |
+//		PrimaryExpr TypeAssertion |
+//		PrimaryExpr Arguments .
+//
+//	Selector       = "." identifier .
+//	Index          = "[" Expression "]" .
+//	Slice          = "[" ( [ Expression ] ":" [ Expression ] ) |
+//	                     ( [ Expression ] ":" Expression ":" Expression )
+//	                 "]" .
+//	TypeAssertion  = "." "(" Type ")" .
+//	Arguments      = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" .
 func (p *parser) pexpr(x Expr, keep_parens bool) Expr {
 	if trace {
 		defer p.trace("pexpr")()
@@ -1283,10 +1285,10 @@ func newIndirect(pos Pos, typ Expr) Expr {
 // typeOrNil is like type_ but it returns nil if there was no type
 // instead of reporting an error.
 //
-// Type     = TypeName | TypeLit | "(" Type ")" .
-// TypeName = identifier | QualifiedIdent .
-// TypeLit  = ArrayType | StructType | PointerType | FunctionType | InterfaceType |
-// 	      SliceType | MapType | Channel_Type .
+//	Type     = TypeName | TypeLit | "(" Type ")" .
+//	TypeName = identifier | QualifiedIdent .
+//	TypeLit  = ArrayType | StructType | PointerType | FunctionType | InterfaceType |
+//		      SliceType | MapType | Channel_Type .
 func (p *parser) typeOrNil() Expr {
 	if trace {
 		defer p.trace("typeOrNil")()
@@ -2519,11 +2521,13 @@ func (p *parser) commClause() *CommClause {
 	return c
 }
 
-// Statement =
-// 	Declaration | LabeledStmt | SimpleStmt |
-// 	GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt |
-// 	FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt |
-// 	DeferStmt .
+// stmtOrNil parses a statement if one is present, or else returns nil.
+//
+//	Statement =
+//		Declaration | LabeledStmt | SimpleStmt |
+//		GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt |
+//		FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt |
+//		DeferStmt .
 func (p *parser) stmtOrNil() Stmt {
 	if trace {
 		defer p.trace("stmt " + p.tok.String())()
diff --git a/src/cmd/compile/internal/typecheck/subr.go b/src/cmd/compile/internal/typecheck/subr.go
index e9690a5551..d4ec52adf9 100644
--- a/src/cmd/compile/internal/typecheck/subr.go
+++ b/src/cmd/compile/internal/typecheck/subr.go
@@ -1476,14 +1476,14 @@ func getShapes(t *types.Type, listp *[]*types.Type) {
 // For now, we only consider two types to have the same shape, if they have exactly
 // the same underlying type or they are both pointer types.
 //
-//  tparam is the associated typeparam - it must be TTYPEPARAM type. If there is a
-//  structural type for the associated type param (not common), then a pointer type t
-//  is mapped to its underlying type, rather than being merged with other pointers.
+// tparam is the associated typeparam - it must be TTYPEPARAM type. If there is a
+// structural type for the associated type param (not common), then a pointer type t
+// is mapped to its underlying type, rather than being merged with other pointers.
 //
-//  Shape types are also distinguished by the index of the type in a type param/arg
-//  list. We need to do this so we can distinguish and substitute properly for two
-//  type params in the same function that have the same shape for a particular
-//  instantiation.
+// Shape types are also distinguished by the index of the type in a type param/arg
+// list. We need to do this so we can distinguish and substitute properly for two
+// type params in the same function that have the same shape for a particular
+// instantiation.
 func Shapify(t *types.Type, index int, tparam *types.Type) *types.Type {
 	assert(!t.IsShape())
 	if t.HasShape() {
diff --git a/src/cmd/compile/internal/types/size.go b/src/cmd/compile/internal/types/size.go
index fc9907b85f..9fa3e49e34 100644
--- a/src/cmd/compile/internal/types/size.go
+++ b/src/cmd/compile/internal/types/size.go
@@ -17,18 +17,18 @@ var RegSize int
 
 // Slices in the runtime are represented by three components:
 //
-// type slice struct {
-// 	ptr unsafe.Pointer
-// 	len int
-// 	cap int
-// }
+//	type slice struct {
+//		ptr unsafe.Pointer
+//		len int
+//		cap int
+//	}
 //
 // Strings in the runtime are represented by two components:
 //
-// type string struct {
-// 	ptr unsafe.Pointer
-// 	len int
-// }
+//	type string struct {
+//		ptr unsafe.Pointer
+//		len int
+//	}
 //
 // These variables are the offsets of fields and sizes of these structs.
 var (
diff --git a/src/cmd/compile/internal/types/type.go b/src/cmd/compile/internal/types/type.go
index c8d11b5bb9..147194c369 100644
--- a/src/cmd/compile/internal/types/type.go
+++ b/src/cmd/compile/internal/types/type.go
@@ -1121,9 +1121,9 @@ func (t *Type) SimpleString() string {
 }
 
 // Cmp is a comparison between values a and b.
-// -1 if a < b
-//  0 if a == b
-//  1 if a > b
+//  -1 if a < b
+//   0 if a == b
+//   1 if a > b
 type Cmp int8
 
 const (
diff --git a/src/cmd/compile/internal/types2/infer.go b/src/cmd/compile/internal/types2/infer.go
index 78fc35b72a..9f7e593eeb 100644
--- a/src/cmd/compile/internal/types2/infer.go
+++ b/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,
diff --git a/src/cmd/compile/internal/types2/object.go b/src/cmd/compile/internal/types2/object.go
index 08d37cb256..ee7c8a8488 100644
--- a/src/cmd/compile/internal/types2/object.go
+++ b/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}
 }
diff --git a/src/cmd/compile/internal/walk/builtin.go b/src/cmd/compile/internal/walk/builtin.go
index b25627bd22..8fe231161a 100644
--- a/src/cmd/compile/internal/walk/builtin.go
+++ b/src/cmd/compile/internal/walk/builtin.go
@@ -125,12 +125,12 @@ func walkClose(n *ir.UnaryExpr, init *ir.Nodes) ir.Node {
 
 // Lower copy(a, b) to a memmove call or a runtime call.
 //
-// init {
-//   n := len(a)
-//   if n > len(b) { n = len(b) }
-//   if a.ptr != b.ptr { memmove(a.ptr, b.ptr, n*sizeof(elem(a))) }
-// }
-// n;
+//	init {
+//	  n := len(a)
+//	  if n > len(b) { n = len(b) }
+//	  if a.ptr != b.ptr { memmove(a.ptr, b.ptr, n*sizeof(elem(a))) }
+//	}
+//	n;
 //
 // Also works if b is a string.
 //
diff --git a/src/cmd/compile/internal/walk/range.go b/src/cmd/compile/internal/walk/range.go
index aa8c548963..dcf7a786e7 100644
--- a/src/cmd/compile/internal/walk/range.go
+++ b/src/cmd/compile/internal/walk/range.go
@@ -316,9 +316,9 @@ func walkRange(nrange *ir.RangeStmt) ir.Node {
 
 // isMapClear checks if n is of the form:
 //
-// for k := range m {
-//   delete(m, k)
-// }
+//	for k := range m {
+//		delete(m, k)
+//	}
 //
 // where == for keys of map m is reflexive.
 func isMapClear(n *ir.RangeStmt) bool {
@@ -374,9 +374,9 @@ func mapClear(m ir.Node) ir.Node {
 // fast zeroing of slices and arrays (issue 5373).
 // Look for instances of
 //
-// for i := range a {
-// 	a[i] = zero
-// }
+//	for i := range a {
+//		a[i] = zero
+//	}
 //
 // in which the evaluation of a is side-effect-free.
 //