reflect/protoreflect: improve documentation
Change-Id: I3942f9790be2d1d84578154645384018a5e1546e
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/220342
Reviewed-by: Damien Neil <dneil@google.com>
diff --git a/reflect/protoreflect/proto.go b/reflect/protoreflect/proto.go
index 443e3eb..eb5d289 100644
--- a/reflect/protoreflect/proto.go
+++ b/reflect/protoreflect/proto.go
@@ -11,30 +11,42 @@
//
// Protocol Buffer Descriptors
//
-// Protobuf descriptors (e.g., MessageDescriptor or EnumDescriptor)
+// 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.
//
-// The Message and Enum interfaces provide a Type method which returns the
-// appropriate descriptor type for a value.
+// 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. Protobuf descriptors can be constructed
+// using the "google.golang.org/protobuf/reflect/protodesc" package.
//
//
// Go Type Descriptors
//
-// A type descriptor (e.g., MessageType or EnumType) 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,
+// 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
-// create type descriptors when only the protobuf descriptor is known.
+// create Go type descriptors from protobuf descriptors.
//
//
// 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.
+// 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
// former's ProtoReflect method. Since the ProtoReflect method is new to the
