reflect/protoreflect: improve documentation

Change-Id: I3942f9790be2d1d84578154645384018a5e1546e
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/220342
Reviewed-by: Damien Neil <dneil@google.com>

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
+// Enums and messages generated by this module implement Enum and ProtoMessage,
-// appropriate descriptor type for a value.
+// 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.
+// The Enum and Message interfaces provide a reflective view over an
-// This type provides the ability to manipulate the fields of a message.
+// 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