Merge remote-tracking branch 'origin/3.4.x' into mergemaster

2 files changed, 39 insertions, 21 deletions

diff --git a/objectivec/google/protobuf/Any.pbobjc.h b/objectivec/google/protobuf/Any.pbobjc.h
index d236e4b2..b17e76f0 100644
--- a/objectivec/google/protobuf/Any.pbobjc.h
+++ b/objectivec/google/protobuf/Any.pbobjc.h
@@ -87,6 +87,16 @@ typedef GPB_ENUM(GPBAny_FieldNumber) {
  *       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 '/'
diff --git a/objectivec/google/protobuf/Api.pbobjc.h b/objectivec/google/protobuf/Api.pbobjc.h
index 742a8122..095fc2cd 100644
--- a/objectivec/google/protobuf/Api.pbobjc.h
+++ b/objectivec/google/protobuf/Api.pbobjc.h
@@ -63,34 +63,41 @@ typedef GPB_ENUM(GPBApi_FieldNumber) {
 };
 
 /**
- * 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.
  **/
 @interface GPBApi : GPBMessage
 
 /**
- * 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.
  **/
 @property(nonatomic, readwrite, copy, null_resettable) NSString *name;
 
-/** The methods of this api, in unspecified order. */
+/** The methods of this interface, in unspecified order. */
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBMethod*> *methodsArray;
 /** The number of items in @c methodsArray without causing the array to be created. */
 @property(nonatomic, readonly) NSUInteger methodsArray_Count;
 
-/** Any metadata attached to the API. */
+/** Any metadata attached to the interface. */
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray;
 /** The number of items in @c optionsArray without causing the array to be created. */
 @property(nonatomic, readonly) NSUInteger optionsArray_Count;
 
 /**
- * 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
@@ -100,10 +107,10 @@ typedef GPB_ENUM(GPBApi_FieldNumber) {
  * 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.
  **/
 @property(nonatomic, readwrite, copy, null_resettable) NSString *version;
 
@@ -115,7 +122,7 @@ typedef GPB_ENUM(GPBApi_FieldNumber) {
 /** Test to see if @c sourceContext has been set. */
 @property(nonatomic, readwrite) BOOL hasSourceContext;
 
-/** Included APIs. See [Mixin][]. */
+/** Included interfaces. See [Mixin][]. */
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBMixin*> *mixinsArray;
 /** The number of items in @c mixinsArray without causing the array to be created. */
 @property(nonatomic, readonly) NSUInteger mixinsArray_Count;
@@ -150,7 +157,7 @@ typedef GPB_ENUM(GPBMethod_FieldNumber) {
 };
 
 /**
- * Method represents a method of an api.
+ * Method represents a method of an API interface.
  **/
 @interface GPBMethod : GPBMessage
 
@@ -199,9 +206,9 @@ typedef GPB_ENUM(GPBMixin_FieldNumber) {
 };
 
 /**
- * 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
@@ -213,7 +220,8 @@ typedef GPB_ENUM(GPBMixin_FieldNumber) {
  *
  * - 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:
  *
@@ -279,7 +287,7 @@ typedef GPB_ENUM(GPBMixin_FieldNumber) {
  **/
 @interface GPBMixin : GPBMessage
 
-/** The fully qualified name of the API which is included. */
+/** The fully qualified name of the interface which is included. */
 @property(nonatomic, readwrite, copy, null_resettable) NSString *name;
 
 /**