proto: extend documentation of GetExtension, SetExtension

Document the type mapping and the recommended pattern for working with
extensions. This documentation was Google-internal (cl/335451491), presumably
because of the reference to static analysis tools that don’t exist outside.

Compared to the internal version, this CL uses “should” instead of “must”.

Change-Id: I9293c10b2f6f91c9546d145c94b52e84f3a7a9c9
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/607995
LUCI-TryBot-Result: Go LUCI <[email protected]>
Reviewed-by: Damien Neil <[email protected]>
Reviewed-by: Christian Höppner <[email protected]>

proto/extension.go

@@ -39,6 +39,48 @@ func ClearExtension(m Message, xt protoreflect.ExtensionType) {
 // If the field is unpopulated, it returns the default value for
 // scalars and an immutable, empty value for lists or messages.
 // It panics if xt does not extend m.
+//
+// The type of the value is dependent on the field type of the extension.
+// For extensions generated by protoc-gen-go, the Go type is as follows:
+//
+//	╔═══════════════════╤═════════════════════════╗
+//	║ Go type           │ Protobuf kind           ║
+//	╠═══════════════════╪═════════════════════════╣
+//	║ bool              │ bool                    ║
+//	║ int32             │ int32, sint32, sfixed32 ║
+//	║ int64             │ int64, sint64, sfixed64 ║
+//	║ uint32            │ uint32, fixed32         ║
+//	║ uint64            │ uint64, fixed64         ║
+//	║ float32           │ float                   ║
+//	║ float64           │ double                  ║
+//	║ string            │ string                  ║
+//	║ []byte            │ bytes                   ║
+//	║ protoreflect.Enum │ enum                    ║
+//	║ proto.Message     │ message, group          ║
+//	╚═══════════════════╧═════════════════════════╝
+//
+// The protoreflect.Enum and proto.Message types are the concrete Go type
+// associated with the named enum or message. Repeated fields are represented
+// using a Go slice of the base element type.
+//
+// If a generated extension descriptor variable is directly passed to
+// GetExtension, then the call should be followed immediately by a
+// type assertion to the expected output value. For example:
+//
+//	mm := proto.GetExtension(m, foopb.E_MyExtension).(*foopb.MyMessage)
+//
+// This pattern enables static analysis tools to verify that the asserted type
+// matches the Go type associated with the extension field and
+// also enables a possible future migration to a type-safe extension API.
+//
+// Since singular messages are the most common extension type, the pattern of
+// calling HasExtension followed by GetExtension may be simplified to:
+//
+//	if mm := proto.GetExtension(m, foopb.E_MyExtension).(*foopb.MyMessage); mm != nil {
+//	    ... // make use of mm
+//	}
+//
+// The mm variable is non-nil if and only if HasExtension reports true.
 func GetExtension(m Message, xt protoreflect.ExtensionType) any {
 	// Treat nil message interface as an empty message; return the default.
 	if m == nil {
@@ -51,6 +93,35 @@ func GetExtension(m Message, xt protoreflect.ExtensionType) any {
 // SetExtension stores the value of an extension field.
 // It panics if m is invalid, xt does not extend m, or if type of v
 // is invalid for the specified extension field.
+//
+// The type of the value is dependent on the field type of the extension.
+// For extensions generated by protoc-gen-go, the Go type is as follows:
+//
+//	╔═══════════════════╤═════════════════════════╗
+//	║ Go type           │ Protobuf kind           ║
+//	╠═══════════════════╪═════════════════════════╣
+//	║ bool              │ bool                    ║
+//	║ int32             │ int32, sint32, sfixed32 ║
+//	║ int64             │ int64, sint64, sfixed64 ║
+//	║ uint32            │ uint32, fixed32         ║
+//	║ uint64            │ uint64, fixed64         ║
+//	║ float32           │ float                   ║
+//	║ float64           │ double                  ║
+//	║ string            │ string                  ║
+//	║ []byte            │ bytes                   ║
+//	║ protoreflect.Enum │ enum                    ║
+//	║ proto.Message     │ message, group          ║
+//	╚═══════════════════╧═════════════════════════╝
+//
+// The protoreflect.Enum and proto.Message types are the concrete Go type
+// associated with the named enum or message. Repeated fields are represented
+// using a Go slice of the base element type.
+//
+// If a generated extension descriptor variable is directly passed to
+// SetExtension (e.g., foopb.E_MyExtension), then the value should be a
+// concrete type that matches the expected Go type for the extension descriptor
+// so that static analysis tools can verify type correctness.
+// This also enables a possible future migration to a type-safe extension API.
 func SetExtension(m Message, xt protoreflect.ExtensionType, v any) {
 	xd := xt.TypeDescriptor()
 	pv := xt.ValueOf(v)