Browse Source

all: minor documentation adjustments (#1112)

pull/1125/head
Joe Tsai 4 years ago
committed by GitHub
parent
commit
b5de78c91d
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 38 additions and 33 deletions
  1. +6
    -2
      README.md
  2. +7
    -7
      descriptor/descriptor.go
  3. +2
    -2
      jsonpb/decode.go
  4. +4
    -4
      jsonpb/encode.go
  5. +4
    -4
      jsonpb/json.go
  6. +7
    -7
      proto/buffer.go
  7. +2
    -2
      proto/extensions.go
  8. +4
    -4
      proto/text_encode.go
  9. +2
    -1
      protoc-gen-go/generator/generator.go

+ 6
- 2
README.md View File

@ -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


+ 7
- 7
descriptor/descriptor.go View File

@ -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) {


+ 2
- 2
jsonpb/decode.go View File

@ -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")


+ 4
- 4
jsonpb/encode.go View File

@ -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 {


+ 4
- 4
jsonpb/json.go View File

@ -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)
}


+ 7
- 7
proto/buffer.go View File

@ -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 {


+ 2
- 2
proto/extensions.go View File

@ -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.


+ 4
- 4
proto/text_encode.go View File

@ -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")


+ 2
- 1
protoc-gen-go/generator/generator.go View File

@ -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 (


Loading…
Cancel
Save