reflect/protoreflect: update documentation
There were a few stale references due to renamed identifiers.
Change-Id: I0ac7eda93c46143292799c3806214dc89f1e80cd
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/219504
Reviewed-by: Damien Neil <dneil@google.com>
diff --git a/reflect/protoreflect/proto.go b/reflect/protoreflect/proto.go
index 044c10a..443e3eb 100644
--- a/reflect/protoreflect/proto.go
+++ b/reflect/protoreflect/proto.go
@@ -5,27 +5,42 @@
// Package protoreflect provides interfaces to dynamically manipulate messages.
//
// This package includes type descriptors which describe the structure of types
-// defined in proto source files, and value interfaces which provide the
+// defined in proto source files and value interfaces which provide the
// ability to examine and manipulate the contents of messages.
//
//
-// Type Descriptors
+// Protocol Buffer Descriptors
//
-// The type descriptors (e.g., MessageDescriptor or EnumDescriptor)
+// Protobuf descriptors (e.g., MessageDescriptor or EnumDescriptor)
// 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.
//
// The Message and Enum interfaces provide a Type method which returns the
// appropriate descriptor type for a value.
//
//
+// Go Type Descriptors
+//
+// A type descriptor (e.g., MessageType or EnumType) 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.
+//
+// The "google.golang.org/protobuf/types/dynamicpb" package can be used to
+// create type descriptors when only the protobuf descriptor is known.
+//
+//
// Value Interfaces
//
// The protoreflect.Message type is a reflective view of a message instance.
// This type provides the ability to manipulate the fields of a message.
//
// To convert a proto.Message to a protoreflect.Message, use the
-// former's ProtoReflect method.
+// 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
+// to obtain a reflective view on older messages.
//
//
// Relationships
@@ -134,7 +149,7 @@
}
}
-// String returns s as a proto source identifier.
+// String returns s as a proto source identifier (e.g., "proto2").
func (s Syntax) String() string {
switch s {
case Proto2:
@@ -146,7 +161,7 @@
}
}
-// GoString returns s as a Go source identifier.
+// GoString returns s as a Go source identifier (e.g., "Proto2").
func (s Syntax) GoString() string {
switch s {
case Proto2:
@@ -180,7 +195,7 @@
}
}
-// String returns c as a proto source identifier.
+// String returns c as a proto source identifier (e.g., "optional").
func (c Cardinality) String() string {
switch c {
case Optional:
@@ -194,7 +209,7 @@
}
}
-// GoString returns c as a Go source identifier.
+// GoString returns c as a Go source identifier (e.g., "Optional").
func (c Cardinality) GoString() string {
switch c {
case Optional:
@@ -250,7 +265,7 @@
}
}
-// String returns k as a proto source identifier.
+// String returns k as a proto source identifier (e.g., "bool").
func (k Kind) String() string {
switch k {
case BoolKind:
@@ -294,7 +309,7 @@
}
}
-// GoString returns k as a Go source identifier.
+// GoString returns k as a Go source identifier (e.g., "BoolKind").
func (k Kind) GoString() string {
switch k {
case BoolKind:
diff --git a/reflect/protoreflect/source.go b/reflect/protoreflect/source.go
index f08c983..32ea3d9 100644
--- a/reflect/protoreflect/source.go
+++ b/reflect/protoreflect/source.go
@@ -41,7 +41,7 @@
TrailingComments string
}
-// SourcePath identifies a part of a file descriptor for a source location.
+// SourcePath identifies part of a file descriptor for a source location.
// The SourcePath is a sequence of either field numbers or indexes into
// a repeated field that form a path starting from the root file descriptor.
//
diff --git a/reflect/protoreflect/type.go b/reflect/protoreflect/type.go
index 91380e5..797aa18 100644
--- a/reflect/protoreflect/type.go
+++ b/reflect/protoreflect/type.go
@@ -17,7 +17,7 @@
// 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).
// This can occur if a descriptor type is created dynamically, or multiple
-// versions of the same proto type are linked into the Go binary.
+// versions of the same proto type are accidentally linked into the Go binary.
type Descriptor interface {
// ParentFile returns the parent file descriptor that this descriptor
// is declared within. The parent file for the file descriptor is itself.
@@ -68,39 +68,44 @@
// dependency is not resolved, in which case only name information is known.
//
// Placeholder types may only be returned by the following accessors
- // as a result of weak imports:
+ // as a result of unresolved dependencies or weak imports:
//
- // ╔═══════════════════════════════════╤═══════════════════╗
- // ║ Accessor │ Descriptor ║
- // ╠═══════════════════════════════════╪═══════════════════╣
- // ║ FileImports.FileDescriptor │ FileDescriptor ║
- // ║ FieldDescriptor.MessageDescriptor │ MessageDescriptor ║
- // ╚═══════════════════════════════════╧═══════════════════╝
+ // ╔═══════════════════════════════════╤═════════════════════╗
+ // ║ Accessor │ Descriptor ║
+ // ╠═══════════════════════════════════╪═════════════════════╣
+ // ║ FileImports.FileDescriptor │ FileDescriptor ║
+ // ║ FieldDescriptor.Enum │ EnumDescriptor ║
+ // ║ FieldDescriptor.Message │ MessageDescriptor ║
+ // ║ FieldDescriptor.DefaultEnumValue │ EnumValueDescriptor ║
+ // ║ FieldDescriptor.ContainingMessage │ MessageDescriptor ║
+ // ║ MethodDescriptor.Input │ MessageDescriptor ║
+ // ║ MethodDescriptor.Output │ MessageDescriptor ║
+ // ╚═══════════════════════════════════╧═════════════════════╝
//
// If true, only Name and FullName are valid.
- // For FileDescriptor, the Path and Package are also valid.
+ // For FileDescriptor, the Path is also valid.
IsPlaceholder() bool
// Options returns the descriptor options. The caller must not modify
// the returned value.
//
- // To avoid a dependency cycle, this function returns an interface value.
+ // To avoid a dependency cycle, this function returns a proto.Message value.
// The proto message type returned for each descriptor type is as follows:
// ╔═════════════════════╤══════════════════════════════════════════╗
// ║ Go type │ Protobuf message type ║
// ╠═════════════════════╪══════════════════════════════════════════╣
// ║ FileDescriptor │ google.protobuf.FileOptions ║
+ // ║ EnumDescriptor │ google.protobuf.EnumOptions ║
+ // ║ EnumValueDescriptor │ google.protobuf.EnumValueOptions ║
// ║ MessageDescriptor │ google.protobuf.MessageOptions ║
// ║ FieldDescriptor │ google.protobuf.FieldOptions ║
// ║ OneofDescriptor │ google.protobuf.OneofOptions ║
- // ║ EnumDescriptor │ google.protobuf.EnumOptions ║
- // ║ EnumValueDescriptor │ google.protobuf.EnumValueOptions ║
// ║ ServiceDescriptor │ google.protobuf.ServiceOptions ║
// ║ MethodDescriptor │ google.protobuf.MethodOptions ║
// ╚═════════════════════╧══════════════════════════════════════════╝
//
// This method returns a typed nil-pointer if no options are present.
- // The caller must import the descriptor package to use this.
+ // The caller must import the descriptorpb package to use this.
Options() ProtoMessage
doNotImplement
@@ -110,11 +115,11 @@
// corresponds with the google.protobuf.FileDescriptorProto message.
//
// Top-level declarations:
-// MessageDescriptor, EnumDescriptor, FieldDescriptor, and/or ServiceDescriptor.
+// EnumDescriptor, MessageDescriptor, FieldDescriptor, and/or ServiceDescriptor.
type FileDescriptor interface {
Descriptor // Descriptor.FullName is identical to Package
- // Path returns the file name, relative to root of source tree.
+ // Path returns the file name, relative to the source tree root.
Path() string // e.g., "path/to/file.proto"
// Package returns the protobuf package namespace.
Package() FullName // e.g., "google.protobuf"
@@ -122,10 +127,10 @@
// Imports is a list of imported proto files.
Imports() FileImports
- // Messages is a list of the top-level message declarations.
- Messages() MessageDescriptors
// Enums is a list of the top-level enum declarations.
Enums() EnumDescriptors
+ // Messages is a list of the top-level message declarations.
+ Messages() MessageDescriptors
// Extensions is a list of the top-level extension declarations.
Extensions() ExtensionDescriptors
// Services is a list of the top-level service declarations.
@@ -175,8 +180,8 @@
// corresponds with the google.protobuf.DescriptorProto message.
//
// Nested declarations:
-// FieldDescriptor, OneofDescriptor, FieldDescriptor, MessageDescriptor,
-// and/or EnumDescriptor.
+// FieldDescriptor, OneofDescriptor, FieldDescriptor, EnumDescriptor,
+// and/or MessageDescriptor.
type MessageDescriptor interface {
Descriptor
@@ -214,10 +219,10 @@
// This method may return a nil interface value if no options are present.
ExtensionRangeOptions(i int) ProtoMessage
- // Messages is a list of nested message declarations.
- Messages() MessageDescriptors
// Enums is a list of nested enum declarations.
Enums() EnumDescriptors
+ // Messages is a list of nested message declarations.
+ Messages() MessageDescriptors
// Extensions is a list of nested extension declarations.
Extensions() ExtensionDescriptors
@@ -277,12 +282,12 @@
// IsExtension reports whether this is an extension field. If false,
// then Parent and ContainingMessage refer to the same message.
- // Otherwise, ContainingMessage and Parent almost certainly differ.
+ // Otherwise, ContainingMessage and Parent likely differ.
IsExtension() bool
// IsWeak reports whether this is a weak field, which does not impose a
// direct dependency on the target type.
- // If true, then MessageDescriptor returns a placeholder type.
+ // If true, then Message returns a placeholder type.
IsWeak() bool
// IsPacked reports whether repeated primitive numeric kinds should be
@@ -467,10 +472,10 @@
// as it has more type information available.
InterfaceOf(Value) interface{}
- // IsValidValue returns whether the Value is valid to assign to the field.
+ // IsValidValue reports whether the Value is valid to assign to the field.
IsValidValue(Value) bool
- // IsValidInterface returns whether the input is valid to assign to the field.
+ // IsValidInterface reports whether the input is valid to assign to the field.
IsValidInterface(interface{}) bool
}
