all: minor documentation adjustments (#1112)
diff --git a/README.md b/README.md
index 4f4302c..2e4233f 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,11 @@
Versions v1.4 and later of `github.com/golang/protobuf` are implemented
in terms of `google.golang.org/protobuf`.
-Programs which use both modules should use at least version v1.4 of this one.
+Programs which use both modules must use at least version v1.4 of this one.
+
+See the
+[developer guide for protocol buffers in Go](https://developers.google.com/protocol-buffers/docs/gotutorial)
+for a general guide for how to get started using protobufs in Go.
See
[release note documentation](https://github.com/golang/protobuf/releases)
@@ -51,7 +55,7 @@
Package `wrappers` is the generated package for
`google/protobuf/wrappers.proto`.
* [`ptypes/struct`](https://pkg.go.dev/github.com/golang/protobuf/ptypes/struct):
- Package `struct` is the generated package for
+ Package `structpb` is the generated package for
`google/protobuf/struct.proto`.
* [`protoc-gen-go/descriptor`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/descriptor):
Package `descriptor` is the generated package for
diff --git a/descriptor/descriptor.go b/descriptor/descriptor.go
index 53390ea..c3c4a2b 100644
--- a/descriptor/descriptor.go
+++ b/descriptor/descriptor.go
@@ -5,8 +5,8 @@
// Package descriptor provides functions for obtaining the protocol buffer
// descriptors of generated Go types.
//
-// Deprecated: Use the "google.golang.org/protobuf/reflect/protoreflect"
-// package instead to obtain an EnumDescriptor or MessageDescriptor in order to
+// Deprecated: See the "google.golang.org/protobuf/reflect/protoreflect" package
+// for how to obtain an EnumDescriptor or MessageDescriptor in order to
// programatically interact with the protobuf type system.
package descriptor
@@ -99,8 +99,8 @@
return file, idxs
}
-// EnumRawDescriptor returns the GZIP'd raw file descriptor containing the
-// enum and the index path to reach the enum declaration.
+// EnumRawDescriptor returns the GZIP'd raw file descriptor representing
+// the enum and the index path to reach the enum declaration.
// The returned slices must not be mutated.
func EnumRawDescriptor(e proto.GeneratedEnum) ([]byte, []int) {
if ev, ok := e.(interface{ EnumDescriptor() ([]byte, []int) }); ok {
@@ -110,7 +110,7 @@
return deriveRawDescriptor(ed.Descriptor())
}
-// MessageRawDescriptor returns the GZIP'd raw file descriptor containing
+// MessageRawDescriptor returns the GZIP'd raw file descriptor representing
// the message and the index path to reach the message declaration.
// The returned slices must not be mutated.
func MessageRawDescriptor(m proto.GeneratedMessage) ([]byte, []int) {
@@ -148,7 +148,7 @@
return fd
}
-// EnumDescriptorProto returns the file descriptor proto containing
+// EnumDescriptorProto returns the file descriptor proto representing
// the enum and the enum descriptor proto for the enum itself.
// The returned proto messages must not be mutated.
func EnumDescriptorProto(e proto.GeneratedEnum) (*descriptorpb.FileDescriptorProto, *descriptorpb.EnumDescriptorProto) {
@@ -168,7 +168,7 @@
return fd, ed
}
-// MessageDescriptorProto returns the file descriptor proto containing
+// MessageDescriptorProto returns the file descriptor proto representing
// the message and the message descriptor proto for the message itself.
// The returned proto messages must not be mutated.
func MessageDescriptorProto(m proto.GeneratedMessage) (*descriptorpb.FileDescriptorProto, *descriptorpb.DescriptorProto) {
diff --git a/jsonpb/decode.go b/jsonpb/decode.go
index 6faa5fe..8573830 100644
--- a/jsonpb/decode.go
+++ b/jsonpb/decode.go
@@ -24,7 +24,7 @@
const wrapJSONUnmarshalV2 = false
-// UnmarshalNext unmarshals the next object in a JSON object stream into m.
+// UnmarshalNext unmarshals the next JSON object from d into m.
func UnmarshalNext(d *json.Decoder, m proto.Message) error {
return new(Unmarshaler).UnmarshalNext(d, m)
}
@@ -68,7 +68,7 @@
return u.UnmarshalNext(json.NewDecoder(r), m)
}
-// UnmarshalNext unmarshals the next object in a JSON object stream into m.
+// UnmarshalNext unmarshals the next JSON object from d into m.
func (u *Unmarshaler) UnmarshalNext(d *json.Decoder, m proto.Message) error {
if m == nil {
return errors.New("invalid nil message")
diff --git a/jsonpb/encode.go b/jsonpb/encode.go
index c5b80bc..7633019 100644
--- a/jsonpb/encode.go
+++ b/jsonpb/encode.go
@@ -35,11 +35,11 @@
// as opposed to string values.
EnumsAsInts bool
- // EmitDefaults specifies Whether to render fields with zero values.
+ // EmitDefaults specifies whether to render fields with zero values.
EmitDefaults bool
// Indent controls whether the output is compact or not.
- // If empty, the output is compact JSON. If non-empty, every JSON object
+ // If empty, the output is compact JSON. Otherwise, every JSON object
// entry and JSON array value will be on its own line.
// Each line will be preceded by repeated copies of Indent, where the
// number of copies is the current indentation depth.
@@ -62,7 +62,7 @@
MarshalJSONPB(*Marshaler) ([]byte, error)
}
-// Marshal marshals a protocol buffer into JSON.
+// Marshal serializes a protobuf message as JSON into w.
func (jm *Marshaler) Marshal(w io.Writer, m proto.Message) error {
b, err := jm.marshal(m)
if len(b) > 0 {
@@ -73,7 +73,7 @@
return err
}
-// MarshalToString converts a protocol buffer object to JSON string.
+// MarshalToString serializes a protobuf message as JSON in string form.
func (jm *Marshaler) MarshalToString(m proto.Message) (string, error) {
b, err := jm.marshal(m)
if err != nil {
diff --git a/jsonpb/json.go b/jsonpb/json.go
index 6b74410..480e244 100644
--- a/jsonpb/json.go
+++ b/jsonpb/json.go
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package jsonpb provides marshaling and unmarshaling between a protocol buffer
-// message and JSON. It follows the specification at
+// Package jsonpb provides functionality to marshal and unmarshal between a
+// protocol buffer message and JSON. It follows the specification at
// https://developers.google.com/protocol-buffers/docs/proto3#json.
//
// Do not rely on the default behavior of the standard encoding/json package
@@ -20,8 +20,8 @@
"google.golang.org/protobuf/runtime/protoimpl"
)
-// AnyResolver takes a type URL, present in an Any message, and resolves it into
-// an instance of the associated message.
+// AnyResolver takes a type URL, present in an Any message,
+// and resolves it into an instance of the associated message.
type AnyResolver interface {
Resolve(typeURL string) (proto.Message, error)
}
diff --git a/proto/buffer.go b/proto/buffer.go
index 62df7e3..e810e6f 100644
--- a/proto/buffer.go
+++ b/proto/buffer.go
@@ -33,8 +33,8 @@
return protowire.SizeVarint(v)
}
-// DecodeVarint parses a varint encoded integer from b, returning the
-// integer value and the length of the varint.
+// DecodeVarint parses a varint encoded integer from b,
+// returning the integer value and the length of the varint.
// It returns (0, 0) if there is a parse error.
func DecodeVarint(b []byte) (uint64, int) {
v, n := protowire.ConsumeVarint(b)
@@ -112,9 +112,9 @@
return err
}
-// Unmarshal parses the wire-format message in the buffer and places the decoded results in m.
-//
-// Unlike proto.Unmarshal, this does not reset the message before starting to unmarshal.
+// Unmarshal parses the wire-format message in the buffer and
+// places the decoded results in m.
+// It does not reset m before unmarshaling.
func (b *Buffer) Unmarshal(m Message) error {
err := UnmarshalMerge(b.Unread(), m)
b.idx = len(b.buf)
@@ -260,7 +260,7 @@
}
// DecodeMessage consumes a length-prefixed message from the buffer.
-// It does not reset m.
+// It does not reset m before unmarshaling.
func (b *Buffer) DecodeMessage(m Message) error {
v, err := b.DecodeRawBytes(false)
if err != nil {
@@ -272,7 +272,7 @@
// DecodeGroup consumes a message group from the buffer.
// It assumes that the start group marker has already been consumed and
// consumes all bytes until (and including the end group marker).
-// It does not reset m.
+// It does not reset m before unmarshaling.
func (b *Buffer) DecodeGroup(m Message) error {
v, n, err := consumeGroup(b.buf[b.idx:])
if err != nil {
diff --git a/proto/extensions.go b/proto/extensions.go
index 5ed131c..42fc120 100644
--- a/proto/extensions.go
+++ b/proto/extensions.go
@@ -68,7 +68,7 @@
return has
}
-// ClearExtension removes the the exntesion field from m
+// ClearExtension removes the extension field from m
// either as an explicitly populated field or as an unknown field.
func ClearExtension(m Message, xt *ExtensionDesc) {
mr := MessageReflect(m)
@@ -108,7 +108,7 @@
clearUnknown(mr, mr.Descriptor().ExtensionRanges())
}
-// GetExtension retrieves a proto2 extended field from pb.
+// GetExtension retrieves a proto2 extended field from m.
//
// If the descriptor is type complete (i.e., ExtensionDesc.ExtensionType is non-nil),
// then GetExtension parses the encoded field and returns a Go value of the specified type.
diff --git a/proto/text_encode.go b/proto/text_encode.go
index 7ac02e6..a31134e 100644
--- a/proto/text_encode.go
+++ b/proto/text_encode.go
@@ -94,16 +94,16 @@
)
// MarshalText writes the proto text format of m to w.
-func MarshalText(w io.Writer, pb Message) error { return defaultTextMarshaler.Marshal(w, pb) }
+func MarshalText(w io.Writer, m Message) error { return defaultTextMarshaler.Marshal(w, m) }
// MarshalTextString returns a proto text formatted string of m.
-func MarshalTextString(pb Message) string { return defaultTextMarshaler.Text(pb) }
+func MarshalTextString(m Message) string { return defaultTextMarshaler.Text(m) }
// CompactText writes the compact proto text format of m to w.
-func CompactText(w io.Writer, pb Message) error { return compactTextMarshaler.Marshal(w, pb) }
+func CompactText(w io.Writer, m Message) error { return compactTextMarshaler.Marshal(w, m) }
// CompactTextString returns a compact proto text formatted string of m.
-func CompactTextString(pb Message) string { return compactTextMarshaler.Text(pb) }
+func CompactTextString(m Message) string { return compactTextMarshaler.Text(m) }
var (
newline = []byte("\n")
diff --git a/protoc-gen-go/generator/generator.go b/protoc-gen-go/generator/generator.go
index 791f511..12ff35b 100644
--- a/protoc-gen-go/generator/generator.go
+++ b/protoc-gen-go/generator/generator.go
@@ -7,7 +7,8 @@
// This package is excluded from the Go protocol buffer compatibility guarantee
// and may be deleted at some point in the future.
//
-// Deprecated: Do not use.
+// Deprecated: Use the "google.golang.org/protobuf/compiler/protogen" package
+// instead to write protoc plugins in Go.
package generator
import (
