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 <jba@google.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

9 files changed, 136 insertions, 104 deletions

diff --git a/src/encoding/binary/varint.go b/src/encoding/binary/varint.go
index bfb4dd193e..1b07e2541d 100644
--- a/src/encoding/binary/varint.go
+++ b/src/encoding/binary/varint.go
@@ -53,9 +53,9 @@ func PutUvarint(buf []byte, x uint64) int {
 // number of bytes read (> 0). If an error occurred, the value is 0
 // and the number of bytes n is <= 0 meaning:
 //
-// 	n == 0: buf too small
-// 	n  < 0: value larger than 64 bits (overflow)
-// 	        and -n is the number of bytes read
+//	n == 0: buf too small
+//	n  < 0: value larger than 64 bits (overflow)
+//	        and -n is the number of bytes read
 func Uvarint(buf []byte) (uint64, int) {
 	var x uint64
 	var s uint
@@ -91,9 +91,9 @@ func PutVarint(buf []byte, x int64) int {
 // number of bytes read (> 0). If an error occurred, the value is 0
 // and the number of bytes n is <= 0 with the following meaning:
 //
-// 	n == 0: buf too small
-// 	n  < 0: value larger than 64 bits (overflow)
-// 	        and -n is the number of bytes read
+//	n == 0: buf too small
+//	n  < 0: value larger than 64 bits (overflow)
+//	        and -n is the number of bytes read
 func Varint(buf []byte) (int64, int) {
 	ux, n := Uvarint(buf) // ok to continue in presence of error
 	x := int64(ux >> 1)
diff --git a/src/encoding/gob/debug.go b/src/encoding/gob/debug.go
index c989ab1ad6..dc572fc11e 100644
--- a/src/encoding/gob/debug.go
+++ b/src/encoding/gob/debug.go
@@ -215,6 +215,7 @@ func (deb *debugger) uint64() uint64 {
 }
 
 // GobStream:
+//
 //	DelimitedMessage* (until EOF)
 func (deb *debugger) gobStream() {
 	// Make sure we're single-threaded through here.
@@ -226,6 +227,7 @@ func (deb *debugger) gobStream() {
 }
 
 // DelimitedMessage:
+//
 //	uint(lengthOfMessage) Message
 func (deb *debugger) delimitedMessage(indent tab) bool {
 	for {
@@ -261,12 +263,19 @@ func (deb *debugger) loadBlock(eofOK bool) int {
 }
 
 // Message:
+//
 //	TypeSequence TypedValue
+//
 // TypeSequence
+//
 //	(TypeDefinition DelimitedTypeDefinition*)?
+//
 // DelimitedTypeDefinition:
+//
 //	uint(lengthOfTypeDefinition) TypeDefinition
+//
 // TypedValue:
+//
 //	int(typeId) Value
 func (deb *debugger) message(indent tab) bool {
 	for {
@@ -351,6 +360,7 @@ func (deb *debugger) delta(expect int) int {
 }
 
 // TypeDefinition:
+//
 //	[int(-typeId) (already read)] encodingOfWireType
 func (deb *debugger) typeDefinition(indent tab, id typeId) {
 	deb.dump("type definition for id %d", id)
@@ -437,6 +447,7 @@ func (deb *debugger) typeDefinition(indent tab, id typeId) {
 }
 
 // Value:
+//
 //	SingletonValue | StructValue
 func (deb *debugger) value(indent tab, id typeId) {
 	wire, ok := deb.wireType[id]
@@ -448,6 +459,7 @@ func (deb *debugger) value(indent tab, id typeId) {
 }
 
 // SingletonValue:
+//
 //	uint(0) FieldValue
 func (deb *debugger) singletonValue(indent tab, id typeId) {
 	deb.dump("Singleton value")
@@ -465,6 +477,7 @@ func (deb *debugger) singletonValue(indent tab, id typeId) {
 }
 
 // InterfaceValue:
+//
 //	NilInterfaceValue | NonNilInterfaceValue
 func (deb *debugger) interfaceValue(indent tab) {
 	deb.dump("Start of interface value")
@@ -476,6 +489,7 @@ func (deb *debugger) interfaceValue(indent tab) {
 }
 
 // NilInterfaceValue:
+//
 //	uint(0) [already read]
 func (deb *debugger) nilInterfaceValue(indent tab) int {
 	fmt.Fprintf(os.Stderr, "%snil interface\n", indent)
@@ -483,12 +497,19 @@ func (deb *debugger) nilInterfaceValue(indent tab) int {
 }
 
 // NonNilInterfaceValue:
+//
 //	ConcreteTypeName TypeSequence InterfaceContents
+//
 // ConcreteTypeName:
+//
 //	uint(lengthOfName) [already read=n] name
+//
 // InterfaceContents:
+//
 //	int(concreteTypeId) DelimitedValue
+//
 // DelimitedValue:
+//
 //	uint(length) Value
 func (deb *debugger) nonNilInterfaceValue(indent tab, nameLen int) {
 	// ConcreteTypeName
@@ -549,6 +570,7 @@ func (deb *debugger) printWireType(indent tab, wire *wireType) {
 
 // fieldValue prints a value of any type, such as a struct field.
 // FieldValue:
+//
 //	builtinValue | ArrayValue | MapValue | SliceValue | StructValue | InterfaceValue
 func (deb *debugger) fieldValue(indent tab, id typeId) {
 	_, ok := builtinIdToType[id]
@@ -622,6 +644,7 @@ func (deb *debugger) printBuiltin(indent tab, id typeId) {
 }
 
 // ArrayValue:
+//
 //	uint(n) FieldValue*n
 func (deb *debugger) arrayValue(indent tab, wire *wireType) {
 	elemId := wire.ArrayT.Elem
@@ -636,6 +659,7 @@ func (deb *debugger) arrayValue(indent tab, wire *wireType) {
 }
 
 // MapValue:
+//
 //	uint(n) (FieldValue FieldValue)*n  [n (key, value) pairs]
 func (deb *debugger) mapValue(indent tab, wire *wireType) {
 	keyId := wire.MapT.Key
@@ -649,6 +673,7 @@ func (deb *debugger) mapValue(indent tab, wire *wireType) {
 }
 
 // SliceValue:
+//
 //	uint(n) (n FieldValue)
 func (deb *debugger) sliceValue(indent tab, wire *wireType) {
 	elemId := wire.SliceT.Elem
@@ -662,6 +687,7 @@ func (deb *debugger) sliceValue(indent tab, wire *wireType) {
 }
 
 // StructValue:
+//
 //	(uint(fieldDelta) FieldValue)*
 func (deb *debugger) structValue(indent tab, id typeId) {
 	deb.dump("Start of struct value of %q id=%d\n<<\n", id.name(), id)
@@ -692,6 +718,7 @@ func (deb *debugger) structValue(indent tab, id typeId) {
 }
 
 // GobEncoderValue:
+//
 //	uint(n) byte*n
 func (deb *debugger) gobEncoderValue(indent tab, id typeId) {
 	len := deb.uint64()
diff --git a/src/encoding/gob/decoder.go b/src/encoding/gob/decoder.go
index 86f54b4193..9c4257eb3b 100644
--- a/src/encoding/gob/decoder.go
+++ b/src/encoding/gob/decoder.go
@@ -132,7 +132,9 @@ func (dec *Decoder) nextUint() uint64 {
 
 // decodeTypeSequence parses:
 // TypeSequence
+//
 //	(TypeDefinition DelimitedTypeDefinition*)?
+//
 // and returns the type id of the next value. It returns -1 at
 // EOF.  Upon return, the remainder of dec.buf is the value to be
 // decoded. If this is an interface value, it can be ignored by
diff --git a/src/encoding/gob/doc.go b/src/encoding/gob/doc.go
index c765707139..306d395d5b 100644
--- a/src/encoding/gob/doc.go
+++ b/src/encoding/gob/doc.go
@@ -12,7 +12,7 @@ The implementation compiles a custom codec for each data type in the stream and
 is most efficient when a single Encoder is used to transmit a stream of values,
 amortizing the cost of compilation.
 
-Basics
+# Basics
 
 A stream of gobs is self-describing. Each data item in the stream is preceded by
 a specification of its type, expressed in terms of a small set of predefined
@@ -27,7 +27,7 @@ all type information is sent before it is needed. At the receive side, a
 Decoder retrieves values from the encoded stream and unpacks them into local
 variables.
 
-Types and Values
+# Types and Values
 
 The source and destination values/types need not correspond exactly. For structs,
 fields (identified by name) that are in the source but absent from the receiving
@@ -101,7 +101,7 @@ Gob can decode a value of any type implementing the GobDecoder or
 encoding.BinaryUnmarshaler interfaces by calling the corresponding method,
 again in that order of preference.
 
-Encoding Details
+# Encoding Details
 
 This section documents the encoding, details that are not important for most
 users. Details are presented bottom-up.
diff --git a/src/encoding/json/encode.go b/src/encoding/json/encode.go
index fc865386ed..5b67251fbb 100644
--- a/src/encoding/json/encode.go
+++ b/src/encoding/json/encode.go
@@ -77,31 +77,31 @@ import (
 //
 // Examples of struct field tags and their meanings:
 //
-//   // Field appears in JSON as key "myName".
-//   Field int `json:"myName"`
+//	// Field appears in JSON as key "myName".
+//	Field int `json:"myName"`
 //
-//   // Field appears in JSON as key "myName" and
-//   // the field is omitted from the object if its value is empty,
-//   // as defined above.
-//   Field int `json:"myName,omitempty"`
+//	// Field appears in JSON as key "myName" and
+//	// the field is omitted from the object if its value is empty,
+//	// as defined above.
+//	Field int `json:"myName,omitempty"`
 //
-//   // Field appears in JSON as key "Field" (the default), but
-//   // the field is skipped if empty.
-//   // Note the leading comma.
-//   Field int `json:",omitempty"`
+//	// Field appears in JSON as key "Field" (the default), but
+//	// the field is skipped if empty.
+//	// Note the leading comma.
+//	Field int `json:",omitempty"`
 //
-//   // Field is ignored by this package.
-//   Field int `json:"-"`
+//	// Field is ignored by this package.
+//	Field int `json:"-"`
 //
-//   // Field appears in JSON as key "-".
-//   Field int `json:"-,"`
+//	// Field appears in JSON as key "-".
+//	Field int `json:"-,"`
 //
 // The "string" option signals that a field is stored as JSON inside a
 // JSON-encoded string. It applies only to fields of string, floating point,
 // integer, or boolean types. This extra level of encoding is sometimes used
 // when communicating with JavaScript programs:
 //
-//    Int64String int64 `json:",string"`
+//	Int64String int64 `json:",string"`
 //
 // The key name will be used if it's a non-empty string consisting of
 // only Unicode letters, digits, and ASCII punctuation except quotation
diff --git a/src/encoding/json/fold.go b/src/encoding/json/fold.go
index 9e170127db..ab249b2bbe 100644
--- a/src/encoding/json/fold.go
+++ b/src/encoding/json/fold.go
@@ -24,8 +24,9 @@ const (
 // 4) simpleLetterEqualFold, no specials, no non-letters.
 //
 // The letters S and K are special because they map to 3 runes, not just 2:
-//  * S maps to s and to U+017F 'ſ' Latin small letter long s
-//  * k maps to K and to U+212A 'K' Kelvin sign
+//   - S maps to s and to U+017F 'ſ' Latin small letter long s
+//   - k maps to K and to U+212A 'K' Kelvin sign
+//
 // See https://play.golang.org/p/tTxjOc0OGo
 //
 // The returned function is specialized for matching against s and
diff --git a/src/encoding/pem/pem.go b/src/encoding/pem/pem.go
index e7adf88382..146f9d0e1a 100644
--- a/src/encoding/pem/pem.go
+++ b/src/encoding/pem/pem.go
@@ -19,10 +19,12 @@ import (
 // A Block represents a PEM encoded structure.
 //
 // The encoded form is:
-//    -----BEGIN Type-----
-//    Headers
-//    base64-encoded Bytes
-//    -----END Type-----
+//
+//	-----BEGIN Type-----
+//	Headers
+//	base64-encoded Bytes
+//	-----END Type-----
+//
 // where Headers is a possibly empty sequence of Key: Value lines.
 type Block struct {
 	Type    string            // The type, taken from the preamble (i.e. "RSA PRIVATE KEY").
diff --git a/src/encoding/xml/marshal.go b/src/encoding/xml/marshal.go
index 7792ac77f8..01f673a851 100644
--- a/src/encoding/xml/marshal.go
+++ b/src/encoding/xml/marshal.go
@@ -32,39 +32,39 @@ const (
 // elements containing the data.
 //
 // The name for the XML elements is taken from, in order of preference:
-//     - the tag on the XMLName field, if the data is a struct
-//     - the value of the XMLName field of type Name
-//     - the tag of the struct field used to obtain the data
-//     - the name of the struct field used to obtain the data
-//     - the name of the marshaled type
+//   - the tag on the XMLName field, if the data is a struct
+//   - the value of the XMLName field of type Name
+//   - the tag of the struct field used to obtain the data
+//   - the name of the struct field used to obtain the data
+//   - the name of the marshaled type
 //
 // The XML element for a struct contains marshaled elements for each of the
 // exported fields of the struct, with these exceptions:
-//     - the XMLName field, described above, is omitted.
-//     - a field with tag "-" is omitted.
-//     - a field with tag "name,attr" becomes an attribute with
-//       the given name in the XML element.
-//     - a field with tag ",attr" becomes an attribute with the
-//       field name in the XML element.
-//     - a field with tag ",chardata" is written as character data,
-//       not as an XML element.
-//     - a field with tag ",cdata" is written as character data
-//       wrapped in one or more <![CDATA[ ... ]]> tags, not as an XML element.
-//     - a field with tag ",innerxml" is written verbatim, not subject
-//       to the usual marshaling procedure.
-//     - a field with tag ",comment" is written as an XML comment, not
-//       subject to the usual marshaling procedure. It must not contain
-//       the "--" string within it.
-//     - a field with a tag including the "omitempty" option is omitted
-//       if the field value is empty. The empty values are false, 0, any
-//       nil pointer or interface value, and any array, slice, map, or
-//       string of length zero.
-//     - an anonymous struct field is handled as if the fields of its
-//       value were part of the outer struct.
-//     - a field implementing Marshaler is written by calling its MarshalXML
-//       method.
-//     - a field implementing encoding.TextMarshaler is written by encoding the
-//       result of its MarshalText method as text.
+//   - the XMLName field, described above, is omitted.
+//   - a field with tag "-" is omitted.
+//   - a field with tag "name,attr" becomes an attribute with
+//     the given name in the XML element.
+//   - a field with tag ",attr" becomes an attribute with the
+//     field name in the XML element.
+//   - a field with tag ",chardata" is written as character data,
+//     not as an XML element.
+//   - a field with tag ",cdata" is written as character data
+//     wrapped in one or more <![CDATA[ ... ]]> tags, not as an XML element.
+//   - a field with tag ",innerxml" is written verbatim, not subject
+//     to the usual marshaling procedure.
+//   - a field with tag ",comment" is written as an XML comment, not
+//     subject to the usual marshaling procedure. It must not contain
+//     the "--" string within it.
+//   - a field with a tag including the "omitempty" option is omitted
+//     if the field value is empty. The empty values are false, 0, any
+//     nil pointer or interface value, and any array, slice, map, or
+//     string of length zero.
+//   - an anonymous struct field is handled as if the fields of its
+//     value were part of the outer struct.
+//   - a field implementing Marshaler is written by calling its MarshalXML
+//     method.
+//   - a field implementing encoding.TextMarshaler is written by encoding the
+//     result of its MarshalText method as text.
 //
 // If a field uses a tag "a>b>c", then the element c will be nested inside
 // parent elements a and b. Fields that appear next to each other that name
diff --git a/src/encoding/xml/read.go b/src/encoding/xml/read.go
index 0701e18625..565d9a8bea 100644
--- a/src/encoding/xml/read.go
+++ b/src/encoding/xml/read.go
@@ -35,62 +35,62 @@ import (
 // In the rules, the tag of a field refers to the value associated with the
 // key 'xml' in the struct field's tag (see the example above).
 //
-//   * If the struct has a field of type []byte or string with tag
-//      ",innerxml", Unmarshal accumulates the raw XML nested inside the
-//      element in that field. The rest of the rules still apply.
+//   - If the struct has a field of type []byte or string with tag
+//     ",innerxml", Unmarshal accumulates the raw XML nested inside the
+//     element in that field. The rest of the rules still apply.
 //
-//   * If the struct has a field named XMLName of type Name,
-//      Unmarshal records the element name in that field.
+//   - If the struct has a field named XMLName of type Name,
+//     Unmarshal records the element name in that field.
 //
-//   * If the XMLName field has an associated tag of the form
-//      "name" or "namespace-URL name", the XML element must have
-//      the given name (and, optionally, name space) or else Unmarshal
-//      returns an error.
+//   - If the XMLName field has an associated tag of the form
+//     "name" or "namespace-URL name", the XML element must have
+//     the given name (and, optionally, name space) or else Unmarshal
+//     returns an error.
 //
-//   * If the XML element has an attribute whose name matches a
-//      struct field name with an associated tag containing ",attr" or
-//      the explicit name in a struct field tag of the form "name,attr",
-//      Unmarshal records the attribute value in that field.
+//   - If the XML element has an attribute whose name matches a
+//     struct field name with an associated tag containing ",attr" or
+//     the explicit name in a struct field tag of the form "name,attr",
+//     Unmarshal records the attribute value in that field.
 //
-//   * If the XML element has an attribute not handled by the previous
-//      rule and the struct has a field with an associated tag containing
-//      ",any,attr", Unmarshal records the attribute value in the first
-//      such field.
+//   - If the XML element has an attribute not handled by the previous
+//     rule and the struct has a field with an associated tag containing
+//     ",any,attr", Unmarshal records the attribute value in the first
+//     such field.
 //
-//   * If the XML element contains character data, that data is
-//      accumulated in the first struct field that has tag ",chardata".
-//      The struct field may have type []byte or string.
-//      If there is no such field, the character data is discarded.
+//   - If the XML element contains character data, that data is
+//     accumulated in the first struct field that has tag ",chardata".
+//     The struct field may have type []byte or string.
+//     If there is no such field, the character data is discarded.
 //
-//   * If the XML element contains comments, they are accumulated in
-//      the first struct field that has tag ",comment".  The struct
-//      field may have type []byte or string. If there is no such
-//      field, the comments are discarded.
+//   - If the XML element contains comments, they are accumulated in
+//     the first struct field that has tag ",comment".  The struct
+//     field may have type []byte or string. If there is no such
+//     field, the comments are discarded.
 //
-//   * If the XML element contains a sub-element whose name matches
-//      the prefix of a tag formatted as "a" or "a>b>c", unmarshal
-//      will descend into the XML structure looking for elements with the
-//      given names, and will map the innermost elements to that struct
-//      field. A tag starting with ">" is equivalent to one starting
-//      with the field name followed by ">".
+//   - If the XML element contains a sub-element whose name matches
+//     the prefix of a tag formatted as "a" or "a>b>c", unmarshal
+//     will descend into the XML structure looking for elements with the
+//     given names, and will map the innermost elements to that struct
+//     field. A tag starting with ">" is equivalent to one starting
+//     with the field name followed by ">".
 //
-//   * If the XML element contains a sub-element whose name matches
-//      a struct field's XMLName tag and the struct field has no
-//      explicit name tag as per the previous rule, unmarshal maps
-//      the sub-element to that struct field.
+//   - If the XML element contains a sub-element whose name matches
+//     a struct field's XMLName tag and the struct field has no
+//     explicit name tag as per the previous rule, unmarshal maps
+//     the sub-element to that struct field.
 //
-//   * If the XML element contains a sub-element whose name matches a
-//      field without any mode flags (",attr", ",chardata", etc), Unmarshal
-//      maps the sub-element to that struct field.
+//   - If the XML element contains a sub-element whose name matches a
+//     field without any mode flags (",attr", ",chardata", etc), Unmarshal
+//     maps the sub-element to that struct field.
 //
-//   * If the XML element contains a sub-element that hasn't matched any
-//      of the above rules and the struct has a field with tag ",any",
-//      unmarshal maps the sub-element to that struct field.
+//   - If the XML element contains a sub-element that hasn't matched any
+//     of the above rules and the struct has a field with tag ",any",
+//     unmarshal maps the sub-element to that struct field.
 //
-//   * An anonymous struct field is handled as if the fields of its
-//      value were part of the outer struct.
+//   - An anonymous struct field is handled as if the fields of its
+//     value were part of the outer struct.
 //
-//   * A struct field with tag "-" is never unmarshaled into.
+//   - A struct field with tag "-" is never unmarshaled into.
 //
 // If Unmarshal encounters a field type that implements the Unmarshaler
 // interface, Unmarshal calls its UnmarshalXML method to produce the value from