Skip to content

Commit b5de78c

Browse files
dsnetdsnet
authored
all: minor documentation adjustments (#1112)
1 parent 8d9af28 commit b5de78c

File tree

9 files changed

+38
-33
lines changed

9 files changed

+38
-33
lines changed

‎README.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,11 @@ We recommend that new code use the `google.golang.org/protobuf` module.
1515

1616
Versions v1.4 and later of `github.com/golang/protobuf` are implemented
1717
in terms of `google.golang.org/protobuf`.
18-
Programs which use both modules should use at least version v1.4 of this one.
18+
Programs which use both modules must use at least version v1.4 of this one.
19+
20+
See the
21+
[developer guide for protocol buffers in Go](https://developers.google.com/protocol-buffers/docs/gotutorial)
22+
for a general guide for how to get started using protobufs in Go.
1923

2024
See
2125
[release note documentation](https://github.com/golang/protobuf/releases)
@@ -51,7 +55,7 @@ Summary of the packages provided by this module:
5155
Package `wrappers` is the generated package for
5256
`google/protobuf/wrappers.proto`.
5357
* [`ptypes/struct`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/struct):
54-
Package `struct` is the generated package for
58+
Package `structpb` is the generated package for
5559
`google/protobuf/struct.proto`.
5660
* [`protoc-gen-go/descriptor`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/descriptor):
5761
Package `descriptor` is the generated package for

‎descriptor/descriptor.go‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@
55
// Package descriptor provides functions for obtaining the protocol buffer
66
// descriptors of generated Go types.
77
//
8-
// Deprecated: Use the "google.golang.org/protobuf/reflect/protoreflect"
9-
// package instead to obtain an EnumDescriptor or MessageDescriptor in order to
8+
// Deprecated: See the "google.golang.org/protobuf/reflect/protoreflect" package
9+
// for how to obtain an EnumDescriptor or MessageDescriptor in order to
1010
// programatically interact with the protobuf type system.
1111
package descriptor
1212

@@ -99,8 +99,8 @@ func deriveRawDescriptor(d protoreflect.Descriptor) ([]byte, []int) {
9999
return file, idxs
100100
}
101101

102-
// EnumRawDescriptor returns the GZIP'd raw file descriptor containing the
103-
// enum and the index path to reach the enum declaration.
102+
// EnumRawDescriptor returns the GZIP'd raw file descriptor representing
103+
// the enum and the index path to reach the enum declaration.
104104
// The returned slices must not be mutated.
105105
func EnumRawDescriptor(e proto.GeneratedEnum) ([]byte, []int) {
106106
if ev, ok := e.(interface{ EnumDescriptor() ([]byte, []int) }); ok {
@@ -110,7 +110,7 @@ func EnumRawDescriptor(e proto.GeneratedEnum) ([]byte, []int) {
110110
return deriveRawDescriptor(ed.Descriptor())
111111
}
112112

113-
// MessageRawDescriptor returns the GZIP'd raw file descriptor containing
113+
// MessageRawDescriptor returns the GZIP'd raw file descriptor representing
114114
// the message and the index path to reach the message declaration.
115115
// The returned slices must not be mutated.
116116
func MessageRawDescriptor(m proto.GeneratedMessage) ([]byte, []int) {
@@ -148,7 +148,7 @@ func deriveFileDescriptor(rawDesc []byte) *descriptorpb.FileDescriptorProto {
148148
return fd
149149
}
150150

151-
// EnumDescriptorProto returns the file descriptor proto containing
151+
// EnumDescriptorProto returns the file descriptor proto representing
152152
// the enum and the enum descriptor proto for the enum itself.
153153
// The returned proto messages must not be mutated.
154154
func EnumDescriptorProto(e proto.GeneratedEnum) (*descriptorpb.FileDescriptorProto, *descriptorpb.EnumDescriptorProto) {
@@ -168,7 +168,7 @@ func EnumDescriptorProto(e proto.GeneratedEnum) (*descriptorpb.FileDescriptorPro
168168
return fd, ed
169169
}
170170

171-
// MessageDescriptorProto returns the file descriptor proto containing
171+
// MessageDescriptorProto returns the file descriptor proto representing
172172
// the message and the message descriptor proto for the message itself.
173173
// The returned proto messages must not be mutated.
174174
func MessageDescriptorProto(m proto.GeneratedMessage) (*descriptorpb.FileDescriptorProto, *descriptorpb.DescriptorProto) {

‎jsonpb/decode.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ import (
2424

2525
const wrapJSONUnmarshalV2 = false
2626

27-
// UnmarshalNext unmarshals the next object in a JSON object stream into m.
27+
// UnmarshalNext unmarshals the next JSON object from d into m.
2828
func UnmarshalNext(d *json.Decoder, m proto.Message) error {
2929
return new(Unmarshaler).UnmarshalNext(d, m)
3030
}
@@ -68,7 +68,7 @@ func (u *Unmarshaler) Unmarshal(r io.Reader, m proto.Message) error {
6868
return u.UnmarshalNext(json.NewDecoder(r), m)
6969
}
7070

71-
// UnmarshalNext unmarshals the next object in a JSON object stream into m.
71+
// UnmarshalNext unmarshals the next JSON object from d into m.
7272
func (u *Unmarshaler) UnmarshalNext(d *json.Decoder, m proto.Message) error {
7373
if m == nil {
7474
return errors.New("invalid nil message")

‎jsonpb/encode.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,11 @@ type Marshaler struct {
3535
// as opposed to string values.
3636
EnumsAsInts bool
3737

38-
// EmitDefaults specifies Whether to render fields with zero values.
38+
// EmitDefaults specifies whether to render fields with zero values.
3939
EmitDefaults bool
4040

4141
// Indent controls whether the output is compact or not.
42-
// If empty, the output is compact JSON. If non-empty, every JSON object
42+
// If empty, the output is compact JSON. Otherwise, every JSON object
4343
// entry and JSON array value will be on its own line.
4444
// Each line will be preceded by repeated copies of Indent, where the
4545
// number of copies is the current indentation depth.
@@ -62,7 +62,7 @@ type JSONPBMarshaler interface {
6262
MarshalJSONPB(*Marshaler) ([]byte, error)
6363
}
6464

65-
// Marshal marshals a protocol buffer into JSON.
65+
// Marshal serializes a protobuf message as JSON into w.
6666
func (jm *Marshaler) Marshal(w io.Writer, m proto.Message) error {
6767
b, err := jm.marshal(m)
6868
if len(b) > 0 {
@@ -73,7 +73,7 @@ func (jm *Marshaler) Marshal(w io.Writer, m proto.Message) error {
7373
return err
7474
}
7575

76-
// MarshalToString converts a protocol buffer object to JSON string.
76+
// MarshalToString serializes a protobuf message as JSON in string form.
7777
func (jm *Marshaler) MarshalToString(m proto.Message) (string, error) {
7878
b, err := jm.marshal(m)
7979
if err != nil {

‎jsonpb/json.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
// Use of this source code is governed by a BSD-style
33
// license that can be found in the LICENSE file.
44

5-
// Package jsonpb provides marshaling and unmarshaling between a protocol buffer
6-
// message and JSON. It follows the specification at
5+
// Package jsonpb provides functionality to marshal and unmarshal between a
6+
// protocol buffer message and JSON. It follows the specification at
77
// https://developers.google.com/protocol-buffers/docs/proto3#json.
88
//
99
// Do not rely on the default behavior of the standard encoding/json package
@@ -20,8 +20,8 @@ import (
2020
"google.golang.org/protobuf/runtime/protoimpl"
2121
)
2222

23-
// AnyResolver takes a type URL, present in an Any message, and resolves it into
24-
// an instance of the associated message.
23+
// AnyResolver takes a type URL, present in an Any message,
24+
// and resolves it into an instance of the associated message.
2525
type AnyResolver interface {
2626
Resolve(typeURL string) (proto.Message, error)
2727
}

‎proto/buffer.go‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,8 @@ func SizeVarint(v uint64) int {
3333
return protowire.SizeVarint(v)
3434
}
3535

36-
// DecodeVarint parses a varint encoded integer from b, returning the
37-
// integer value and the length of the varint.
36+
// DecodeVarint parses a varint encoded integer from b,
37+
// returning the integer value and the length of the varint.
3838
// It returns (0, 0) if there is a parse error.
3939
func DecodeVarint(b []byte) (uint64, int) {
4040
v, n := protowire.ConsumeVarint(b)
@@ -112,9 +112,9 @@ func (b *Buffer) Marshal(m Message) error {
112112
return err
113113
}
114114

115-
// Unmarshal parses the wire-format message in the buffer and places the decoded results in m.
116-
//
117-
// Unlike proto.Unmarshal, this does not reset the message before starting to unmarshal.
115+
// Unmarshal parses the wire-format message in the buffer and
116+
// places the decoded results in m.
117+
// It does not reset m before unmarshaling.
118118
func (b *Buffer) Unmarshal(m Message) error {
119119
err := UnmarshalMerge(b.Unread(), m)
120120
b.idx = len(b.buf)
@@ -260,7 +260,7 @@ func (b *Buffer) DecodeStringBytes() (string, error) {
260260
}
261261

262262
// DecodeMessage consumes a length-prefixed message from the buffer.
263-
// It does not reset m.
263+
// It does not reset m before unmarshaling.
264264
func (b *Buffer) DecodeMessage(m Message) error {
265265
v, err := b.DecodeRawBytes(false)
266266
if err != nil {
@@ -272,7 +272,7 @@ func (b *Buffer) DecodeMessage(m Message) error {
272272
// DecodeGroup consumes a message group from the buffer.
273273
// It assumes that the start group marker has already been consumed and
274274
// consumes all bytes until (and including the end group marker).
275-
// It does not reset m.
275+
// It does not reset m before unmarshaling.
276276
func (b *Buffer) DecodeGroup(m Message) error {
277277
v, n, err := consumeGroup(b.buf[b.idx:])
278278
if err != nil {

‎proto/extensions.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ func HasExtension(m Message, xt *ExtensionDesc) (has bool) {
6868
return has
6969
}
7070

71-
// ClearExtension removes the the exntesion field from m
71+
// ClearExtension removes the extension field from m
7272
// either as an explicitly populated field or as an unknown field.
7373
func ClearExtension(m Message, xt *ExtensionDesc) {
7474
mr := MessageReflect(m)
@@ -108,7 +108,7 @@ func ClearAllExtensions(m Message) {
108108
clearUnknown(mr, mr.Descriptor().ExtensionRanges())
109109
}
110110

111-
// GetExtension retrieves a proto2 extended field from pb.
111+
// GetExtension retrieves a proto2 extended field from m.
112112
//
113113
// If the descriptor is type complete (i.e., ExtensionDesc.ExtensionType is non-nil),
114114
// then GetExtension parses the encoded field and returns a Go value of the specified type.

‎proto/text_encode.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -94,16 +94,16 @@ var (
9494
)
9595

9696
// MarshalText writes the proto text format of m to w.
97-
func MarshalText(w io.Writer, pb Message) error { return defaultTextMarshaler.Marshal(w, pb) }
97+
func MarshalText(w io.Writer, m Message) error { return defaultTextMarshaler.Marshal(w, m) }
9898

9999
// MarshalTextString returns a proto text formatted string of m.
100-
func MarshalTextString(pb Message) string { return defaultTextMarshaler.Text(pb) }
100+
func MarshalTextString(m Message) string { return defaultTextMarshaler.Text(m) }
101101

102102
// CompactText writes the compact proto text format of m to w.
103-
func CompactText(w io.Writer, pb Message) error { return compactTextMarshaler.Marshal(w, pb) }
103+
func CompactText(w io.Writer, m Message) error { return compactTextMarshaler.Marshal(w, m) }
104104

105105
// CompactTextString returns a compact proto text formatted string of m.
106-
func CompactTextString(pb Message) string { return compactTextMarshaler.Text(pb) }
106+
func CompactTextString(m Message) string { return compactTextMarshaler.Text(m) }
107107

108108
var (
109109
newline = []byte("\n")

‎protoc-gen-go/generator/generator.go‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@
77
// This package is excluded from the Go protocol buffer compatibility guarantee
88
// and may be deleted at some point in the future.
99
//
10-
// Deprecated: Do not use.
10+
// Deprecated: Use the "google.golang.org/protobuf/compiler/protogen" package
11+
// instead to write protoc plugins in Go.
1112
package generator
1213

1314
import (

0 commit comments

Comments
 (0)