reflect/protoreflect: improve package documentation

There are many types in this package, which can get very confusing how
they all relate to each other. Add some Unicode box art to show the
relationships between XType, XDescriptor, and X.

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

reflect/protoreflect/proto.go

@@ -4,10 +4,11 @@
 
 // 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
+// This package includes type descriptors which describe the structure of types
+// defined in proto source files, and value interfaces which provide the
 // ability to examine and manipulate the contents of messages.
 //
+//
 // Type Descriptors
 //
 // The type descriptors (e.g., MessageDescriptor or EnumDescriptor)
@@ -17,6 +18,7 @@
 // The Message and Enum interfaces provide a Type method which returns the
 // appropriate descriptor type for a value.
 //
+//
 // Value Interfaces
 //
 // The protoreflect.Message type is a reflective view of a message instance.
@@ -24,6 +26,70 @@
 //
 // To convert a proto.Message to a protoreflect.Message, use the
 // former's ProtoReflect method.
+//
+//
+// Relationships
+//
+//	                       ┌───────────────────────────────────┐
+//	                       V                                   │
+//	   ┌────────────── New(n) ─────────────┐                   │
+//	   │                                   │                   │
+//	   │      ┌──── Descriptor() ──┐       │  ┌── Number() ──┐ │
+//	   │      │                    V       V  │              V │
+//	╔════════════╗  ╔════════════════╗  ╔════════╗  ╔════════════╗
+//	║  EnumType  ║  ║ EnumDescriptor ║  ║  Enum  ║  ║ EnumNumber ║
+//	╚════════════╝  ╚════════════════╝  ╚════════╝  ╚════════════╝
+//	      Λ           Λ                   │ │
+//	      │           └─── Descriptor() ──┘ │
+//	      │                                 │
+//	      └────────────────── 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 Enum is a concrete enum instance. Generated enums implement Enum.
+//
+//
+//	  ┌──────────────── New() ─────────────────┐
+//	  │                                        │
+//	  │         ┌─── Descriptor() ─────┐       │   ┌── Interface() ───┐
+//	  │         │                      V       V   │                  V
+//	╔═════════════╗  ╔═══════════════════╗  ╔═════════╗  ╔══════════════╗
+//	║ MessageType ║  ║ MessageDescriptor ║  ║ Message ║  ║ ProtoMessage ║
+//	╚═════════════╝  ╚═══════════════════╝  ╚═════════╝  ╚══════════════╝
+//	       Λ           Λ                      │ │  Λ                  │
+//	       │           └──── Descriptor() ────┘ │  └─ ProtoReflect() ─┘
+//	       │                                    │
+//	       └─────────────────── Type() ─────────┘
+//
+// • A MessageType describes a concrete Go message type.
+// It has a MessageDescriptor and can construct a Message instance.
+//
+// • A MessageDescriptor describes an abstract protobuf message type.
+//
+// • A Message is a concrete message instance. Generated messages implement
+// ProtoMessage, which can convert to/from a Message.
+//
+//
+//	        ┌── Descriptor() ──┐       ┌───── implements ─────┐
+//	        │                  V       │                      V
+//	╔═══════════════╗  ╔═════════════════════════╗  ╔═════════════════════╗
+//	║ ExtensionType ║  ║ ExtensionTypeDescriptor ║  ║ ExtensionDescriptor ║
+//	╚═══════════════╝  ╚═════════════════════════╝  ╚═════════════════════╝
+//	        Λ                  │       Λ                      │
+//	        └───── Type() ─────┘       └─── may implement ────┘
+//
+// • 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 ExtensionTypeDescriptor is an ExtensionDescriptor
+// which also has an ExtensionType.
+//
+// • An ExtensionDescriptor describes an abstract protobuf extension field and
+// may not always be an ExtensionTypeDescriptor.
 package protoreflect
 
 import (

reflect/protoreflect/type.go

@@ -30,18 +30,18 @@ type Descriptor interface {
 	// Parent returns the parent containing this descriptor declaration.
 	// The following shows the mapping from child type to possible parent types:
 	//
-	//	+---------------------+-----------------------------------+
-	//	| Child type          | Possible parent types             |
-	//	+---------------------+-----------------------------------+
-	//	| FileDescriptor      | nil                               |
-	//	| MessageDescriptor   | FileDescriptor, MessageDescriptor |
-	//	| FieldDescriptor     | FileDescriptor, MessageDescriptor |
-	//	| OneofDescriptor     | MessageDescriptor                 |
-	//	| EnumDescriptor      | FileDescriptor, MessageDescriptor |
-	//	| EnumValueDescriptor | EnumDescriptor                    |
-	//	| ServiceDescriptor   | FileDescriptor                    |
-	//	| MethodDescriptor    | ServiceDescriptor                 |
-	//	+---------------------+-----------------------------------+
+	//	╔═════════════════════╤═══════════════════════════════════╗
+	//	║ Child type          │ Possible parent types             ║
+	//	╠═════════════════════╪═══════════════════════════════════╣
+	//	║ FileDescriptor      │ nil                               ║
+	//	║ MessageDescriptor   │ FileDescriptor, MessageDescriptor ║
+	//	║ FieldDescriptor     │ FileDescriptor, MessageDescriptor ║
+	//	║ OneofDescriptor     │ MessageDescriptor                 ║
+	//	║ EnumDescriptor      │ FileDescriptor, MessageDescriptor ║
+	//	║ EnumValueDescriptor │ EnumDescriptor                    ║
+	//	║ ServiceDescriptor   │ FileDescriptor                    ║
+	//	║ MethodDescriptor    │ ServiceDescriptor                 ║
+	//	╚═════════════════════╧═══════════════════════════════════╝
 	//
 	// Support for this functionality is optional and may return nil.
 	Parent() Descriptor
@@ -72,12 +72,12 @@ type Descriptor interface {
 	// Placeholder types may only be returned by the following accessors
 	// as a result of weak imports:
 	//
-	//	+-----------------------------------+-------------------+
-	//	| Accessor                          | Descriptor        |
-	//	+-----------------------------------+-------------------+
-	//	| FileImports.FileDescriptor        | FileDescriptor    |
-	//	| FieldDescriptor.MessageDescriptor | MessageDescriptor |
-	//	+-----------------------------------+-------------------+
+	//	╔═══════════════════════════════════╤═══════════════════╗
+	//	║ Accessor                          │ Descriptor        ║
+	//	╠═══════════════════════════════════╪═══════════════════╣
+	//	║ FileImports.FileDescriptor        │ FileDescriptor    ║
+	//	║ FieldDescriptor.MessageDescriptor │ MessageDescriptor ║
+	//	╚═══════════════════════════════════╧═══════════════════╝
 	//
 	// If true, only Name and FullName are valid.
 	// For FileDescriptor, the Path and Package are also valid.
@@ -88,18 +88,18 @@ type Descriptor interface {
 	//
 	// To avoid a dependency cycle, this function returns an interface value.
 	// The proto message type returned for each descriptor type is as follows:
-	//	+---------------------+------------------------------------------+
-	//	| Go type             | Proto message type                       |
-	//	+---------------------+------------------------------------------+
-	//	| FileDescriptor      | google.protobuf.FileOptions              |
-	//	| 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            |
-	//	+---------------------+------------------------------------------+
+	//	╔═════════════════════╤══════════════════════════════════════════╗
+	//	║ Go type             │ Protobuf message type                    ║
+	//	╠═════════════════════╪══════════════════════════════════════════╣
+	//	║ FileDescriptor      │ google.protobuf.FileOptions              ║
+	//	║ 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.

reflect/protoreflect/value_union.go

@@ -14,21 +14,21 @@ import (
 // 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:
 //
-//	+------------+-------------------------------------+
-//	| Go type    | Protobuf kind                       |
-//	+------------+-------------------------------------+
-//	| bool       | BoolKind                            |
-//	| int32      | Int32Kind, Sint32Kind, Sfixed32Kind |
-//	| int64      | Int64Kind, Sint64Kind, Sfixed64Kind |
-//	| uint32     | Uint32Kind, Fixed32Kind             |
-//	| uint64     | Uint64Kind, Fixed64Kind             |
-//	| float32    | FloatKind                           |
-//	| float64    | DoubleKind                          |
-//	| string     | StringKind                          |
-//	| []byte     | BytesKind                           |
-//	| EnumNumber | EnumKind                            |
-//	| Message    | MessageKind, GroupKind              |
-//	+------------+-------------------------------------+
+//	╔════════════╤═════════════════════════════════════╗
+//	║ Go type    │ Protobuf kind                       ║
+//	╠════════════╪═════════════════════════════════════╣
+//	║ bool       │ BoolKind                            ║
+//	║ int32      │ Int32Kind, Sint32Kind, Sfixed32Kind ║
+//	║ int64      │ Int64Kind, Sint64Kind, Sfixed64Kind ║
+//	║ uint32     │ Uint32Kind, Fixed32Kind             ║
+//	║ uint64     │ Uint64Kind, Fixed64Kind             ║
+//	║ float32    │ FloatKind                           ║
+//	║ float64    │ DoubleKind                          ║
+//	║ string     │ StringKind                          ║
+//	║ []byte     │ BytesKind                           ║
+//	║ EnumNumber │ EnumKind                            ║
+//	║ Message    │ MessageKind, GroupKind              ║
+//	╚════════════╧═════════════════════════════════════╝
 //
 // 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,
@@ -248,16 +248,16 @@ func (v Value) MapKey() MapKey {
 // the specified key Kind (see MessageDescriptor.IsMapEntry).
 // The following shows what Go type is used to represent each proto Kind:
 //
-//	+---------+-------------------------------------+
-//	| Go type | Protobuf kind                       |
-//	+---------+-------------------------------------+
-//	| bool    | BoolKind                            |
-//	| int32   | Int32Kind, Sint32Kind, Sfixed32Kind |
-//	| int64   | Int64Kind, Sint64Kind, Sfixed64Kind |
-//	| uint32  | Uint32Kind, Fixed32Kind             |
-//	| uint64  | Uint64Kind, Fixed64Kind             |
-//	| string  | StringKind                          |
-//	+---------+-------------------------------------+
+//	╔═════════╤═════════════════════════════════════╗
+//	║ Go type │ Protobuf kind                       ║
+//	╠═════════╪═════════════════════════════════════╣
+//	║ bool    │ BoolKind                            ║
+//	║ int32   │ Int32Kind, Sint32Kind, Sfixed32Kind ║
+//	║ int64   │ Int64Kind, Sint64Kind, Sfixed64Kind ║
+//	║ uint32  │ Uint32Kind, Fixed32Kind             ║
+//	║ uint64  │ Uint64Kind, Fixed64Kind             ║
+//	║ string  │ StringKind                          ║
+//	╚═════════╧═════════════════════════════════════╝
 //
 // A MapKey is constructed and accessed through a Value:
 //	k := ValueOf("hash").MapKey() // convert string to MapKey