mirror/protobuf-go
1
0
Fork 0
mirror of https://github.com/protocolbuffers/protobuf-go.git synced 2025-02-04 12:39:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

all: modernize documentation

Browse Source 
Modernize the documentation across the entire module
to make use of the newer ability to linkify declarations.

Change-Id: I440f9a3f025ec6fadfd9cba59b1dfb57028bf3f1
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/309430
Reviewed-by: Michael Stapelberg <stapelberg@google.com>
Reviewed-by: Damien Neil <dneil@google.com>
This commit is contained in:
Joe Tsai 2021-04-12 13:48:27 -07:00 committed by Michael Stapelberg
parent 6d0a5dbd95
commit f9212a8dfa
32 changed files with 360 additions and 355 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
compiler/protogen/protogen.go
View File

@ -5,8 +5,8 @@
// Package protogen provides support for writing protoc plugins.
//
// Plugins for protoc, the Protocol Buffer compiler,
// are programs which read a CodeGeneratorRequest message from standard input
// and write a CodeGeneratorResponse message to standard output.
// are programs which read a [pluginpb.CodeGeneratorRequest] message from standard input
// and write a [pluginpb.CodeGeneratorResponse] message to standard output.
// This package provides support for writing plugins which generate Go code.
package protogen
@ -44,11 +44,11 @@ const goPackageDocURL = "https://protobuf.dev/reference/go/go-generated#package"
// Run executes a function as a protoc plugin.
//
// It reads a CodeGeneratorRequest message from os.Stdin, invokes the plugin
// function, and writes a CodeGeneratorResponse message to os.Stdout.
// It reads a [pluginpb.CodeGeneratorRequest] message from [os.Stdin], invokes the plugin
// function, and writes a [pluginpb.CodeGeneratorResponse] message to [os.Stdout].
//
// If a failure occurs while reading or writing, Run prints an error to
// os.Stderr and calls os.Exit(1).
// [os.Stderr] and calls [os.Exit](1).
func (opts Options) Run(f func(*Plugin) error) {
if err := run(opts, f); err != nil {
fmt.Fprintf(os.Stderr, "%s: %v\n", filepath.Base(os.Args[0]), err)
@ -834,7 +834,7 @@ func newOneof(gen *Plugin, f *File, message *Message, desc protoreflect.OneofDes
}
}
// Extension is an alias of Field for documentation.
// Extension is an alias of [Field] for documentation.
type Extension = Field
// A Service describes a service.
@ -946,7 +946,7 @@ func (gen *Plugin) NewGeneratedFile(filename string, goImportPath GoImportPath)
}
// P prints a line to the generated output. It converts each parameter to a
// string following the same rules as fmt.Print. It never inserts spaces
// string following the same rules as [fmt.Print]. It never inserts spaces
// between parameters.
func (g *GeneratedFile) P(v ...interface{}) {
for _, x := range v {
@ -983,14 +983,14 @@ func (g *GeneratedFile) QualifiedGoIdent(ident GoIdent) string {
// Import ensures a package is imported by the generated file.
//
// Packages referenced by QualifiedGoIdent are automatically imported.
// Packages referenced by [GeneratedFile.QualifiedGoIdent] are automatically imported.
// Explicitly importing a package with Import is generally only necessary
// when the import will be blank (import _ "package").
func (g *GeneratedFile) Import(importPath GoImportPath) {
g.manualImports[importPath] = true
}
// Write implements io.Writer.
// Write implements [io.Writer].
func (g *GeneratedFile) Write(p []byte) (n int, err error) {
return g.buf.Write(p)
}
@ -1000,8 +1000,8 @@ func (g *GeneratedFile) Skip() {
g.skip = true
}
// Unskip reverts a previous call to Skip, re-including the generated file in
// the plugin output.
// Unskip reverts a previous call to [GeneratedFile.Skip],
// re-including the generated file in the plugin output.
func (g *GeneratedFile) Unskip() {
g.skip = false
}
@ -1013,7 +1013,7 @@ func (g *GeneratedFile) Unskip() {
// struct field. The "T.sel" syntax is used to identify the method or field
// 'sel' on type 'T'.
//
// Deprecated: Use the AnnotateSymbol method instead.
// Deprecated: Use the [GeneratedFile.AnnotateSymbol] method instead.
func (g *GeneratedFile) Annotate(symbol string, loc Location) {
g.AnnotateSymbol(symbol, Annotation{Location: loc})
}
@ -1319,7 +1319,7 @@ func (c Comments) String() string {
// file for which we are generating bindings.
//
// Lookups consult the local type registry first and fall back to the base type
// registry which defaults to protoregistry.GlobalTypes
// registry which defaults to protoregistry.GlobalTypes.
type extensionRegistry struct {
base *protoregistry.Types
local *protoregistry.Types

14
encoding/protodelim/protodelim.go
View File

@ -42,7 +42,7 @@ func (o MarshalOptions) MarshalTo(w io.Writer, m proto.Message) (int, error) {
// MarshalTo writes a varint size-delimited wire-format message to w
// with the default options.
//
// See the documentation for MarshalOptions.MarshalTo.
// See the documentation for [MarshalOptions.MarshalTo].
func MarshalTo(w io.Writer, m proto.Message) (int, error) {
return MarshalOptions{}.MarshalTo(w, m)
}
@ -61,7 +61,7 @@ type UnmarshalOptions struct {
const defaultMaxSize = 4 << 20 // 4 MiB, corresponds to the default gRPC max request/response size
// SizeTooLargeError is an error that is returned when the unmarshaler encounters a message size
// that is larger than its configured MaxSize.
// that is larger than its configured [UnmarshalOptions.MaxSize].
type SizeTooLargeError struct {
// Size is the varint size of the message encountered
// that was larger than the provided MaxSize.
@ -75,8 +75,8 @@ func (e *SizeTooLargeError) Error() string {
return fmt.Sprintf("message size %d exceeded unmarshaler's maximum configured size %d", e.Size, e.MaxSize)
}
// Reader is the interface expected by UnmarshalFrom.
// It is implemented by *bufio.Reader.
// Reader is the interface expected by [UnmarshalFrom].
// It is implemented by *[bufio.Reader].
type Reader interface {
io.Reader
io.ByteReader
@ -86,11 +86,11 @@ type Reader interface {
// from r.
// The provided message must be mutable (e.g., a non-nil pointer to a message).
//
// The error is io.EOF error only if no bytes are read.
// The error is [io.EOF] error only if no bytes are read.
// If an EOF happens after reading some but not all the bytes,
// UnmarshalFrom returns a non-io.EOF error.
// In particular if r returns a non-io.EOF error, UnmarshalFrom returns it unchanged,
// and if only a size is read with no subsequent message, io.ErrUnexpectedEOF is returned.
// and if only a size is read with no subsequent message, [io.ErrUnexpectedEOF] is returned.
func (o UnmarshalOptions) UnmarshalFrom(r Reader, m proto.Message) error {
var sizeArr [binary.MaxVarintLen64]byte
sizeBuf := sizeArr[:0]
@ -154,7 +154,7 @@ func (o UnmarshalOptions) UnmarshalFrom(r Reader, m proto.Message) error {
// from r with the default options.
// The provided message must be mutable (e.g., a non-nil pointer to a message).
//
// See the documentation for UnmarshalOptions.UnmarshalFrom.
// See the documentation for [UnmarshalOptions.UnmarshalFrom].
func UnmarshalFrom(r Reader, m proto.Message) error {
return UnmarshalOptions{}.UnmarshalFrom(r, m)
}

4
encoding/protojson/decode.go
View File

@ -23,7 +23,7 @@ import (
"google.golang.org/protobuf/reflect/protoregistry"
)
// Unmarshal reads the given []byte into the given proto.Message.
// Unmarshal reads the given []byte into the given [proto.Message].
// The provided message must be mutable (e.g., a non-nil pointer to a message).
func Unmarshal(b []byte, m proto.Message) error {
return UnmarshalOptions{}.Unmarshal(b, m)
@ -49,7 +49,7 @@ type UnmarshalOptions struct {
}
}
// Unmarshal reads the given []byte and populates the given proto.Message
// Unmarshal reads the given []byte and populates the given [proto.Message]
// using options in the UnmarshalOptions object.
// It will clear the message first before setting the fields.
// If it returns an error, the given message may be partially set.

2
encoding/protojson/doc.go
View File

@ -6,6 +6,6 @@
// format. It follows the guide at
// https://protobuf.dev/programming-guides/proto3#json.
//
// This package produces a different output than the standard "encoding/json"
// This package produces a different output than the standard [encoding/json]
// package, which does not operate correctly on protocol buffer messages.
package protojson

4
encoding/protojson/encode.go
View File

@ -31,7 +31,7 @@ func Format(m proto.Message) string {
return MarshalOptions{Multiline: true}.Format(m)
}
// Marshal writes the given proto.Message in JSON format using default options.
// Marshal writes the given [proto.Message] in JSON format using default options.
// Do not depend on the output being stable. It may change over time across
// different versions of the program.
func Marshal(m proto.Message) ([]byte, error) {
@ -102,7 +102,7 @@ func (o MarshalOptions) Format(m proto.Message) string {
return string(b)
}
// Marshal marshals the given proto.Message in the JSON format using options in
// Marshal marshals the given [proto.Message] in the JSON format using options in
// MarshalOptions. Do not depend on the output being stable. It may change over
// time across different versions of the program.
func (o MarshalOptions) Marshal(m proto.Message) ([]byte, error) {

4
encoding/prototext/decode.go
View File

@ -21,7 +21,7 @@ import (
"google.golang.org/protobuf/reflect/protoregistry"
)
// Unmarshal reads the given []byte into the given proto.Message.
// Unmarshal reads the given []byte into the given [proto.Message].
// The provided message must be mutable (e.g., a non-nil pointer to a message).
func Unmarshal(b []byte, m proto.Message) error {
return UnmarshalOptions{}.Unmarshal(b, m)
@ -51,7 +51,7 @@ type UnmarshalOptions struct {
}
}
// Unmarshal reads the given []byte and populates the given proto.Message
// Unmarshal reads the given []byte and populates the given [proto.Message]
// using options in the UnmarshalOptions object.
// The provided message must be mutable (e.g., a non-nil pointer to a message).
func (o UnmarshalOptions) Unmarshal(b []byte, m proto.Message) error {

4
encoding/prototext/encode.go
View File

@ -33,7 +33,7 @@ func Format(m proto.Message) string {
return MarshalOptions{Multiline: true}.Format(m)
}
// Marshal writes the given proto.Message in textproto format using default
// Marshal writes the given [proto.Message] in textproto format using default
// options. Do not depend on the output being stable. It may change over time
// across different versions of the program.
func Marshal(m proto.Message) ([]byte, error) {
@ -97,7 +97,7 @@ func (o MarshalOptions) Format(m proto.Message) string {
return string(b)
}
// Marshal writes the given proto.Message in textproto format using options in
// Marshal writes the given [proto.Message] in textproto format using options in
// MarshalOptions object. Do not depend on the output being stable. It may
// change over time across different versions of the program.
func (o MarshalOptions) Marshal(m proto.Message) ([]byte, error) {

28
encoding/protowire/wire.go
View File

@ -6,7 +6,7 @@
// See https://protobuf.dev/programming-guides/encoding.
//
// For marshaling and unmarshaling entire protobuf messages,
// use the "google.golang.org/protobuf/proto" package instead.
// use the [google.golang.org/protobuf/proto] package instead.
package protowire
import (
@ -87,7 +87,7 @@ func ParseError(n int) error {
// ConsumeField parses an entire field record (both tag and value) and returns
// the field number, the wire type, and the total length.
// This returns a negative length upon an error (see ParseError).
// This returns a negative length upon an error (see [ParseError]).
//
// The total length includes the tag header and the end group marker (if the
// field is a group).
@ -104,8 +104,8 @@ func ConsumeField(b []byte) (Number, Type, int) {
}
// ConsumeFieldValue parses a field value and returns its length.
// This assumes that the field Number and wire Type have already been parsed.
// This returns a negative length upon an error (see ParseError).
// This assumes that the field [Number] and wire [Type] have already been parsed.
// This returns a negative length upon an error (see [ParseError]).
//
// When parsing a group, the length includes the end group marker and
// the end group is verified to match the starting field number.
@ -164,7 +164,7 @@ func AppendTag(b []byte, num Number, typ Type) []byte {
}
// ConsumeTag parses b as a varint-encoded tag, reporting its length.
// This returns a negative length upon an error (see ParseError).
// This returns a negative length upon an error (see [ParseError]).
func ConsumeTag(b []byte) (Number, Type, int) {
v, n := ConsumeVarint(b)
if n < 0 {
@ -263,7 +263,7 @@ func AppendVarint(b []byte, v uint64) []byte {
}
// ConsumeVarint parses b as a varint-encoded uint64, reporting its length.
// This returns a negative length upon an error (see ParseError).
// This returns a negative length upon an error (see [ParseError]).
func ConsumeVarint(b []byte) (v uint64, n int) {
var y uint64
if len(b) <= 0 {
@ -384,7 +384,7 @@ func AppendFixed32(b []byte, v uint32) []byte {
}
// ConsumeFixed32 parses b as a little-endian uint32, reporting its length.
// This returns a negative length upon an error (see ParseError).
// This returns a negative length upon an error (see [ParseError]).
func ConsumeFixed32(b []byte) (v uint32, n int) {
if len(b) < 4 {
return 0, errCodeTruncated
@ -412,7 +412,7 @@ func AppendFixed64(b []byte, v uint64) []byte {
}
// ConsumeFixed64 parses b as a little-endian uint64, reporting its length.
// This returns a negative length upon an error (see ParseError).
// This returns a negative length upon an error (see [ParseError]).
func ConsumeFixed64(b []byte) (v uint64, n int) {
if len(b) < 8 {
return 0, errCodeTruncated
@ -432,7 +432,7 @@ func AppendBytes(b []byte, v []byte) []byte {
}
// ConsumeBytes parses b as a length-prefixed bytes value, reporting its length.
// This returns a negative length upon an error (see ParseError).
// This returns a negative length upon an error (see [ParseError]).
func ConsumeBytes(b []byte) (v []byte, n int) {
m, n := ConsumeVarint(b)
if n < 0 {
@ -456,7 +456,7 @@ func AppendString(b []byte, v string) []byte {
}
// ConsumeString parses b as a length-prefixed bytes value, reporting its length.
// This returns a negative length upon an error (see ParseError).
// This returns a negative length upon an error (see [ParseError]).
func ConsumeString(b []byte) (v string, n int) {
bb, n := ConsumeBytes(b)
return string(bb), n
@ -471,7 +471,7 @@ func AppendGroup(b []byte, num Number, v []byte) []byte {
// ConsumeGroup parses b as a group value until the trailing end group marker,
// and verifies that the end marker matches the provided num. The value v
// does not contain the end marker, while the length does contain the end marker.
// This returns a negative length upon an error (see ParseError).
// This returns a negative length upon an error (see [ParseError]).
func ConsumeGroup(num Number, b []byte) (v []byte, n int) {
n = ConsumeFieldValue(num, StartGroupType, b)
if n < 0 {
@ -495,8 +495,8 @@ func SizeGroup(num Number, n int) int {
return n + SizeTag(num)
}
// DecodeTag decodes the field Number and wire Type from its unified form.
// The Number is -1 if the decoded field number overflows int32.
// DecodeTag decodes the field [Number] and wire [Type] from its unified form.
// The [Number] is -1 if the decoded field number overflows int32.
// Other than overflow, this does not check for field number validity.
func DecodeTag(x uint64) (Number, Type) {
// NOTE: MessageSet allows for larger field numbers than normal.
@ -506,7 +506,7 @@ func DecodeTag(x uint64) (Number, Type) {
return Number(x >> 3), Type(x & 7)
}
// EncodeTag encodes the field Number and wire Type into its unified form.
// EncodeTag encodes the field [Number] and wire [Type] into its unified form.
func EncodeTag(num Number, typ Type) uint64 {
return uint64(num)<<3 | uint64(typ&7)
}

2
proto/decode.go
View File

@ -69,7 +69,7 @@ func (o UnmarshalOptions) Unmarshal(b []byte, m Message) error {
// UnmarshalState parses a wire-format message and places the result in m.
//
// This method permits fine-grained control over the unmarshaler.
// Most users should use Unmarshal instead.
// Most users should use [Unmarshal] instead.
func (o UnmarshalOptions) UnmarshalState(in protoiface.UnmarshalInput) (protoiface.UnmarshalOutput, error) {
if o.RecursionLimit == 0 {
o.RecursionLimit = protowire.DefaultRecursionLimit

58
proto/doc.go
View File

@ -18,27 +18,27 @@
// This package contains functions to convert to and from the wire format,
// an efficient binary serialization of protocol buffers.
//
// • Size reports the size of a message in the wire format.
// - [Size] reports the size of a message in the wire format.
//
// • Marshal converts a message to the wire format.
// The MarshalOptions type provides more control over wire marshaling.
// - [Marshal] converts a message to the wire format.
// The [MarshalOptions] type provides more control over wire marshaling.
//
// • Unmarshal converts a message from the wire format.
// The UnmarshalOptions type provides more control over wire unmarshaling.
// - [Unmarshal] converts a message from the wire format.
// The [UnmarshalOptions] type provides more control over wire unmarshaling.
//
// # Basic message operations
//
// • Clone makes a deep copy of a message.
// - [Clone] makes a deep copy of a message.
//
// • Merge merges the content of a message into another.
// - [Merge] merges the content of a message into another.
//
// • Equal compares two messages. For more control over comparisons
// and detailed reporting of differences, see package
// "google.golang.org/protobuf/testing/protocmp".
// - [Equal] compares two messages. For more control over comparisons
// and detailed reporting of differences, see package
// [google.golang.org/protobuf/testing/protocmp].
//
// • Reset clears the content of a message.
// - [Reset] clears the content of a message.
//
// • CheckInitialized reports whether all required fields in a message are set.
// - [CheckInitialized] reports whether all required fields in a message are set.
//
// # Optional scalar constructors
//
@ -46,9 +46,9 @@
// as pointers to a value. For example, an optional string field has the
// Go type *string.
//
// • Bool, Int32, Int64, Uint32, Uint64, Float32, Float64, and String
// take a value and return a pointer to a new instance of it,
// to simplify construction of optional field values.
// - [Bool], [Int32], [Int64], [Uint32], [Uint64], [Float32], [Float64], and [String]
// take a value and return a pointer to a new instance of it,
// to simplify construction of optional field values.
//
// Generated enum types usually have an Enum method which performs the
// same operation.
@ -57,29 +57,29 @@
//
// # Extension accessors
//
// • HasExtension, GetExtension, SetExtension, and ClearExtension
// access extension field values in a protocol buffer message.
// - [HasExtension], [GetExtension], [SetExtension], and [ClearExtension]
// access extension field values in a protocol buffer message.
//
// Extension fields are only supported in proto2.
//
// # Related packages
//
// • Package "google.golang.org/protobuf/encoding/protojson" converts messages to
// and from JSON.
// - Package [google.golang.org/protobuf/encoding/protojson] converts messages to
// and from JSON.
//
// • Package "google.golang.org/protobuf/encoding/prototext" converts messages to
// and from the text format.
// - Package [google.golang.org/protobuf/encoding/prototext] converts messages to
// and from the text format.
//
// • Package "google.golang.org/protobuf/reflect/protoreflect" provides a
// reflection interface for protocol buffer data types.
// - Package [google.golang.org/protobuf/reflect/protoreflect] provides a
// reflection interface for protocol buffer data types.
//
// • Package "google.golang.org/protobuf/testing/protocmp" provides features
// to compare protocol buffer messages with the "github.com/google/go-cmp/cmp"
// package.
// - Package [google.golang.org/protobuf/testing/protocmp] provides features
// to compare protocol buffer messages with the [github.com/google/go-cmp/cmp]
// package.
//
// • Package "google.golang.org/protobuf/types/dynamicpb" provides a dynamic
// message type, suitable for working with messages where the protocol buffer
// type is only known at runtime.
// - Package [google.golang.org/protobuf/types/dynamicpb] provides a dynamic
// message type, suitable for working with messages where the protocol buffer
// type is only known at runtime.
//
// This module contains additional packages for more specialized use cases.
// Consult the individual package documentation for details.

2
proto/encode.go
View File

@ -129,7 +129,7 @@ func (o MarshalOptions) MarshalAppend(b []byte, m Message) ([]byte, error) {
// MarshalState returns the wire-format encoding of a message.
//
// This method permits fine-grained control over the marshaler.
// Most users should use Marshal instead.
// Most users should use [Marshal] instead.
func (o MarshalOptions) MarshalState(in protoiface.MarshalInput) (protoiface.MarshalOutput, error) {
return o.marshal(in.Buf, in.Message)
}

2
proto/extension.go
View File

@ -26,7 +26,7 @@ func HasExtension(m Message, xt protoreflect.ExtensionType) bool {
}
// ClearExtension clears an extension field such that subsequent
// HasExtension calls return false.
// [HasExtension] calls return false.
// It panics if m is invalid or if xt does not extend m.
func ClearExtension(m Message, xt protoreflect.ExtensionType) {
m.ProtoReflect().Clear(xt.TypeDescriptor())

2
proto/merge.go
View File

@ -21,7 +21,7 @@ import (
// The unknown fields of src are appended to the unknown fields of dst.
//
// It is semantically equivalent to unmarshaling the encoded form of src
// into dst with the UnmarshalOptions.Merge option specified.
// into dst with the [UnmarshalOptions.Merge] option specified.
func Merge(dst, src Message) {
// TODO: Should nil src be treated as semantically equivalent to a
// untyped, read-only, empty message? What about a nil dst?

18
proto/proto.go
View File

@ -15,18 +15,20 @@ import (
// protobuf module that accept a Message, except where otherwise specified.
//
// This is the v2 interface definition for protobuf messages.
// The v1 interface definition is "github.com/golang/protobuf/proto".Message.
// The v1 interface definition is [github.com/golang/protobuf/proto.Message].
//
// To convert a v1 message to a v2 message,
// use "github.com/golang/protobuf/proto".MessageV2.
// To convert a v2 message to a v1 message,
// use "github.com/golang/protobuf/proto".MessageV1.
// - To convert a v1 message to a v2 message,
// use [google.golang.org/protobuf/protoadapt.MessageV2Of].
// - To convert a v2 message to a v1 message,
// use [google.golang.org/protobuf/protoadapt.MessageV1Of].
type Message = protoreflect.ProtoMessage
// Error matches all errors produced by packages in the protobuf module.
// Error matches all errors produced by packages in the protobuf module
// according to [errors.Is].
//
// That is, errors.Is(err, Error) reports whether an error is produced
// by this module.
// Example usage:
//
// if errors.Is(err, proto.Error) { ... }
var Error error
func init() {

10
protoadapt/convert.go
View File

@ -11,21 +11,21 @@ import (
"google.golang.org/protobuf/runtime/protoimpl"
)
// MessageV1 is the original "github.com/golang/protobuf/proto".Message type.
// MessageV1 is the original [github.com/golang/protobuf/proto.Message] type.
type MessageV1 = protoiface.MessageV1
// MessageV2 is the Message type used by the current google.golang.org/protobuf
// module, adding support for reflection.
// MessageV2 is the [google.golang.org/protobuf/proto.Message] type used by the
// current [google.golang.org/protobuf] module, adding support for reflection.
type MessageV2 = proto.Message
// MessageV1Of converts a v2 message to a v1 message.
// It returns nil if m is nil.
func MessageV1Of(m MessageV2) protoiface.MessageV1 {
func MessageV1Of(m MessageV2) MessageV1 {
return protoimpl.X.ProtoMessageV1Of(m)
}
// MessageV2Of converts a v1 message to a v2 message.
// It returns nil if m is nil.
func MessageV2Of(m MessageV1) proto.Message {
func MessageV2Of(m MessageV1) MessageV2 {
return protoimpl.X.ProtoMessageV2Of(m)
}

20
reflect/protodesc/desc.go
View File

@ -3,11 +3,11 @@
// license that can be found in the LICENSE file.
// Package protodesc provides functionality for converting
// FileDescriptorProto messages to/from protoreflect.FileDescriptor values.
// FileDescriptorProto messages to/from [protoreflect.FileDescriptor] values.
//
// The google.protobuf.FileDescriptorProto is a protobuf message that describes
// the type information for a .proto file in a form that is easily serializable.
// The protoreflect.FileDescriptor is a more structured representation of
// The [protoreflect.FileDescriptor] is a more structured representation of
// the FileDescriptorProto message where references and remote dependencies
// can be directly followed.
package protodesc
@ -24,11 +24,11 @@ import (
"google.golang.org/protobuf/types/descriptorpb"
)
// Resolver is the resolver used by NewFile to resolve dependencies.
// Resolver is the resolver used by [NewFile] to resolve dependencies.
// The enums and messages provided must belong to some parent file,
// which is also registered.
//
// It is implemented by protoregistry.Files.
// It is implemented by [protoregistry.Files].
type Resolver interface {
FindFileByPath(string) (protoreflect.FileDescriptor, error)
FindDescriptorByName(protoreflect.FullName) (protoreflect.Descriptor, error)
@ -61,19 +61,19 @@ type FileOptions struct {
AllowUnresolvable bool
}
// NewFile creates a new protoreflect.FileDescriptor from the provided
// file descriptor message. See FileOptions.New for more information.
// NewFile creates a new [protoreflect.FileDescriptor] from the provided
// file descriptor message. See [FileOptions.New] for more information.
func NewFile(fd *descriptorpb.FileDescriptorProto, r Resolver) (protoreflect.FileDescriptor, error) {
return FileOptions{}.New(fd, r)
}
// NewFiles creates a new protoregistry.Files from the provided
// FileDescriptorSet message. See FileOptions.NewFiles for more information.
// NewFiles creates a new [protoregistry.Files] from the provided
// FileDescriptorSet message. See [FileOptions.NewFiles] for more information.
func NewFiles(fd *descriptorpb.FileDescriptorSet) (*protoregistry.Files, error) {
return FileOptions{}.NewFiles(fd)
}
// New creates a new protoreflect.FileDescriptor from the provided
// New creates a new [protoreflect.FileDescriptor] from the provided
// file descriptor message. The file must represent a valid proto file according
// to protobuf semantics. The returned descriptor is a deep copy of the input.
//
@ -231,7 +231,7 @@ func (is importSet) importPublic(imps protoreflect.FileImports) {
}
}
// NewFiles creates a new protoregistry.Files from the provided
// NewFiles creates a new [protoregistry.Files] from the provided
// FileDescriptorSet message. The descriptor set must include only
// valid files according to protobuf semantics. The returned descriptors
// are a deep copy of the input.

16
reflect/protodesc/proto.go
View File

@ -16,7 +16,7 @@ import (
"google.golang.org/protobuf/types/descriptorpb"
)
// ToFileDescriptorProto copies a protoreflect.FileDescriptor into a
// ToFileDescriptorProto copies a [protoreflect.FileDescriptor] into a
// google.protobuf.FileDescriptorProto message.
func ToFileDescriptorProto(file protoreflect.FileDescriptor) *descriptorpb.FileDescriptorProto {
p := &descriptorpb.FileDescriptorProto{
@ -76,7 +76,7 @@ func ToFileDescriptorProto(file protoreflect.FileDescriptor) *descriptorpb.FileD
return p
}
// ToDescriptorProto copies a protoreflect.MessageDescriptor into a
// ToDescriptorProto copies a [protoreflect.MessageDescriptor] into a
// google.protobuf.DescriptorProto message.
func ToDescriptorProto(message protoreflect.MessageDescriptor) *descriptorpb.DescriptorProto {
p := &descriptorpb.DescriptorProto{
@ -119,7 +119,7 @@ func ToDescriptorProto(message protoreflect.MessageDescriptor) *descriptorpb.Des
return p
}
// ToFieldDescriptorProto copies a protoreflect.FieldDescriptor into a
// ToFieldDescriptorProto copies a [protoreflect.FieldDescriptor] into a
// google.protobuf.FieldDescriptorProto message.
func ToFieldDescriptorProto(field protoreflect.FieldDescriptor) *descriptorpb.FieldDescriptorProto {
p := &descriptorpb.FieldDescriptorProto{
@ -168,7 +168,7 @@ func ToFieldDescriptorProto(field protoreflect.FieldDescriptor) *descriptorpb.Fi
return p
}
// ToOneofDescriptorProto copies a protoreflect.OneofDescriptor into a
// ToOneofDescriptorProto copies a [protoreflect.OneofDescriptor] into a
// google.protobuf.OneofDescriptorProto message.
func ToOneofDescriptorProto(oneof protoreflect.OneofDescriptor) *descriptorpb.OneofDescriptorProto {
return &descriptorpb.OneofDescriptorProto{
@ -177,7 +177,7 @@ func ToOneofDescriptorProto(oneof protoreflect.OneofDescriptor) *descriptorpb.On
}
}
// ToEnumDescriptorProto copies a protoreflect.EnumDescriptor into a
// ToEnumDescriptorProto copies a [protoreflect.EnumDescriptor] into a
// google.protobuf.EnumDescriptorProto message.
func ToEnumDescriptorProto(enum protoreflect.EnumDescriptor) *descriptorpb.EnumDescriptorProto {
p := &descriptorpb.EnumDescriptorProto{
@ -200,7 +200,7 @@ func ToEnumDescriptorProto(enum protoreflect.EnumDescriptor) *descriptorpb.EnumD
return p
}
// ToEnumValueDescriptorProto copies a protoreflect.EnumValueDescriptor into a
// ToEnumValueDescriptorProto copies a [protoreflect.EnumValueDescriptor] into a
// google.protobuf.EnumValueDescriptorProto message.
func ToEnumValueDescriptorProto(value protoreflect.EnumValueDescriptor) *descriptorpb.EnumValueDescriptorProto {
return &descriptorpb.EnumValueDescriptorProto{
@ -210,7 +210,7 @@ func ToEnumValueDescriptorProto(value protoreflect.EnumValueDescriptor) *descrip
}
}
// ToServiceDescriptorProto copies a protoreflect.ServiceDescriptor into a
// ToServiceDescriptorProto copies a [protoreflect.ServiceDescriptor] into a
// google.protobuf.ServiceDescriptorProto message.
func ToServiceDescriptorProto(service protoreflect.ServiceDescriptor) *descriptorpb.ServiceDescriptorProto {
p := &descriptorpb.ServiceDescriptorProto{
@ -223,7 +223,7 @@ func ToServiceDescriptorProto(service protoreflect.ServiceDescriptor) *descripto
return p
}
// ToMethodDescriptorProto copies a protoreflect.MethodDescriptor into a
// ToMethodDescriptorProto copies a [protoreflect.MethodDescriptor] into a
// google.protobuf.MethodDescriptorProto message.
func ToMethodDescriptorProto(method protoreflect.MethodDescriptor) *descriptorpb.MethodDescriptorProto {
p := &descriptorpb.MethodDescriptorProto{

8
reflect/protopath/path.go
View File

@ -17,14 +17,14 @@ import (
// where you would like to "address" some value in a message with just the path
// and don't have the value information available.
//
// This is different from how "github.com/google/go-cmp/cmp".Path operates,
// This is different from how github.com/google/go-cmp/cmp.Path operates,
// which combines both path and value information together.
// Since the cmp package itself is the only one ever constructing a cmp.Path,
// it will always have the value available.
// Path is a sequence of protobuf reflection steps applied to some root
// protobuf message value to arrive at the current value.
// The first step must be a Root step.
// The first step must be a [Root] step.
type Path []Step
// TODO: Provide a Parse function that parses something similar to or
@ -55,8 +55,8 @@ func (p Path) String() string {
}
// Values is a Path paired with a sequence of values at each step.
// The lengths of Path and Values must be identical.
// The first step must be a Root step and
// The lengths of [Values.Path] and [Values.Values] must be identical.
// The first step must be a [Root] step and
// the first value must be a concrete message value.
type Values struct {
Path Path

44
reflect/protorange/range.go
View File

@ -30,7 +30,7 @@ var (
// Range performs a depth-first traversal over reachable values in a message.
//
// See Options.Range for details.
// See [Options.Range] for details.
func Range(m protoreflect.Message, f func(protopath.Values) error) error {
return Options{}.Range(m, f, nil)
}
@ -61,33 +61,33 @@ type Options struct {
}
// Range performs a depth-first traversal over reachable values in a message.
// The first push and the last pop are to push/pop a protopath.Root step.
// If push or pop return any non-nil error (other than Break or Terminate),
// The first push and the last pop are to push/pop a [protopath.Root] step.
// If push or pop return any non-nil error (other than [Break] or [Terminate]),
// it terminates the traversal and is returned by Range.
//
// The rules for traversing a message is as follows:
//
// • For messages, iterate over every populated known and extension field.
// Each field is preceded by a push of a protopath.FieldAccess step,
// followed by recursive application of the rules on the field value,
// and succeeded by a pop of that step.
// If the message has unknown fields, then push an protopath.UnknownAccess step
// followed immediately by pop of that step.
// - For messages, iterate over every populated known and extension field.
// Each field is preceded by a push of a [protopath.FieldAccess] step,
// followed by recursive application of the rules on the field value,
// and succeeded by a pop of that step.
// If the message has unknown fields, then push an [protopath.UnknownAccess] step
// followed immediately by pop of that step.
//
// • As an exception to the above rule, if the current message is a
// google.protobuf.Any message, expand the underlying message (if resolvable).
// The expanded message is preceded by a push of a protopath.AnyExpand step,
// followed by recursive application of the rules on the underlying message,
// and succeeded by a pop of that step. Mutations to the expanded message
// are written back to the Any message when popping back out.
// - As an exception to the above rule, if the current message is a
// google.protobuf.Any message, expand the underlying message (if resolvable).
// The expanded message is preceded by a push of a [protopath.AnyExpand] step,
// followed by recursive application of the rules on the underlying message,
// and succeeded by a pop of that step. Mutations to the expanded message
// are written back to the Any message when popping back out.
//
// • For lists, iterate over every element. Each element is preceded by a push
// of a protopath.ListIndex step, followed by recursive application of the rules
// on the list element, and succeeded by a pop of that step.
// - For lists, iterate over every element. Each element is preceded by a push
// of a [protopath.ListIndex] step, followed by recursive application of the rules
// on the list element, and succeeded by a pop of that step.
//
// • For maps, iterate over every entry. Each entry is preceded by a push
// of a protopath.MapIndex step, followed by recursive application of the rules
// on the map entry value, and succeeded by a pop of that step.
// - For maps, iterate over every entry. Each entry is preceded by a push
// of a [protopath.MapIndex] step, followed by recursive application of the rules
// on the map entry value, and succeeded by a pop of that step.
//
// Mutations should only be made to the last value, otherwise the effects on
// traversal will be undefined. If the mutation is made to the last value
@ -96,7 +96,7 @@ type Options struct {
// populates a few fields in that message, then the newly modified fields
// will be traversed.
//
// The protopath.Values provided to push functions is only valid until the
// The [protopath.Values] provided to push functions is only valid until the
// corresponding pop call and the values provided to a pop call is only valid
// for the duration of the pop call itself.
func (o Options) Range(m protoreflect.Message, push, pop func(protopath.Values) error) error {

78
reflect/protoreflect/proto.go
View File

@ -10,46 +10,46 @@
//
// # Protocol Buffer Descriptors
//
// Protobuf descriptors (e.g., EnumDescriptor or MessageDescriptor)
// Protobuf descriptors (e.g., [EnumDescriptor] or [MessageDescriptor])
// are immutable objects that represent protobuf type information.
// They are wrappers around the messages declared in descriptor.proto.
// Protobuf descriptors alone lack any information regarding Go types.
//
// Enums and messages generated by this module implement Enum and ProtoMessage,
// Enums and messages generated by this module implement [Enum] and [ProtoMessage],
// where the Descriptor and ProtoReflect.Descriptor accessors respectively
// return the protobuf descriptor for the values.
//
// The protobuf descriptor interfaces are not meant to be implemented by
// user code since they might need to be extended in the future to support
// additions to the protobuf language.
// The "google.golang.org/protobuf/reflect/protodesc" package converts between
// The [google.golang.org/protobuf/reflect/protodesc] package converts between
// google.protobuf.DescriptorProto messages and protobuf descriptors.
//
// # Go Type Descriptors
//
// A type descriptor (e.g., EnumType or MessageType) is a constructor for
// A type descriptor (e.g., [EnumType] or [MessageType]) is a constructor for
// a concrete Go type that represents the associated protobuf descriptor.
// There is commonly a one-to-one relationship between protobuf descriptors and
// Go type descriptors, but it can potentially be a one-to-many relationship.
//
// Enums and messages generated by this module implement Enum and ProtoMessage,
// Enums and messages generated by this module implement [Enum] and [ProtoMessage],
// where the Type and ProtoReflect.Type accessors respectively
// return the protobuf descriptor for the values.
//
// The "google.golang.org/protobuf/types/dynamicpb" package can be used to
// The [google.golang.org/protobuf/types/dynamicpb] package can be used to
// create Go type descriptors from protobuf descriptors.
//
// # Value Interfaces
//
// The Enum and Message interfaces provide a reflective view over an
// The [Enum] and [Message] interfaces provide a reflective view over an
// enum or message instance. For enums, it provides the ability to retrieve
// the enum value number for any concrete enum type. For messages, it provides
// the ability to access or manipulate fields of the message.
//
// To convert a proto.Message to a protoreflect.Message, use the
// To convert a [google.golang.org/protobuf/proto.Message] to a [protoreflect.Message], use the
// former's ProtoReflect method. Since the ProtoReflect method is new to the
// v2 message interface, it may not be present on older message implementations.
// The "github.com/golang/protobuf/proto".MessageReflect function can be used
// The [github.com/golang/protobuf/proto.MessageReflect] function can be used
// to obtain a reflective view on older messages.
//
// # Relationships
@ -71,12 +71,12 @@
// │ │
// └────────────────── Type() ───────┘
//
// • An EnumType describes a concrete Go enum type.
// • An [EnumType] describes a concrete Go enum type.
// It has an EnumDescriptor and can construct an Enum instance.
//
// • An EnumDescriptor describes an abstract protobuf enum type.
// • An [EnumDescriptor] describes an abstract protobuf enum type.
//
// • An Enum is a concrete enum instance. Generated enums implement Enum.
// • An [Enum] is a concrete enum instance. Generated enums implement Enum.
//
// ┌──────────────── New() ─────────────────┐
// │ │
@ -90,24 +90,26 @@
// │ │
// └─────────────────── Type() ─────────┘
//
// • A MessageType describes a concrete Go message type.
// It has a MessageDescriptor and can construct a Message instance.
// Just as how Go's reflect.Type is a reflective description of a Go type,
// a MessageType is a reflective description of a Go type for a protobuf message.
// • A [MessageType] describes a concrete Go message type.
// It has a [MessageDescriptor] and can construct a [Message] instance.
// Just as how Go's [reflect.Type] is a reflective description of a Go type,
// a [MessageType] is a reflective description of a Go type for a protobuf message.
//
// • A MessageDescriptor describes an abstract protobuf message type.
// It has no understanding of Go types. In order to construct a MessageType
// from just a MessageDescriptor, you can consider looking up the message type
// in the global registry using protoregistry.GlobalTypes.FindMessageByName
// or constructing a dynamic MessageType using dynamicpb.NewMessageType.
// • A [MessageDescriptor] describes an abstract protobuf message type.
// It has no understanding of Go types. In order to construct a [MessageType]
// from just a [MessageDescriptor], you can consider looking up the message type
// in the global registry using the FindMessageByName method on
// [google.golang.org/protobuf/reflect/protoregistry.GlobalTypes]
// or constructing a dynamic [MessageType] using
// [google.golang.org/protobuf/types/dynamicpb.NewMessageType].
//
// • A Message is a reflective view over a concrete message instance.
// Generated messages implement ProtoMessage, which can convert to a Message.
// Just as how Go's reflect.Value is a reflective view over a Go value,
// a Message is a reflective view over a concrete protobuf message instance.
// Using Go reflection as an analogy, the ProtoReflect method is similar to
// calling reflect.ValueOf, and the Message.Interface method is similar to
// calling reflect.Value.Interface.
// • A [Message] is a reflective view over a concrete message instance.
// Generated messages implement [ProtoMessage], which can convert to a [Message].
// Just as how Go's [reflect.Value] is a reflective view over a Go value,
// a [Message] is a reflective view over a concrete protobuf message instance.
// Using Go reflection as an analogy, the [ProtoMessage.ProtoReflect] method is similar to
// calling [reflect.ValueOf], and the [Message.Interface] method is similar to
// calling [reflect.Value.Interface].
//
// ┌── TypeDescriptor() ──┐ ┌───── Descriptor() ─────┐
// │ V │ V
@ -119,15 +121,15 @@
// │ │
// └────── implements ────────┘
//
// • An ExtensionType describes a concrete Go implementation of an extension.
// It has an ExtensionTypeDescriptor and can convert to/from
// abstract Values and Go values.
// • An [ExtensionType] describes a concrete Go implementation of an extension.
// It has an [ExtensionTypeDescriptor] and can convert to/from
// an abstract [Value] and a Go value.
//
// • An ExtensionTypeDescriptor is an ExtensionDescriptor
// which also has an ExtensionType.
// • An [ExtensionTypeDescriptor] is an [ExtensionDescriptor]
// which also has an [ExtensionType].
//
// • An ExtensionDescriptor describes an abstract protobuf extension field and
// may not always be an ExtensionTypeDescriptor.
// • An [ExtensionDescriptor] describes an abstract protobuf extension field and
// may not always be an [ExtensionTypeDescriptor].
package protoreflect
import (
@ -142,7 +144,7 @@ type doNotImplement pragma.DoNotImplement
// ProtoMessage is the top-level interface that all proto messages implement.
// This is declared in the protoreflect package to avoid a cyclic dependency;
// use the proto.Message type instead, which aliases this type.
// use the [google.golang.org/protobuf/proto.Message] type instead, which aliases this type.
type ProtoMessage interface{ ProtoReflect() Message }
// Syntax is the language version of the proto file.
@ -436,7 +438,7 @@ type Names interface {
// FullName is a qualified name that uniquely identifies a proto declaration.
// A qualified name is the concatenation of the proto package along with the
// fully-declared name (i.e., name of parent preceding the name of the child),
// with a '.' delimiter placed between each Name.
// with a '.' delimiter placed between each [Name].
//
// This should not have any leading or trailing dots.
type FullName string // e.g., "google.protobuf.Field.Kind"
@ -480,7 +482,7 @@ func isLetterDigit(c byte) bool {
}
// Name returns the short name, which is the last identifier segment.
// A single segment FullName is the Name itself.
// A single segment FullName is the [Name] itself.
func (n FullName) Name() Name {
if i := strings.LastIndexByte(string(n), '.'); i >= 0 {
return Name(n[i+1:])

44
reflect/protoreflect/type.go
View File

@ -12,7 +12,7 @@ package protoreflect
// exactly identical. However, it is possible for the same semantically
// identical proto type to be represented by multiple type descriptors.
//
// For example, suppose we have t1 and t2 which are both MessageDescriptors.
// For example, suppose we have t1 and t2 which are both an [MessageDescriptor].
// If t1 == t2, then the types are definitely equal and all accessors return
// the same information. However, if t1 != t2, then it is still possible that
// they still represent the same proto type (e.g., t1.FullName == t2.FullName).
@ -115,7 +115,7 @@ type Descriptor interface {
// corresponds with the google.protobuf.FileDescriptorProto message.
//
// Top-level declarations:
// EnumDescriptor, MessageDescriptor, FieldDescriptor, and/or ServiceDescriptor.
// [EnumDescriptor], [MessageDescriptor], [FieldDescriptor], and/or [ServiceDescriptor].
type FileDescriptor interface {
Descriptor // Descriptor.FullName is identical to Package
@ -180,8 +180,8 @@ type FileImport struct {
// corresponds with the google.protobuf.DescriptorProto message.
//
// Nested declarations:
// FieldDescriptor, OneofDescriptor, FieldDescriptor, EnumDescriptor,
// and/or MessageDescriptor.
// [FieldDescriptor], [OneofDescriptor], [FieldDescriptor], [EnumDescriptor],
// and/or [MessageDescriptor].
type MessageDescriptor interface {
Descriptor
@ -214,7 +214,7 @@ type MessageDescriptor interface {
ExtensionRanges() FieldRanges
// ExtensionRangeOptions returns the ith extension range options.
//
// To avoid a dependency cycle, this method returns a proto.Message value,
// To avoid a dependency cycle, this method returns a proto.Message] value,
// which always contains a google.protobuf.ExtensionRangeOptions message.
// This method returns a typed nil-pointer if no options are present.
// The caller must import the descriptorpb package to use this.
@ -231,9 +231,9 @@ type MessageDescriptor interface {
}
type isMessageDescriptor interface{ ProtoType(MessageDescriptor) }
// MessageType encapsulates a MessageDescriptor with a concrete Go implementation.
// MessageType encapsulates a [MessageDescriptor] with a concrete Go implementation.
// It is recommended that implementations of this interface also implement the
// MessageFieldTypes interface.
// [MessageFieldTypes] interface.
type MessageType interface {
// New returns a newly allocated empty message.
// It may return nil for synthetic messages representing a map entry.
@ -249,19 +249,19 @@ type MessageType interface {
Descriptor() MessageDescriptor
}
// MessageFieldTypes extends a MessageType by providing type information
// MessageFieldTypes extends a [MessageType] by providing type information
// regarding enums and messages referenced by the message fields.
type MessageFieldTypes interface {
MessageType
// Enum returns the EnumType for the ith field in Descriptor.Fields.
// Enum returns the EnumType for the ith field in MessageDescriptor.Fields.
// It returns nil if the ith field is not an enum kind.
// It panics if out of bounds.
//
// Invariant: mt.Enum(i).Descriptor() == mt.Descriptor().Fields(i).Enum()
Enum(i int) EnumType
// Message returns the MessageType for the ith field in Descriptor.Fields.
// Message returns the MessageType for the ith field in MessageDescriptor.Fields.
// It returns nil if the ith field is not a message or group kind.
// It panics if out of bounds.
//
@ -286,8 +286,8 @@ type MessageDescriptors interface {
// corresponds with the google.protobuf.FieldDescriptorProto message.
//
// It is used for both normal fields defined within the parent message
// (e.g., MessageDescriptor.Fields) and fields that extend some remote message
// (e.g., FileDescriptor.Extensions or MessageDescriptor.Extensions).
// (e.g., [MessageDescriptor.Fields]) and fields that extend some remote message
// (e.g., [FileDescriptor.Extensions] or [MessageDescriptor.Extensions]).
type FieldDescriptor interface {
Descriptor
@ -344,7 +344,7 @@ type FieldDescriptor interface {
// IsMap reports whether this field represents a map,
// where the value type for the associated field is a Map.
// It is equivalent to checking whether Cardinality is Repeated,
// that the Kind is MessageKind, and that Message.IsMapEntry reports true.
// that the Kind is MessageKind, and that MessageDescriptor.IsMapEntry reports true.
IsMap() bool
// MapKey returns the field descriptor for the key in the map entry.
@ -419,7 +419,7 @@ type OneofDescriptor interface {
// IsSynthetic reports whether this is a synthetic oneof created to support
// proto3 optional semantics. If true, Fields contains exactly one field
// with HasOptionalKeyword specified.
// with FieldDescriptor.HasOptionalKeyword specified.
IsSynthetic() bool
// Fields is a list of fields belonging to this oneof.
@ -442,10 +442,10 @@ type OneofDescriptors interface {
doNotImplement
}
// ExtensionDescriptor is an alias of FieldDescriptor for documentation.
// ExtensionDescriptor is an alias of [FieldDescriptor] for documentation.
type ExtensionDescriptor = FieldDescriptor
// ExtensionTypeDescriptor is an ExtensionDescriptor with an associated ExtensionType.
// ExtensionTypeDescriptor is an [ExtensionDescriptor] with an associated [ExtensionType].
type ExtensionTypeDescriptor interface {
ExtensionDescriptor
@ -470,12 +470,12 @@ type ExtensionDescriptors interface {
doNotImplement
}
// ExtensionType encapsulates an ExtensionDescriptor with a concrete
// ExtensionType encapsulates an [ExtensionDescriptor] with a concrete
// Go implementation. The nested field descriptor must be for a extension field.
//
// While a normal field is a member of the parent message that it is declared
// within (see Descriptor.Parent), an extension field is a member of some other
// target message (see ExtensionDescriptor.Extendee) and may have no
// within (see [Descriptor.Parent]), an extension field is a member of some other
// target message (see [FieldDescriptor.ContainingMessage]) and may have no
// relationship with the parent. However, the full name of an extension field is
// relative to the parent that it is declared within.
//
@ -532,7 +532,7 @@ type ExtensionType interface {
// corresponds with the google.protobuf.EnumDescriptorProto message.
//
// Nested declarations:
// EnumValueDescriptor.
// [EnumValueDescriptor].
type EnumDescriptor interface {
Descriptor
@ -548,7 +548,7 @@ type EnumDescriptor interface {
}
type isEnumDescriptor interface{ ProtoType(EnumDescriptor) }
// EnumType encapsulates an EnumDescriptor with a concrete Go implementation.
// EnumType encapsulates an [EnumDescriptor] with a concrete Go implementation.
type EnumType interface {
// New returns an instance of this enum type with its value set to n.
New(n EnumNumber) Enum
@ -610,7 +610,7 @@ type EnumValueDescriptors interface {
// ServiceDescriptor describes a service and
// corresponds with the google.protobuf.ServiceDescriptorProto message.
//
// Nested declarations: MethodDescriptor.
// Nested declarations: [MethodDescriptor].
type ServiceDescriptor interface {
Descriptor

24
reflect/protoreflect/value.go
View File

@ -27,16 +27,16 @@ type Enum interface {
// Message is a reflective interface for a concrete message value,
// encapsulating both type and value information for the message.
//
// Accessor/mutators for individual fields are keyed by FieldDescriptor.
// Accessor/mutators for individual fields are keyed by [FieldDescriptor].
// For non-extension fields, the descriptor must exactly match the
// field known by the parent message.
// For extension fields, the descriptor must implement ExtensionTypeDescriptor,
// extend the parent message (i.e., have the same message FullName), and
// For extension fields, the descriptor must implement [ExtensionTypeDescriptor],
// extend the parent message (i.e., have the same message [FullName]), and
// be within the parent's extension range.
//
// Each field Value can be a scalar or a composite type (Message, List, or Map).
// See Value for the Go types associated with a FieldDescriptor.
// Providing a Value that is invalid or of an incorrect type panics.
// Each field [Value] can be a scalar or a composite type ([Message], [List], or [Map]).
// See [Value] for the Go types associated with a [FieldDescriptor].
// Providing a [Value] that is invalid or of an incorrect type panics.
type Message interface {
// Descriptor returns message descriptor, which contains only the protobuf
// type information for the message.
@ -152,7 +152,7 @@ type Message interface {
// This method may return nil.
//
// The returned methods type is identical to
// "google.golang.org/protobuf/runtime/protoiface".Methods.
// google.golang.org/protobuf/runtime/protoiface.Methods.
// Consult the protoiface package documentation for details.
ProtoMethods() *methods
}
@ -175,8 +175,8 @@ func (b RawFields) IsValid() bool {
}
// List is a zero-indexed, ordered list.
// The element Value type is determined by FieldDescriptor.Kind.
// Providing a Value that is invalid or of an incorrect type panics.
// The element [Value] type is determined by [FieldDescriptor.Kind].
// Providing a [Value] that is invalid or of an incorrect type panics.
type List interface {
// Len reports the number of entries in the List.
// Get, Set, and Truncate panic with out of bound indexes.
@ -226,9 +226,9 @@ type List interface {
}
// Map is an unordered, associative map.
// The entry MapKey type is determined by FieldDescriptor.MapKey.Kind.
// The entry Value type is determined by FieldDescriptor.MapValue.Kind.
// Providing a MapKey or Value that is invalid or of an incorrect type panics.
// The entry [MapKey] type is determined by [FieldDescriptor.MapKey].Kind.
// The entry [Value] type is determined by [FieldDescriptor.MapValue].Kind.
// Providing a [MapKey] or [Value] that is invalid or of an incorrect type panics.
type Map interface {
// Len reports the number of elements in the map.
Len() int

8
reflect/protoreflect/value_equal.go
View File

@ -24,19 +24,19 @@ import (
// Unlike the == operator, a NaN is equal to another NaN.
//
// - Enums are equal if they contain the same number.
// Since Value does not contain an enum descriptor,
// Since [Value] does not contain an enum descriptor,
// enum values do not consider the type of the enum.
//
// - Other scalar values are equal if they contain the same value.
//
// - Message values are equal if they belong to the same message descriptor,
// - [Message] values are equal if they belong to the same message descriptor,
// have the same set of populated known and extension field values,
// and the same set of unknown fields values.
//
// - Lists are equal if they are the same length and
// - [List] values are equal if they are the same length and
// each corresponding element is equal.
//
// - Maps are equal if they have the same set of keys and
// - [Map] values are equal if they have the same set of keys and
// the corresponding value for each key is equal.
func (v1 Value) Equal(v2 Value) bool {
return equalValue(v1, v2)

44
reflect/protoreflect/value_union.go
View File

@ -11,7 +11,7 @@ import (
// Value is a union where only one Go type may be set at a time.
// The Value is used to represent all possible values a field may take.
// The following shows which Go type is used to represent each proto Kind:
// The following shows which Go type is used to represent each proto [Kind]:
//
// ╔════════════╤═════════════════════════════════════╗
// ║ Go type │ Protobuf kind ║
@ -31,22 +31,22 @@ import (
//
// Multiple protobuf Kinds may be represented by a single Go type if the type
// can losslessly represent the information for the proto kind. For example,
// Int64Kind, Sint64Kind, and Sfixed64Kind are all represented by int64,
// [Int64Kind], [Sint64Kind], and [Sfixed64Kind] are all represented by int64,
// but use different integer encoding methods.
//
// The List or Map types are used if the field cardinality is repeated.
// A field is a List if FieldDescriptor.IsList reports true.
// A field is a Map if FieldDescriptor.IsMap reports true.
// The [List] or [Map] types are used if the field cardinality is repeated.
// A field is a [List] if [FieldDescriptor.IsList] reports true.
// A field is a [Map] if [FieldDescriptor.IsMap] reports true.
//
// Converting to/from a Value and a concrete Go value panics on type mismatch.
// For example, ValueOf("hello").Int() panics because this attempts to
// For example, [ValueOf]("hello").Int() panics because this attempts to
// retrieve an int64 from a string.
//
// List, Map, and Message Values are called "composite" values.
// [List], [Map], and [Message] Values are called "composite" values.
//
// A composite Value may alias (reference) memory at some location,
// such that changes to the Value updates the that location.
// A composite value acquired with a Mutable method, such as Message.Mutable,
// A composite value acquired with a Mutable method, such as [Message.Mutable],
// always references the source object.
//
// For example:
@ -65,7 +65,7 @@ import (
// // appending to the List here may or may not modify the message.
// list.Append(protoreflect.ValueOfInt32(0))
//
// Some operations, such as Message.Get, may return an "empty, read-only"
// Some operations, such as [Message.Get], may return an "empty, read-only"
// composite Value. Modifying an empty, read-only value panics.
type Value value
@ -306,7 +306,7 @@ func (v Value) Float() float64 {
}
}
// String returns v as a string. Since this method implements fmt.Stringer,
// String returns v as a string. Since this method implements [fmt.Stringer],
// this returns the formatted string value for any non-string type.
func (v Value) String() string {
switch v.typ {
@ -327,7 +327,7 @@ func (v Value) Bytes() []byte {
}
}
// Enum returns v as a EnumNumber and panics if the type is not a EnumNumber.
// Enum returns v as a [EnumNumber] and panics if the type is not a [EnumNumber].
func (v Value) Enum() EnumNumber {
switch v.typ {
case enumType:
@ -337,7 +337,7 @@ func (v Value) Enum() EnumNumber {
}
}
// Message returns v as a Message and panics if the type is not a Message.
// Message returns v as a [Message] and panics if the type is not a [Message].
func (v Value) Message() Message {
switch vi := v.getIface().(type) {
case Message:
@ -347,7 +347,7 @@ func (v Value) Message() Message {
}
}
// List returns v as a List and panics if the type is not a List.
// List returns v as a [List] and panics if the type is not a [List].
func (v Value) List() List {
switch vi := v.getIface().(type) {
case List:
@ -357,7 +357,7 @@ func (v Value) List() List {
}
}
// Map returns v as a Map and panics if the type is not a Map.
// Map returns v as a [Map] and panics if the type is not a [Map].
func (v Value) Map() Map {
switch vi := v.getIface().(type) {
case Map:
@ -367,7 +367,7 @@ func (v Value) Map() Map {
}
}
// MapKey returns v as a MapKey and panics for invalid MapKey types.
// MapKey returns v as a [MapKey] and panics for invalid [MapKey] types.
func (v Value) MapKey() MapKey {
switch v.typ {
case boolType, int32Type, int64Type, uint32Type, uint64Type, stringType:
@ -378,8 +378,8 @@ func (v Value) MapKey() MapKey {
}
// MapKey is used to index maps, where the Go type of the MapKey must match
// the specified key Kind (see MessageDescriptor.IsMapEntry).
// The following shows what Go type is used to represent each proto Kind:
// the specified key [Kind] (see [MessageDescriptor.IsMapEntry]).
// The following shows what Go type is used to represent each proto [Kind]:
//
// ╔═════════╤═════════════════════════════════════╗
// ║ Go type │ Protobuf kind ║
@ -392,13 +392,13 @@ func (v Value) MapKey() MapKey {
// ║ string │ StringKind ║
// ╚═════════╧═════════════════════════════════════╝
//
// A MapKey is constructed and accessed through a Value:
// A MapKey is constructed and accessed through a [Value]:
//
// k := ValueOf("hash").MapKey() // convert string to MapKey
// s := k.String() // convert MapKey to string
//
// The MapKey is a strict subset of valid types used in Value;
// converting a Value to a MapKey with an invalid type panics.
// The MapKey is a strict subset of valid types used in [Value];
// converting a [Value] to a MapKey with an invalid type panics.
type MapKey value
// IsValid reports whether k is populated with a value.
@ -426,13 +426,13 @@ func (k MapKey) Uint() uint64 {
return Value(k).Uint()
}
// String returns k as a string. Since this method implements fmt.Stringer,
// String returns k as a string. Since this method implements [fmt.Stringer],
// this returns the formatted string value for any non-string type.
func (k MapKey) String() string {
return Value(k).String()
}
// Value returns k as a Value.
// Value returns k as a [Value].
func (k MapKey) Value() Value {
return Value(k)
}

24
reflect/protoregistry/registry.go
View File

@ -5,12 +5,12 @@
// Package protoregistry provides data structures to register and lookup
// protobuf descriptor types.
//
// The Files registry contains file descriptors and provides the ability
// The [Files] registry contains file descriptors and provides the ability
// to iterate over the files or lookup a specific descriptor within the files.
// Files only contains protobuf descriptors and has no understanding of Go
// [Files] only contains protobuf descriptors and has no understanding of Go
// type information that may be associated with each descriptor.
//
// The Types registry contains descriptor types for which there is a known
// The [Types] registry contains descriptor types for which there is a known
// Go type associated with that descriptor. It provides the ability to iterate
// over the registered types or lookup a type by name.
package protoregistry
@ -218,7 +218,7 @@ func (r *Files) checkGenProtoConflict(path string) {
// FindDescriptorByName looks up a descriptor by the full name.
//
// This returns (nil, NotFound) if not found.
// This returns (nil, [NotFound]) if not found.
func (r *Files) FindDescriptorByName(name protoreflect.FullName) (protoreflect.Descriptor, error) {
if r == nil {
return nil, NotFound
@ -310,7 +310,7 @@ func (s *nameSuffix) Pop() (name protoreflect.Name) {
// FindFileByPath looks up a file by the path.
//
// This returns (nil, NotFound) if not found.
// This returns (nil, [NotFound]) if not found.
// This returns an error if multiple files have the same path.
func (r *Files) FindFileByPath(path string) (protoreflect.FileDescriptor, error) {
if r == nil {
@ -431,7 +431,7 @@ func rangeTopLevelDescriptors(fd protoreflect.FileDescriptor, f func(protoreflec
// A compliant implementation must deterministically return the same type
// if no error is encountered.
//
// The Types type implements this interface.
// The [Types] type implements this interface.
type MessageTypeResolver interface {
// FindMessageByName looks up a message by its full name.
// E.g., "google.protobuf.Any"
@ -451,7 +451,7 @@ type MessageTypeResolver interface {
// A compliant implementation must deterministically return the same type
// if no error is encountered.
//
// The Types type implements this interface.
// The [Types] type implements this interface.
type ExtensionTypeResolver interface {
// FindExtensionByName looks up a extension field by the field's full name.
// Note that this is the full name of the field as determined by
@ -590,7 +590,7 @@ func (r *Types) register(kind string, desc protoreflect.Descriptor, typ interfac
// FindEnumByName looks up an enum by its full name.
// E.g., "google.protobuf.Field.Kind".
//
// This returns (nil, NotFound) if not found.
// This returns (nil, [NotFound]) if not found.
func (r *Types) FindEnumByName(enum protoreflect.FullName) (protoreflect.EnumType, error) {
if r == nil {
return nil, NotFound
@ -611,7 +611,7 @@ func (r *Types) FindEnumByName(enum protoreflect.FullName) (protoreflect.EnumTyp
// FindMessageByName looks up a message by its full name,
// e.g. "google.protobuf.Any".
//
// This returns (nil, NotFound) if not found.
// This returns (nil, [NotFound]) if not found.
func (r *Types) FindMessageByName(message protoreflect.FullName) (protoreflect.MessageType, error) {
if r == nil {
return nil, NotFound
@ -632,7 +632,7 @@ func (r *Types) FindMessageByName(message protoreflect.FullName) (protoreflect.M
// FindMessageByURL looks up a message by a URL identifier.
// See documentation on google.protobuf.Any.type_url for the URL format.
//
// This returns (nil, NotFound) if not found.
// This returns (nil, [NotFound]) if not found.
func (r *Types) FindMessageByURL(url string) (protoreflect.MessageType, error) {
// This function is similar to FindMessageByName but
// truncates anything before and including '/' in the URL.
@ -662,7 +662,7 @@ func (r *Types) FindMessageByURL(url string) (protoreflect.MessageType, error) {
// where the extension is declared and is unrelated to the full name of the
// message being extended.
//
// This returns (nil, NotFound) if not found.
// This returns (nil, [NotFound]) if not found.
func (r *Types) FindExtensionByName(field protoreflect.FullName) (protoreflect.ExtensionType, error) {
if r == nil {
return nil, NotFound
@ -703,7 +703,7 @@ func (r *Types) FindExtensionByName(field protoreflect.FullName) (protoreflect.E
// FindExtensionByNumber looks up a extension field by the field number
// within some parent message, identified by full name.
//
// This returns (nil, NotFound) if not found.
// This returns (nil, [NotFound]) if not found.
func (r *Types) FindExtensionByNumber(message protoreflect.FullName, field protoreflect.FieldNumber) (protoreflect.ExtensionType, error) {
if r == nil {
return nil, NotFound

90
testing/protocmp/util.go
View File

@ -23,34 +23,34 @@ var (
messageReflectType = reflect.TypeOf(Message{})
)
// FilterEnum filters opt to only be applicable on standalone Enums,
// FilterEnum filters opt to only be applicable on a standalone [Enum],
// singular fields of enums, list fields of enums, or map fields of enum values,
// where the enum is the same type as the specified enum.
//
// The Go type of the last path step may be an:
// - Enum for singular fields, elements of a repeated field,
// values of a map field, or standalone Enums
// - []Enum for list fields
// - map[K]Enum for map fields
// - interface{} for a Message map entry value
// - [Enum] for singular fields, elements of a repeated field,
// values of a map field, or standalone [Enum] values
// - [][Enum] for list fields
// - map[K][Enum] for map fields
// - interface{} for a [Message] map entry value
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func FilterEnum(enum protoreflect.Enum, opt cmp.Option) cmp.Option {
return FilterDescriptor(enum.Descriptor(), opt)
}
// FilterMessage filters opt to only be applicable on standalone Messages,
// FilterMessage filters opt to only be applicable on a standalone [Message] values,
// singular fields of messages, list fields of messages, or map fields of
// message values, where the message is the same type as the specified message.
//
// The Go type of the last path step may be an:
// - Message for singular fields, elements of a repeated field,
// values of a map field, or standalone Messages
// - []Message for list fields
// - map[K]Message for map fields
// - interface{} for a Message map entry value
// - [Message] for singular fields, elements of a repeated field,
// values of a map field, or standalone [Message] values
// - [][Message] for list fields
// - map[K][Message] for map fields
// - interface{} for a [Message] map entry value
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func FilterMessage(message proto.Message, opt cmp.Option) cmp.Option {
return FilterDescriptor(message.ProtoReflect().Descriptor(), opt)
}
@ -62,9 +62,9 @@ func FilterMessage(message proto.Message, opt cmp.Option) cmp.Option {
// - T for singular fields
// - []T for list fields
// - map[K]T for map fields
// - interface{} for a Message map entry value
// - interface{} for a [Message] map entry value
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func FilterField(message proto.Message, name protoreflect.Name, opt cmp.Option) cmp.Option {
md := message.ProtoReflect().Descriptor()
return FilterDescriptor(mustFindFieldDescriptor(md, name), opt)
@ -78,9 +78,9 @@ func FilterField(message proto.Message, name protoreflect.Name, opt cmp.Option)
// - T for singular fields
// - []T for list fields
// - map[K]T for map fields
// - interface{} for a Message map entry value
// - interface{} for a [Message] map entry value
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func FilterOneof(message proto.Message, name protoreflect.Name, opt cmp.Option) cmp.Option {
md := message.ProtoReflect().Descriptor()
return FilterDescriptor(mustFindOneofDescriptor(md, name), opt)
@ -89,17 +89,17 @@ func FilterOneof(message proto.Message, name protoreflect.Name, opt cmp.Option)
// FilterDescriptor ignores the specified descriptor.
//
// The following descriptor types may be specified:
// - protoreflect.EnumDescriptor
// - protoreflect.MessageDescriptor
// - protoreflect.FieldDescriptor
// - protoreflect.OneofDescriptor
// - [protoreflect.EnumDescriptor]
// - [protoreflect.MessageDescriptor]
// - [protoreflect.FieldDescriptor]
// - [protoreflect.OneofDescriptor]
//
// For the behavior of each, see the corresponding filter function.
// Since this filter accepts a protoreflect.FieldDescriptor, it can be used
// to also filter for extension fields as a protoreflect.ExtensionDescriptor
// is just an alias to protoreflect.FieldDescriptor.
// Since this filter accepts a [protoreflect.FieldDescriptor], it can be used
// to also filter for extension fields as a [protoreflect.ExtensionDescriptor]
// is just an alias to [protoreflect.FieldDescriptor].
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func FilterDescriptor(desc protoreflect.Descriptor, opt cmp.Option) cmp.Option {
f := newNameFilters(desc)
return cmp.FilterPath(f.Filter, opt)
@ -108,7 +108,7 @@ func FilterDescriptor(desc protoreflect.Descriptor, opt cmp.Option) cmp.Option {
// IgnoreEnums ignores all enums of the specified types.
// It is equivalent to FilterEnum(enum, cmp.Ignore()) for each enum.
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func IgnoreEnums(enums ...protoreflect.Enum) cmp.Option {
var ds []protoreflect.Descriptor
for _, e := range enums {
@ -118,9 +118,9 @@ func IgnoreEnums(enums ...protoreflect.Enum) cmp.Option {
}
// IgnoreMessages ignores all messages of the specified types.
// It is equivalent to FilterMessage(message, cmp.Ignore()) for each message.
// It is equivalent to [FilterMessage](message, [cmp.Ignore]()) for each message.
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func IgnoreMessages(messages ...proto.Message) cmp.Option {
var ds []protoreflect.Descriptor
for _, m := range messages {
@ -130,10 +130,10 @@ func IgnoreMessages(messages ...proto.Message) cmp.Option {
}
// IgnoreFields ignores the specified fields in the specified message.
// It is equivalent to FilterField(message, name, cmp.Ignore()) for each field
// It is equivalent to [FilterField](message, name, [cmp.Ignore]()) for each field
// in the message.
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func IgnoreFields(message proto.Message, names ...protoreflect.Name) cmp.Option {
var ds []protoreflect.Descriptor
md := message.ProtoReflect().Descriptor()
@ -147,7 +147,7 @@ func IgnoreFields(message proto.Message, names ...protoreflect.Name) cmp.Option
// It is equivalent to FilterOneof(message, name, cmp.Ignore()) for each oneof
// in the message.
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func IgnoreOneofs(message proto.Message, names ...protoreflect.Name) cmp.Option {
var ds []protoreflect.Descriptor
md := message.ProtoReflect().Descriptor()
@ -158,9 +158,9 @@ func IgnoreOneofs(message proto.Message, names ...protoreflect.Name) cmp.Option
}
// IgnoreDescriptors ignores the specified set of descriptors.
// It is equivalent to FilterDescriptor(desc, cmp.Ignore()) for each descriptor.
// It is equivalent to [FilterDescriptor](desc, [cmp.Ignore]()) for each descriptor.
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func IgnoreDescriptors(descs ...protoreflect.Descriptor) cmp.Option {
return cmp.FilterPath(newNameFilters(descs...).Filter, cmp.Ignore())
}
@ -348,7 +348,7 @@ func (f *nameFilters) filterValue(v reflect.Value) bool {
// explicitly set to the default value.
// This option does not effect elements in a list or entries in a map.
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func IgnoreDefaultScalars() cmp.Option {
return cmp.FilterPath(func(p cmp.Path) bool {
// Filter for Message maps.
@ -408,10 +408,10 @@ func equalFloat64(x, y float64) bool {
}
// IgnoreEmptyMessages ignores messages that are empty or unpopulated.
// It applies to standalone Messages, singular message fields,
// It applies to standalone [Message] values, singular message fields,
// list fields of messages, and map fields of message values.
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func IgnoreEmptyMessages() cmp.Option {
return cmp.FilterPath(func(p cmp.Path) bool {
vx, vy := p.Last().Values()
@ -490,7 +490,7 @@ func isEmptyMessage(v reflect.Value) bool {
// IgnoreUnknown ignores unknown fields in all messages.
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func IgnoreUnknown() cmp.Option {
return cmp.FilterPath(func(p cmp.Path) bool {
// Filter for Message maps.
@ -515,16 +515,16 @@ func IgnoreUnknown() cmp.Option {
// The element type T can be one of the following:
// - Go type for a protobuf scalar kind except for an enum
// (i.e., bool, int32, int64, uint32, uint64, float32, float64, string, and []byte)
// - E where E is a concrete enum type that implements protoreflect.Enum
// - M where M is a concrete message type that implement proto.Message
// - E where E is a concrete enum type that implements [protoreflect.Enum]
// - M where M is a concrete message type that implement [proto.Message]
//
// This option only applies to repeated fields within a protobuf message.
// It does not operate on higher-order Go types that seem like a repeated field.
// For example, a []T outside the context of a protobuf message will not be
// handled by this option. To sort Go slices that are not repeated fields,
// consider using "github.com/google/go-cmp/cmp/cmpopts".SortSlices instead.
// consider using [github.com/google/go-cmp/cmp/cmpopts.SortSlices] instead.
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func SortRepeated(lessFunc interface{}) cmp.Option {
t, ok := checkTTBFunc(lessFunc)
if !ok {
@ -613,8 +613,8 @@ func checkTTBFunc(lessFunc interface{}) (reflect.Type, bool) {
// - Floating-point numbers are sorted in ascending order according to
// the total ordering defined by IEEE-754 (section 5.10).
// - Strings and bytes are sorted lexicographically in ascending order.
// - Enums are sorted in ascending order based on its numeric value.
// - Messages are sorted according to some arbitrary ordering
// - [Enum] values are sorted in ascending order based on its numeric value.
// - [Message] values are sorted according to some arbitrary ordering
// which is undefined and may change in future implementations.
//
// The ordering chosen for repeated messages is unlikely to be aesthetically
@ -624,7 +624,7 @@ func checkTTBFunc(lessFunc interface{}) (reflect.Type, bool) {
// ... // user-provided definition for less
// }))
//
// This must be used in conjunction with Transform.
// This must be used in conjunction with [Transform].
func SortRepeatedFields(message proto.Message, names ...protoreflect.Name) cmp.Option {
var opts cmp.Options
md := message.ProtoReflect().Descriptor()

26
testing/protocmp/xform.go
View File

@ -3,11 +3,11 @@
// license that can be found in the LICENSE file.
// Package protocmp provides protobuf specific options for the
// "github.com/google/go-cmp/cmp" package.
// [github.com/google/go-cmp/cmp] package.
//
// The primary feature is the Transform option, which transform proto.Message
// types into a Message map that is suitable for cmp to introspect upon.
// All other options in this package must be used in conjunction with Transform.
// The primary feature is the [Transform] option, which transform [proto.Message]
// types into a [Message] map that is suitable for cmp to introspect upon.
// All other options in this package must be used in conjunction with [Transform].
package protocmp
import (
@ -33,7 +33,7 @@ var (
)
// Enum is a dynamic representation of a protocol buffer enum that is
// suitable for cmp.Equal and cmp.Diff to compare upon.
// suitable for [cmp.Equal] and [cmp.Diff] to compare upon.
type Enum struct {
num protoreflect.EnumNumber
ed protoreflect.EnumDescriptor
@ -94,15 +94,15 @@ func (t1 messageMeta) Equal(t2 messageMeta) bool {
}
// Message is a dynamic representation of a protocol buffer message that is
// suitable for cmp.Equal and cmp.Diff to directly operate upon.
// suitable for [cmp.Equal] and [cmp.Diff] to directly operate upon.
//
// Every populated known field (excluding extension fields) is stored in the map
// with the key being the short name of the field (e.g., "field_name") and
// the value determined by the kind and cardinality of the field.
//
// Singular scalars are represented by the same Go type as protoreflect.Value,
// singular messages are represented by the Message type,
// singular enums are represented by the Enum type,
// Singular scalars are represented by the same Go type as [protoreflect.Value],
// singular messages are represented by the [Message] type,
// singular enums are represented by the [Enum] type,
// list fields are represented as a Go slice, and
// map fields are represented as a Go map.
//
@ -112,7 +112,7 @@ func (t1 messageMeta) Equal(t2 messageMeta) bool {
//
// Every unknown field is stored in the map with the key being the field number
// encoded as a decimal string (e.g., "132") and the value being the raw bytes
// of the encoded field (as the protoreflect.RawFields type).
// of the encoded field (as the [protoreflect.RawFields] type).
//
// Message values must not be created by or mutated by users.
type Message map[string]interface{}
@ -132,7 +132,7 @@ func (m Message) Descriptor() protoreflect.MessageDescriptor {
}
// ProtoReflect returns a reflective view of m.
// It only implements the read-only operations of protoreflect.Message.
// It only implements the read-only operations of [protoreflect.Message].
// Calling any mutating operations on m panics.
func (m Message) ProtoReflect() protoreflect.Message {
return (reflectMessage)(m)
@ -162,11 +162,11 @@ func (m Message) String() string {
type option struct{}
// Transform returns a cmp.Option that converts each proto.Message to a Message.
// Transform returns a [cmp.Option] that converts each [proto.Message] to a [Message].
// The transformation does not mutate nor alias any converted messages.
//
// The google.protobuf.Any message is automatically unmarshaled such that the
// "value" field is a Message representing the underlying message value
// "value" field is a [Message] representing the underlying message value
// assuming it could be resolved and properly unmarshaled.
//
// This does not directly transform higher-order composite Go types.

50
testing/protopack/pack.go
View File

@ -25,10 +25,10 @@ import (
"google.golang.org/protobuf/reflect/protoreflect"
)
// Number is the field number; aliased from the protowire package for convenience.
// Number is the field number; aliased from the [protowire] package for convenience.
type Number = protowire.Number
// Number type constants; copied from the protowire package for convenience.
// Number type constants; copied from the [protowire] package for convenience.
const (
MinValidNumber Number = protowire.MinValidNumber
FirstReservedNumber Number = protowire.FirstReservedNumber
@ -36,10 +36,10 @@ const (
MaxValidNumber Number = protowire.MaxValidNumber
)
// Type is the wire type; aliased from the protowire package for convenience.
// Type is the wire type; aliased from the [protowire] package for convenience.
type Type = protowire.Type
// Wire type constants; copied from the protowire package for convenience.
// Wire type constants; copied from the [protowire] package for convenience.
const (
VarintType Type = protowire.VarintType
Fixed32Type Type = protowire.Fixed32Type
@ -50,9 +50,9 @@ const (
)
type (
// Token is any other type (e.g., Message, Tag, Varint, Float32, etc).
// Token is any other type (e.g., [Message], [Tag], [Varint], [Float32], etc).
Token token
// Message is an ordered sequence of Tokens, where certain tokens may
// Message is an ordered sequence of [Token] values, where certain tokens may
// contain other tokens. It is functionally a concrete syntax tree that
// losslessly represents any arbitrary wire data (including invalid input).
Message []Token
@ -96,10 +96,10 @@ type (
// using more bytes than is strictly necessary. The number of extra bytes
// alone is sufficient to losslessly represent the denormalized varint.
//
// The value may be one of Tag, Bool, Varint, Svarint, or Uvarint,
// The value may be one of [Tag], [Bool], [Varint], [Svarint], or [Uvarint],
// where the varint representation of each token is denormalized.
//
// Alternatively, the value may be one of String, Bytes, or LengthPrefix,
// Alternatively, the value may be one of [String], [Bytes], or [LengthPrefix],
// where the varint representation of the length-prefix is denormalized.
Denormalized struct {
Count uint // number of extra bytes
@ -249,21 +249,21 @@ func (m Message) Marshal() []byte {
// Unmarshal parses the input protobuf wire data as a syntax tree.
// Any parsing error results in the remainder of the input being
// concatenated to the message as a Raw type.
// concatenated to the message as a [Raw] type.
//
// Each tag (a tuple of the field number and wire type) encountered is
// inserted into the syntax tree as a Tag.
// inserted into the syntax tree as a [Tag].
//
// The contents of each wire type is mapped to the following Go types:
//
// VarintType => Uvarint
// Fixed32Type => Uint32
// Fixed64Type => Uint64
// BytesType => Bytes
// GroupType => Message
// - [VarintType] ⇒ [Uvarint]
// - [Fixed32Type] ⇒ [Uint32]
// - [Fixed64Type] ⇒ [Uint64]
// - [BytesType] ⇒ [Bytes]
// - [StartGroupType] and [StartGroupType] ⇒ [Message]
//
// Since the wire format is not self-describing, this function cannot parse
// sub-messages and will leave them as the Bytes type. Further manual parsing
// sub-messages and will leave them as the [Bytes] type. Further manual parsing
// can be performed as such:
//
// var m, m1, m2 Message
@ -280,25 +280,25 @@ func (m *Message) Unmarshal(in []byte) {
// UnmarshalDescriptor parses the input protobuf wire data as a syntax tree
// using the provided message descriptor for more accurate parsing of fields.
// It operates like Unmarshal, but may use a wider range of Go types to
// It operates like [Message.Unmarshal], but may use a wider range of Go types to
// represent the wire data.
//
// The contents of each wire type is mapped to one of the following Go types:
//
// VarintType => Bool, Varint, Svarint, Uvarint
// Fixed32Type => Int32, Uint32, Float32
// Fixed64Type => Uint32, Uint64, Float64
// BytesType => String, Bytes, LengthPrefix
// GroupType => Message
// - [VarintType] ⇒ [Bool], [Varint], [Svarint], [Uvarint]
// - [Fixed32Type] ⇒ [Int32], [Uint32], [Float32]
// - [Fixed64Type] ⇒ [Uint32], [Uint64], [Float64]
// - [BytesType] ⇒ [String], [Bytes], [LengthPrefix]
// - [StartGroupType] and [StartGroupType] ⇒ [Message]
//
// If the field is unknown, it uses the same mapping as Unmarshal.
// If the field is unknown, it uses the same mapping as [Message.Unmarshal].
// Known sub-messages are parsed as a Message and packed repeated fields are
// parsed as a LengthPrefix.
// parsed as a [LengthPrefix].
func (m *Message) UnmarshalDescriptor(in []byte, desc protoreflect.MessageDescriptor) {
m.unmarshal(in, desc, false)
}
// UnmarshalAbductive is like UnmarshalDescriptor, but infers abductively
// UnmarshalAbductive is like [Message.UnmarshalDescriptor], but infers abductively
// whether any unknown bytes values is a message based on whether it is
// a syntactically well-formed message.
//

2
testing/prototest/enum.go
View File

@ -10,7 +10,7 @@ import (
"google.golang.org/protobuf/reflect/protoreflect"
)
// Enum tests an EnumType implementation.
// Enum tests an [protoreflect.EnumType] implementation.
type Enum struct{}
func (test Enum) Test(t testing.TB, et protoreflect.EnumType) {

2
testing/prototest/message.go
View File

@ -35,7 +35,7 @@ type Message struct {
}
}
// Test performs tests on a MessageType implementation.
// Test performs tests on a [protoreflect.MessageType] implementation.
func (test Message) Test(t testing.TB, mt protoreflect.MessageType) {
testType(t, mt)

41
types/dynamicpb/dynamic.go
View File

@ -49,12 +49,13 @@ type extensionType struct {
// A Message is a dynamically constructed protocol buffer message.
//
// Message implements the proto.Message interface, and may be used with all
// standard proto package functions such as Marshal, Unmarshal, and so forth.
// Message implements the [google.golang.org/protobuf/proto.Message] interface,
// and may be used with all standard proto package functions
// such as Marshal, Unmarshal, and so forth.
//
// Message also implements the protoreflect.Message interface. See the protoreflect
// package documentation for that interface for how to get and set fields and
// otherwise interact with the contents of a Message.
// Message also implements the [protoreflect.Message] interface.
// See the [protoreflect] package documentation for that interface for how to
// get and set fields and otherwise interact with the contents of a Message.
//
// Reflection API functions which construct messages, such as NewField,
// return new dynamic messages of the appropriate type. Functions which take
@ -87,7 +88,7 @@ func NewMessage(desc protoreflect.MessageDescriptor) *Message {
// ProtoMessage implements the legacy message interface.
func (m *Message) ProtoMessage() {}
// ProtoReflect implements the protoreflect.ProtoMessage interface.
// ProtoReflect implements the [protoreflect.ProtoMessage] interface.
func (m *Message) ProtoReflect() protoreflect.Message {
return m
}
@ -115,25 +116,25 @@ func (m *Message) Type() protoreflect.MessageType {
}
// New returns a newly allocated empty message with the same descriptor.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) New() protoreflect.Message {
return m.Type().New()
}
// Interface returns the message.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) Interface() protoreflect.ProtoMessage {
return m
}
// ProtoMethods is an internal detail of the protoreflect.Message interface.
// ProtoMethods is an internal detail of the [protoreflect.Message] interface.
// Users should never call this directly.
func (m *Message) ProtoMethods() *protoiface.Methods {
return nil
}
// Range visits every populated field in undefined order.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) Range(f func(protoreflect.FieldDescriptor, protoreflect.Value) bool) {
for num, v := range m.known {
fd := m.ext[num]
@ -150,7 +151,7 @@ func (m *Message) Range(f func(protoreflect.FieldDescriptor, protoreflect.Value)
}
// Has reports whether a field is populated.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) Has(fd protoreflect.FieldDescriptor) bool {
m.checkField(fd)
if fd.IsExtension() && m.ext[fd.Number()] != fd {
@ -164,7 +165,7 @@ func (m *Message) Has(fd protoreflect.FieldDescriptor) bool {
}
// Clear clears a field.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) Clear(fd protoreflect.FieldDescriptor) {
m.checkField(fd)
num := fd.Number()
@ -173,7 +174,7 @@ func (m *Message) Clear(fd protoreflect.FieldDescriptor) {
}
// Get returns the value of a field.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) Get(fd protoreflect.FieldDescriptor) protoreflect.Value {
m.checkField(fd)
num := fd.Number()
@ -212,7 +213,7 @@ func (m *Message) Get(fd protoreflect.FieldDescriptor) protoreflect.Value {
}
// Mutable returns a mutable reference to a repeated, map, or message field.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) Mutable(fd protoreflect.FieldDescriptor) protoreflect.Value {
m.checkField(fd)
if !fd.IsMap() && !fd.IsList() && fd.Message() == nil {
@ -241,7 +242,7 @@ func (m *Message) Mutable(fd protoreflect.FieldDescriptor) protoreflect.Value {
}
// Set stores a value in a field.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) Set(fd protoreflect.FieldDescriptor, v protoreflect.Value) {
m.checkField(fd)
if m.known == nil {
@ -284,7 +285,7 @@ func (m *Message) clearOtherOneofFields(fd protoreflect.FieldDescriptor) {
}
// NewField returns a new value for assignable to the field of a given descriptor.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) NewField(fd protoreflect.FieldDescriptor) protoreflect.Value {
m.checkField(fd)
switch {
@ -305,7 +306,7 @@ func (m *Message) NewField(fd protoreflect.FieldDescriptor) protoreflect.Value {
}
// WhichOneof reports which field in a oneof is populated, returning nil if none are populated.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) WhichOneof(od protoreflect.OneofDescriptor) protoreflect.FieldDescriptor {
for i := 0; i < od.Fields().Len(); i++ {
fd := od.Fields().Get(i)
@ -317,13 +318,13 @@ func (m *Message) WhichOneof(od protoreflect.OneofDescriptor) protoreflect.Field
}
// GetUnknown returns the raw unknown fields.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) GetUnknown() protoreflect.RawFields {
return m.unknown
}
// SetUnknown sets the raw unknown fields.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) SetUnknown(r protoreflect.RawFields) {
if m.known == nil {
panic(errors.New("%v: modification of read-only message", m.typ.desc.FullName()))
@ -332,7 +333,7 @@ func (m *Message) SetUnknown(r protoreflect.RawFields) {
}
// IsValid reports whether the message is valid.
// See protoreflect.Message for details.
// See [protoreflect.Message] for details.
func (m *Message) IsValid() bool {
return m.known != nil
}

14
types/dynamicpb/types.go
View File

@ -23,8 +23,8 @@ type extField struct {
// A Types is a collection of dynamically constructed descriptors.
// Its methods are safe for concurrent use.
//
// Types implements protoregistry.MessageTypeResolver and protoregistry.ExtensionTypeResolver.
// A Types may be used as a proto.UnmarshalOptions.Resolver.
// Types implements [protoregistry.MessageTypeResolver] and [protoregistry.ExtensionTypeResolver].
// A Types may be used as a [google.golang.org/protobuf/proto.UnmarshalOptions.Resolver].
type Types struct {
// atomicExtFiles is used with sync/atomic and hence must be the first word
// of the struct to guarantee 64-bit alignment.
@ -52,7 +52,7 @@ func NewTypes(f *protoregistry.Files) *Types {
// FindEnumByName looks up an enum by its full name;
// e.g., "google.protobuf.Field.Kind".
//
// This returns (nil, protoregistry.NotFound) if not found.
// This returns (nil, [protoregistry.NotFound]) if not found.
func (t *Types) FindEnumByName(name protoreflect.FullName) (protoreflect.EnumType, error) {
d, err := t.files.FindDescriptorByName(name)
if err != nil {
@ -70,7 +70,7 @@ func (t *Types) FindEnumByName(name protoreflect.FullName) (protoreflect.EnumTyp
// where the extension is declared and is unrelated to the full name of the
// message being extended.
//
// This returns (nil, protoregistry.NotFound) if not found.
// This returns (nil, [protoregistry.NotFound]) if not found.
func (t *Types) FindExtensionByName(name protoreflect.FullName) (protoreflect.ExtensionType, error) {
d, err := t.files.FindDescriptorByName(name)
if err != nil {
@ -86,7 +86,7 @@ func (t *Types) FindExtensionByName(name protoreflect.FullName) (protoreflect.Ex
// FindExtensionByNumber looks up an extension field by the field number
// within some parent message, identified by full name.
//
// This returns (nil, protoregistry.NotFound) if not found.
// This returns (nil, [protoregistry.NotFound]) if not found.
func (t *Types) FindExtensionByNumber(message protoreflect.FullName, field protoreflect.FieldNumber) (protoreflect.ExtensionType, error) {
// Construct the extension number map lazily, since not every user will need it.
// Update the map if new files are added to the registry.
@ -103,7 +103,7 @@ func (t *Types) FindExtensionByNumber(message protoreflect.FullName, field proto
// FindMessageByName looks up a message by its full name;
// e.g. "google.protobuf.Any".
//
// This returns (nil, protoregistry.NotFound) if not found.
// This returns (nil, [protoregistry.NotFound]) if not found.
func (t *Types) FindMessageByName(name protoreflect.FullName) (protoreflect.MessageType, error) {
d, err := t.files.FindDescriptorByName(name)
if err != nil {
@ -119,7 +119,7 @@ func (t *Types) FindMessageByName(name protoreflect.FullName) (protoreflect.Mess
// FindMessageByURL looks up a message by a URL identifier.
// See documentation on google.protobuf.Any.type_url for the URL format.
//
// This returns (nil, protoregistry.NotFound) if not found.
// This returns (nil, [protoregistry.NotFound]) if not found.
func (t *Types) FindMessageByURL(url string) (protoreflect.MessageType, error) {
// This function is similar to FindMessageByName but
// truncates anything before and including '/' in the URL.