reflect/protoreflect: improve documentation for message types
There are a number of message types, which can be confusing.
Expand the documentation. In particular, use Go's reflection model
as an analogy, which helps users if they are at least familiar
with how Go reflection works. After all, protobuf reflection
was modeled after Go reflection to a large degree.
Change-Id: I388ae41c792905145ccc86dc938b901a2b79f408
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/399654
Reviewed-by: Damien Neil <dneil@google.com>
Run-TryBot: Ian Lance Taylor <iant@golang.org>
Auto-Submit: Ian Lance Taylor <iant@golang.org>
Run-TryBot: Joseph Tsai <joetsai@digital-static.net>
Auto-Submit: Joseph Tsai <joetsai@digital-static.net>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: Lasse Folger <lassefolger@google.com>
diff --git a/reflect/protoreflect/proto.go b/reflect/protoreflect/proto.go
index dd85915..8be08b1 100644
--- a/reflect/protoreflect/proto.go
+++ b/reflect/protoreflect/proto.go
@@ -98,11 +98,22 @@
//
// • 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 Message is a concrete message instance. Generated messages implement
-// ProtoMessage, which can convert to/from a Message.
+// • 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.
//
//
// ┌── TypeDescriptor() ──┐ ┌───── Descriptor() ─────┐
