all: minor documentation adjustments (#1112)

Author: dsnet

Diff for: README.md

@@ -15,7 +15,11 @@ We recommend that new code use the `google.golang.org/protobuf` module.
 
 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 @@ Summary of the packages provided by this module:
     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 for: 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 @@ func deriveRawDescriptor(d protoreflect.Descriptor) ([]byte, []int) {
 	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 @@ func EnumRawDescriptor(e proto.GeneratedEnum) ([]byte, []int) {
 	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 @@ func deriveFileDescriptor(rawDesc []byte) *descriptorpb.FileDescriptorProto {
 	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 @@ func EnumDescriptorProto(e proto.GeneratedEnum) (*descriptorpb.FileDescriptorPro
 	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 for: jsonpb/decode.go

@@ -24,7 +24,7 @@ import (
 
 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 @@ func (u *Unmarshaler) Unmarshal(r io.Reader, m proto.Message) error {
 	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 for: jsonpb/encode.go

@@ -35,11 +35,11 @@ type Marshaler struct {
 	// 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 @@ type JSONPBMarshaler interface {
 	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 @@ func (jm *Marshaler) Marshal(w io.Writer, m proto.Message) error {
 	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 for: 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 @@ import (
 	"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 for: proto/buffer.go

@@ -33,8 +33,8 @@ func SizeVarint(v uint64) int {
 	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 @@ func (b *Buffer) Marshal(m Message) error {
 	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 @@ func (b *Buffer) DecodeStringBytes() (string, error) {
 }
 
 // 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 @@ func (b *Buffer) DecodeMessage(m Message) error {
 // 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 for: proto/extensions.go

@@ -68,7 +68,7 @@ func HasExtension(m Message, xt *ExtensionDesc) (has bool) {
 	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 @@ func ClearAllExtensions(m Message) {
 	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 for: proto/text_encode.go

@@ -94,16 +94,16 @@ var (
 )
 
 // 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 for: 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 (