From 19309779ac5e2f5a2fd3cbb34421dafb2855ac21 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Thu, 3 Feb 2022 14:12:08 -0500 Subject: 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 Reviewed-by: Ian Lance Taylor --- src/encoding/binary/varint.go | 12 +++--- src/encoding/gob/debug.go | 27 +++++++++++++ src/encoding/gob/decoder.go | 2 + src/encoding/gob/doc.go | 6 +-- src/encoding/json/encode.go | 30 +++++++-------- src/encoding/json/fold.go | 5 ++- src/encoding/pem/pem.go | 10 +++-- src/encoding/xml/marshal.go | 60 ++++++++++++++--------------- src/encoding/xml/read.go | 88 +++++++++++++++++++++---------------------- 9 files changed, 136 insertions(+), 104 deletions(-) (limited to 'src/encoding') 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 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 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 -- cgit v1.3