Merge a769c2e into 8021ff9

gen/google/protobuf/any.proto

@@ -37,7 +37,6 @@ option go_package = "github.com/golang/protobuf/ptypes/any";
 option java_package = "com.google.protobuf";
 option java_outer_classname = "AnyProto";
 option java_multiple_files = true;
-option java_generate_equals_and_hash = true;
 option objc_class_prefix = "GPB";
 
 // `Any` contains an arbitrary serialized protocol buffer message along with a
@@ -75,6 +74,16 @@ option objc_class_prefix = "GPB";
 //       any.Unpack(foo)
 //       ...
 //
+//  Example 4: Pack and unpack a message in Go
+//
+//      foo := &pb.Foo{...}
+//      any, err := ptypes.MarshalAny(foo)
+//      ...
+//      foo := &pb.Foo{}
+//      if err := ptypes.UnmarshalAny(any, foo); err != nil {
+//        ...
+//      }
+//
 // The pack methods provided by protobuf library will by default use
 // 'type.googleapis.com/full.type.name' as the type URL and the unpack
 // methods only use the fully qualified type name after the last '/'
@@ -111,17 +120,18 @@ option objc_class_prefix = "GPB";
 //     }
 //
 message Any {
-  // A URL/resource name whose content describes the type of the
-  // serialized protocol buffer message.
+  // A URL/resource name that uniquely identifies the type of the serialized
+  // protocol buffer message. The last segment of the URL's path must represent
+  // the fully qualified name of the type (as in
+  // `path/google.protobuf.Duration`). The name should be in a canonical form
+  // (e.g., leading "." is not accepted).
   //
-  // For URLs which use the scheme `http`, `https`, or no scheme, the
-  // following restrictions and interpretations apply:
+  // In practice, teams usually precompile into the binary all types that they
+  // expect it to use in the context of Any. However, for URLs which use the
+  // scheme `http`, `https`, or no scheme, one can optionally set up a type
+  // server that maps type URLs to message definitions as follows:
   //
   // * If no scheme is provided, `https` is assumed.
-  // * The last segment of the URL's path must represent the fully
-  //   qualified name of the type (as in `path/google.protobuf.Duration`).
-  //   The name should be in a canonical form (e.g., leading "." is
-  //   not accepted).
   // * An HTTP GET on the URL must yield a [google.protobuf.Type][]
   //   value in binary format, or produce an error.
   // * Applications are allowed to cache lookup results based on the
@@ -130,6 +140,10 @@ message Any {
   //   on changes to types. (Use versioned type names to manage
   //   breaking changes.)
   //
+  // Note: this functionality is not currently available in the official
+  // protobuf release, and it is not used for type URLs beginning with
+  // type.googleapis.com.
+  //
   // Schemes other than `http`, `https` (or the empty scheme) might be
   // used with implementation specific semantics.
   //

gen/google/protobuf/api.proto

@@ -39,29 +39,36 @@ option csharp_namespace = "Google.Protobuf.WellKnownTypes";
 option java_package = "com.google.protobuf";
 option java_outer_classname = "ApiProto";
 option java_multiple_files = true;
-option java_generate_equals_and_hash = true;
 option objc_class_prefix = "GPB";
+option go_package = "google.golang.org/genproto/protobuf/api;api";
 
-// Api is a light-weight descriptor for a protocol buffer service.
+// Api is a light-weight descriptor for an API Interface.
+//
+// Interfaces are also described as "protocol buffer services" in some contexts,
+// such as by the "service" keyword in a .proto file, but they are different
+// from API Services, which represent a concrete implementation of an interface
+// as opposed to simply a description of methods and bindings. They are also
+// 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.
 message Api {
 
-  // The fully qualified name of this api, including package name
-  // followed by the api's simple name.
+  // The fully qualified name of this interface, including package name
+  // followed by the interface's simple name.
   string name = 1;
 
-  // The methods of this api, in unspecified order.
+  // The methods of this interface, in unspecified order.
   repeated Method methods = 2;
 
-  // Any metadata attached to the API.
+  // Any metadata attached to the interface.
   repeated Option options = 3;
 
-  // A version string for this api. If specified, must have the form
-  // `major-version.minor-version`, as in `1.10`. If the minor version
-  // is omitted, it defaults to zero. If the entire version field is
-  // empty, the major version is derived from the package name, as
-  // outlined below. If the field is not empty, the version in the
-  // package name will be verified to be consistent with what is
-  // provided here.
+  // A version string for this interface. If specified, must have the form
+  // `major-version.minor-version`, as in `1.10`. If the minor version is
+  // omitted, it defaults to zero. If the entire version field is empty, the
+  // major version is derived from the package name, as outlined below. If the
+  // field is not empty, the version in the package name will be verified to be
+  // consistent with what is provided here.
   //
   // The versioning schema uses [semantic
   // versioning](http://semver.org) where the major version number
@@ -71,10 +78,10 @@ message Api {
   // chosen based on the product plan.
   //
   // The major version is also reflected in the package name of the
-  // API, which must end in `v<major-version>`, as in
+  // interface, which must end in `v<major-version>`, as in
   // `google.feature.v1`. For major versions 0 and 1, the suffix can
   // be omitted. Zero major versions must only be used for
-  // experimental, none-GA apis.
+  // experimental, non-GA interfaces.
   //
   //
   string version = 4;
@@ -83,14 +90,14 @@ message Api {
   // message.
   SourceContext source_context = 5;
 
-  // Included APIs. See [Mixin][].
+  // Included interfaces. See [Mixin][].
   repeated Mixin mixins = 6;
 
   // The source syntax of the service.
   Syntax syntax = 7;
 }
 
-// Method represents a method of an api.
+// Method represents a method of an API interface.
 message Method {
 
   // The simple name of this method.
@@ -115,9 +122,9 @@ message Method {
   Syntax syntax = 7;
 }
 
-// Declares an API to be included in this API. The including API must
-// redeclare all the methods from the included API, but documentation
-// and options are inherited as follows:
+// Declares an API Interface to be included in this interface. The including
+// interface must redeclare all the methods from the included interface, but
+// documentation and options are inherited as follows:
 //
 // - If after comment and whitespace stripping, the documentation
 //   string of the redeclared method is empty, it will be inherited
@@ -129,7 +136,8 @@ message Method {
 //
 // - If an http annotation is inherited, the path pattern will be
 //   modified as follows. Any version prefix will be replaced by the
-//   version of the including API plus the [root][] path if specified.
+//   version of the including interface plus the [root][] path if
+//   specified.
 //
 // Example of a simple mixin:
 //
@@ -193,7 +201,7 @@ message Method {
 //       ...
 //     }
 message Mixin {
-  // The fully qualified name of the API which is included.
+  // The fully qualified name of the interface which is included.
   string name = 1;
 
   // If non-empty specifies a path under which inherited HTTP paths

gen/google/protobuf/compiler/plugin.proto

@@ -49,10 +49,20 @@ package google.protobuf.compiler;
 option java_package = "com.google.protobuf.compiler";
 option java_outer_classname = "PluginProtos";
 
-option go_package = "plugin_go";
+option go_package = "github.com/golang/protobuf/protoc-gen-go/plugin;plugin_go";
 
 import "google/protobuf/descriptor.proto";
 
+// The version number of protocol compiler.
+message Version {
+  optional int32 major = 1;
+  optional int32 minor = 2;
+  optional int32 patch = 3;
+  // A suffix for alpha, beta or rc release, e.g., "alpha-1", "rc2". It should
+  // be empty for mainline stable releases.
+  optional string suffix = 4;
+}
+
 // An encoded CodeGeneratorRequest is written to the plugin's stdin.
 message CodeGeneratorRequest {
   // The .proto files that were explicitly listed on the command-line.  The
@@ -74,7 +84,14 @@ message CodeGeneratorRequest {
   // the entire set into memory at once.  However, as of this writing, this
   // is not similarly optimized on protoc's end -- it will store all fields in
   // memory at once before sending them to the plugin.
+  //
+  // Type names of fields and extensions in the FileDescriptorProto are always
+  // fully qualified.
   repeated FileDescriptorProto proto_file = 15;
+
+  // The version number of protocol compiler.
+  optional Version compiler_version = 3;
+
 }
 
 // The plugin writes an encoded CodeGeneratorResponse to stdout.