Strongly discourage new usages of google/protobuf/type.proto and google/protobuf/api.proto as alternatives to descriptors

src/google/protobuf/api.proto

@@ -51,6 +51,11 @@ option go_package = "google.golang.org/protobuf/types/known/apipb";
 // sometimes simply referred to as "APIs" in other contexts, such as the name of
 // this message itself. See https://cloud.google.com/apis/design/glossary for
 // detailed terminology.
+//
+// New usages of this message as an alternative to ServiceDescriptorProto are
+// strongly discouraged. This message does not reliability preserve all
+// information necessary to model the schema and preserve semantics. Instead
+// make use of FileDescriptorSet which preserves the necessary information.
 message Api {
   // The fully qualified name of this interface, including package name
   // followed by the interface's simple name.
@@ -99,6 +104,11 @@ message Api {
 }
 
 // Method represents a method of an API interface.
+//
+// New usages of this message as an alternative to MethodDescriptorProto are
+// strongly discouraged. This message does not reliability preserve all
+// information necessary to model the schema and preserve semantics. Instead
+// make use of FileDescriptorSet which preserves the necessary information.
 message Method {
   // The simple name of this method.
   string name = 1;

src/google/protobuf/type.proto

@@ -44,6 +44,11 @@ option csharp_namespace = "Google.Protobuf.WellKnownTypes";
 option go_package = "google.golang.org/protobuf/types/known/typepb";
 
 // A protocol buffer message type.
+//
+// New usages of this message as an alternative to DescriptorProto are strongly
+// discouraged. This message does not reliability preserve all information
+// necessary to model the schema and preserve semantics. Instead make use of
+// FileDescriptorSet which preserves the necessary information.
 message Type {
   // The fully qualified message name.
   string name = 1;
@@ -62,6 +67,11 @@ message Type {
 }
 
 // A single field of a message type.
+//
+// New usages of this message as an alternative to FieldDescriptorProto are
+// strongly discouraged. This message does not reliability preserve all
+// information necessary to model the schema and preserve semantics. Instead
+// make use of FileDescriptorSet which preserves the necessary information.
 message Field {
   // Basic field types.
   enum Kind {
@@ -142,6 +152,11 @@ message Field {
 }
 
 // Enum type definition.
+//
+// New usages of this message as an alternative to EnumDescriptorProto are
+// strongly discouraged. This message does not reliability preserve all
+// information necessary to model the schema and preserve semantics. Instead
+// make use of FileDescriptorSet which preserves the necessary information.
 message Enum {
   // Enum type name.
   string name = 1;
@@ -158,6 +173,11 @@ message Enum {
 }
 
 // Enum value definition.
+//
+// New usages of this message as an alternative to EnumValueDescriptorProto are
+// strongly discouraged. This message does not reliability preserve all
+// information necessary to model the schema and preserve semantics. Instead
+// make use of FileDescriptorSet which preserves the necessary information.
 message EnumValue {
   // Enum value name.
   string name = 1;
@@ -169,6 +189,10 @@ message EnumValue {
 
 // A protocol buffer option, which can be attached to a message, field,
 // enumeration, etc.
+//
+// New usages of this message as an alternative to FileOptions, MessageOptions,
+// FieldOptions, EnumOptions, EnumValueOptions, ServiceOptions, or MethodOptions
+// are strongly discouraged.
 message Option {
   // The option's name. For protobuf built-in options (options defined in
   // descriptor.proto), this is the short name. For example, `"map_entry"`.