diff --git a/objectivec/GPBExtensionRegistry.h b/objectivec/GPBExtensionRegistry.h index b395db17d8..d79632d28b 100644 --- a/objectivec/GPBExtensionRegistry.h +++ b/objectivec/GPBExtensionRegistry.h @@ -77,7 +77,7 @@ NS_ASSUME_NONNULL_BEGIN * @param descriptor The descriptor to look for a registered extension on. * @param fieldNumber The field number of the extension to look for. * - * @return The registered GPBExtensionDescripto or nil if none was found. + * @return The registered GPBExtensionDescriptor or nil if none was found. **/ - (nullable GPBExtensionDescriptor *)extensionForDescriptor:(GPBDescriptor *)descriptor fieldNumber:(NSInteger)fieldNumber; diff --git a/objectivec/google/protobuf/Any.pbobjc.h b/objectivec/google/protobuf/Any.pbobjc.h index 940206b651..842052fed8 100644 --- a/objectivec/google/protobuf/Any.pbobjc.h +++ b/objectivec/google/protobuf/Any.pbobjc.h @@ -51,12 +51,12 @@ typedef GPB_ENUM(GPBAny_FieldNumber) { /** * `Any` contains an arbitrary serialized protocol buffer message along with a * URL that describes the type of the serialized message. - * + * * Protobuf library provides support to pack/unpack Any values in the form * of utility functions or additional generated methods of the Any type. - * + * * Example 1: Pack and unpack a message in C++. - * + * * Foo foo = ...; * Any any; * any.PackFrom(foo); @@ -64,18 +64,18 @@ typedef GPB_ENUM(GPBAny_FieldNumber) { * if (any.UnpackTo(&foo)) { * ... * } - * + * * Example 2: Pack and unpack a message in Java. - * + * * Foo foo = ...; * Any any = Any.pack(foo); * ... * if (any.is(Foo.class)) { * foo = any.unpack(Foo.class); * } - * + * * Example 3: Pack and unpack a message in Python. - * + * * foo = Foo(...) * any = Any() * any.Pack(foo) @@ -83,37 +83,37 @@ typedef GPB_ENUM(GPBAny_FieldNumber) { * if any.Is(Foo.DESCRIPTOR): * any.Unpack(foo) * ... - * + * * 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 '/' * in the type URL, for example "foo.bar.com/x/y.z" will yield type * name "y.z". - * - * + * + * * JSON * ==== * The JSON representation of an `Any` value uses the regular * representation of the deserialized, embedded message, with an * additional field `\@type` which contains the type URL. Example: - * + * * package google.profile; * message Person { * string first_name = 1; * string last_name = 2; * } - * + * * { * "\@type": "type.googleapis.com/google.profile.Person", * "firstName": , * "lastName": * } - * + * * If the embedded message type is well-known and has a custom JSON * representation, that representation will be embedded adding a field * `value` which holds the custom JSON in addition to the `\@type` * field. Example (for message [google.protobuf.Duration][]): - * + * * { * "\@type": "type.googleapis.com/google.protobuf.Duration", * "value": "1.212s" @@ -124,10 +124,10 @@ typedef GPB_ENUM(GPBAny_FieldNumber) { /** * A URL/resource name whose content describes the type of the * serialized protocol buffer message. - * + * * For URLs which use the scheme `http`, `https`, or no scheme, the * following restrictions and interpretations apply: - * + * * * 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`). @@ -140,7 +140,7 @@ typedef GPB_ENUM(GPBAny_FieldNumber) { * lookup. Therefore, binary compatibility needs to be preserved * on changes to types. (Use versioned type names to manage * breaking changes.) - * + * * Schemes other than `http`, `https` (or the empty scheme) might be * used with implementation specific semantics. **/ diff --git a/objectivec/google/protobuf/Api.pbobjc.h b/objectivec/google/protobuf/Api.pbobjc.h index 3dda769877..182e866c04 100644 --- a/objectivec/google/protobuf/Api.pbobjc.h +++ b/objectivec/google/protobuf/Api.pbobjc.h @@ -88,14 +88,14 @@ typedef GPB_ENUM(GPBApi_FieldNumber) { * 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 * indicates a breaking change and the minor version an additive, * non-breaking change. Both version numbers are signals to users * what to expect from different versions, and should be carefully * chosen based on the product plan. - * + * * The major version is also reflected in the package name of the * API, which must end in `v`, as in * `google.feature.v1`. For major versions 0 and 1, the suffix can @@ -199,21 +199,21 @@ 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: - * + * * - If after comment and whitespace stripping, the documentation * string of the redeclared method is empty, it will be inherited * from the original method. - * + * * - Each annotation belonging to the service config (http, * visibility) which is not set in the redeclared method will be * inherited. - * + * * - 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. - * + * * Example of a simple mixin: - * + * * package google.acl.v1; * service AccessControl { * // Get the underlying ACL object. @@ -221,30 +221,30 @@ typedef GPB_ENUM(GPBMixin_FieldNumber) { * option (google.api.http).get = "/v1/{resource=**}:getAcl"; * } * } - * + * * package google.storage.v2; * service Storage { * rpc GetAcl(GetAclRequest) returns (Acl); - * + * * // Get a data record. * rpc GetData(GetDataRequest) returns (Data) { * option (google.api.http).get = "/v2/{resource=**}"; * } * } - * + * * Example of a mixin configuration: - * + * * apis: * - name: google.storage.v2.Storage * mixins: * - name: google.acl.v1.AccessControl - * + * * The mixin construct implies that all methods in `AccessControl` are * also declared with same name and request/response types in * `Storage`. A documentation generator or annotation processor will * see the effective `Storage.GetAcl` method after inherting * documentation and annotations as follows: - * + * * service Storage { * // Get the underlying ACL object. * rpc GetAcl(GetAclRequest) returns (Acl) { @@ -252,20 +252,20 @@ typedef GPB_ENUM(GPBMixin_FieldNumber) { * } * ... * } - * + * * Note how the version in the path pattern changed from `v1` to `v2`. - * + * * If the `root` field in the mixin is specified, it should be a * relative path under which inherited HTTP paths are placed. Example: - * + * * apis: * - name: google.storage.v2.Storage * mixins: * - name: google.acl.v1.AccessControl * root: acls - * + * * This implies the following inherited HTTP annotation: - * + * * service Storage { * // Get the underlying ACL object. * rpc GetAcl(GetAclRequest) returns (Acl) { diff --git a/objectivec/google/protobuf/Duration.pbobjc.h b/objectivec/google/protobuf/Duration.pbobjc.h index 8f9b351589..fa91e223cb 100644 --- a/objectivec/google/protobuf/Duration.pbobjc.h +++ b/objectivec/google/protobuf/Duration.pbobjc.h @@ -55,16 +55,16 @@ typedef GPB_ENUM(GPBDuration_FieldNumber) { * or "month". It is related to Timestamp in that the difference between * two Timestamp values is a Duration and it can be added or subtracted * from a Timestamp. Range is approximately +-10,000 years. - * + * * Example 1: Compute Duration from two Timestamps in pseudo code. - * + * * Timestamp start = ...; * Timestamp end = ...; * Duration duration = ...; - * + * * duration.seconds = end.seconds - start.seconds; * duration.nanos = end.nanos - start.nanos; - * + * * if (duration.seconds < 0 && duration.nanos > 0) { * duration.seconds += 1; * duration.nanos -= 1000000000; @@ -72,16 +72,16 @@ typedef GPB_ENUM(GPBDuration_FieldNumber) { * duration.seconds -= 1; * duration.nanos += 1000000000; * } - * + * * Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. - * + * * Timestamp start = ...; * Duration duration = ...; * Timestamp end = ...; - * + * * end.seconds = start.seconds + duration.seconds; * end.nanos = start.nanos + duration.nanos; - * + * * if (end.nanos < 0) { * end.seconds -= 1; * end.nanos += 1000000000; diff --git a/objectivec/google/protobuf/Empty.pbobjc.h b/objectivec/google/protobuf/Empty.pbobjc.h index d85efd2c25..4d36174d32 100644 --- a/objectivec/google/protobuf/Empty.pbobjc.h +++ b/objectivec/google/protobuf/Empty.pbobjc.h @@ -47,11 +47,11 @@ NS_ASSUME_NONNULL_BEGIN * A generic empty message that you can re-use to avoid defining duplicated * empty messages in your APIs. A typical example is to use it as the request * or the response type of an API method. For instance: - * + * * service Foo { * rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); * } - * + * * The JSON representation for `Empty` is empty JSON object `{}`. **/ @interface GPBEmpty : GPBMessage diff --git a/objectivec/google/protobuf/FieldMask.pbobjc.h b/objectivec/google/protobuf/FieldMask.pbobjc.h index 175db600f4..491463f98a 100644 --- a/objectivec/google/protobuf/FieldMask.pbobjc.h +++ b/objectivec/google/protobuf/FieldMask.pbobjc.h @@ -49,25 +49,25 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) { /** * `FieldMask` represents a set of symbolic field paths, for example: - * + * * paths: "f.a" * paths: "f.b.d" - * + * * Here `f` represents a field in some root message, `a` and `b` * fields in the message found in `f`, and `d` a field found in the * message in `f.b`. - * + * * Field masks are used to specify a subset of fields that should be * returned by a get operation or modified by an update operation. * Field masks also have a custom JSON encoding (see below). - * + * * # Field Masks in Projections - * + * * When used in the context of a projection, a response message or * sub-message is filtered by the API to only contain those fields as * specified in the mask. For example, if the mask in the previous * example is applied to a response message as follows: - * + * * f { * a : 22 * b { @@ -77,26 +77,26 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) { * y : 13 * } * z: 8 - * + * * The result will not contain specific values for fields x,y and z * (their value will be set to the default, and omitted in proto text * output): - * - * + * + * * f { * a : 22 * b { * d : 1 * } * } - * + * * A repeated field is not allowed except at the last position of a * field mask. - * + * * If a FieldMask object is not present in a get operation, the * operation applies to all fields (as if a FieldMask of all fields * had been specified). - * + * * Note that a field mask does not necessarily apply to the * top-level response message. In case of a REST get operation, the * field mask applies directly to the response, but in case of a REST @@ -106,25 +106,25 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) { * clearly documented together with its declaration in the API. In * any case, the effect on the returned resource/resources is required * behavior for APIs. - * + * * # Field Masks in Update Operations - * + * * A field mask in update operations specifies which fields of the * targeted resource are going to be updated. The API is required * to only change the values of the fields as specified in the mask * and leave the others untouched. If a resource is passed in to * describe the updated values, the API ignores the values of all * fields not covered by the mask. - * + * * If a repeated field is specified for an update operation, the existing * repeated values in the target resource will be overwritten by the new values. * Note that a repeated field is only allowed in the last position of a field * mask. - * + * * If a sub-message is specified in the last position of the field mask for an * update operation, then the existing sub-message in the target resource is * overwritten. Given the target message: - * + * * f { * b { * d : 1 @@ -132,34 +132,34 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) { * } * c : 1 * } - * + * * And an update message: - * + * * f { * b { * d : 10 * } * } - * + * * then if the field mask is: - * + * * paths: "f.b" - * + * * then the result will be: - * + * * f { * b { * d : 10 * } * c : 1 * } - * + * * However, if the update mask was: - * + * * paths: "f.b.d" - * + * * then the result would be: - * + * * f { * b { * d : 10 @@ -167,13 +167,13 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) { * } * c : 1 * } - * + * * In order to reset a field's value to the default, the field must * be in the mask and set to the default value in the provided resource. * Hence, in order to reset all fields of a resource, provide a default * instance of the resource and set all fields in the mask, or do * not provide a mask as described below. - * + * * If a field mask is not present on update, the operation applies to * all fields (as if a field mask of all fields has been specified). * Note that in the presence of schema evolution, this may mean that @@ -181,26 +181,26 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) { * the request will be reset to their default. If this is unwanted * behavior, a specific service may require a client to always specify * a field mask, producing an error if not. - * + * * As with get operations, the location of the resource which * describes the updated values in the request message depends on the * operation kind. In any case, the effect of the field mask is * required to be honored by the API. - * + * * ## Considerations for HTTP REST - * + * * The HTTP kind of an update operation which uses a field mask must * be set to PATCH instead of PUT in order to satisfy HTTP semantics * (PUT must only be used for full updates). - * + * * # JSON Encoding of Field Masks - * + * * In JSON, a field mask is encoded as a single string where paths are * separated by a comma. Fields name in each path are converted * to/from lower-camel naming conventions. - * + * * As an example, consider the following message declarations: - * + * * message Profile { * User user = 1; * Photo photo = 2; @@ -209,44 +209,44 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) { * string display_name = 1; * string address = 2; * } - * + * * In proto a field mask for `Profile` may look as such: - * + * * mask { * paths: "user.display_name" * paths: "photo" * } - * + * * In JSON, the same mask is represented as below: - * + * * { * mask: "user.displayName,photo" * } - * + * * # Field Masks and Oneof Fields - * + * * Field masks treat fields in oneofs just as regular fields. Consider the * following message: - * + * * message SampleMessage { * oneof test_oneof { * string name = 4; * SubMessage sub_message = 9; * } * } - * + * * The field mask can be: - * + * * mask { * paths: "name" * } - * + * * Or: - * + * * mask { * paths: "sub_message" * } - * + * * Note that oneof type names ("test_oneof" in this case) cannot be used in * paths. **/ diff --git a/objectivec/google/protobuf/Struct.pbobjc.h b/objectivec/google/protobuf/Struct.pbobjc.h index 670e049dd1..a5b31cd057 100644 --- a/objectivec/google/protobuf/Struct.pbobjc.h +++ b/objectivec/google/protobuf/Struct.pbobjc.h @@ -35,7 +35,7 @@ NS_ASSUME_NONNULL_BEGIN /** * `NullValue` is a singleton enumeration to represent the null value for the * `Value` type union. - * + * * The JSON representation for `NullValue` is JSON `null`. **/ typedef GPB_ENUM(GPBNullValue) { @@ -85,7 +85,7 @@ typedef GPB_ENUM(GPBStruct_FieldNumber) { * scripting languages like JS a struct is represented as an * object. The details of that representation are described together * with the proto support for the language. - * + * * The JSON representation for `Struct` is JSON object. **/ @interface GPBStruct : GPBMessage @@ -123,7 +123,7 @@ typedef GPB_ENUM(GPBValue_Kind_OneOfCase) { * null, a number, a string, a boolean, a recursive struct value, or a * list of values. A producer of value is expected to set one of that * variants, absence of any variant indicates an error. - * + * * The JSON representation for `Value` is JSON value. **/ @interface GPBValue : GPBMessage @@ -176,7 +176,7 @@ typedef GPB_ENUM(GPBListValue_FieldNumber) { /** * `ListValue` is a wrapper around a repeated field of values. - * + * * The JSON representation for `ListValue` is JSON array. **/ @interface GPBListValue : GPBMessage diff --git a/objectivec/google/protobuf/Timestamp.pbobjc.h b/objectivec/google/protobuf/Timestamp.pbobjc.h index 352c260b88..ebfa670ffd 100644 --- a/objectivec/google/protobuf/Timestamp.pbobjc.h +++ b/objectivec/google/protobuf/Timestamp.pbobjc.h @@ -60,44 +60,44 @@ typedef GPB_ENUM(GPBTimestamp_FieldNumber) { * By restricting to that range, we ensure that we can convert to * and from RFC 3339 date strings. * See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). - * + * * Example 1: Compute Timestamp from POSIX `time()`. - * + * * Timestamp timestamp; * timestamp.set_seconds(time(NULL)); * timestamp.set_nanos(0); - * + * * Example 2: Compute Timestamp from POSIX `gettimeofday()`. - * + * * struct timeval tv; * gettimeofday(&tv, NULL); - * + * * Timestamp timestamp; * timestamp.set_seconds(tv.tv_sec); * timestamp.set_nanos(tv.tv_usec * 1000); - * + * * Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. - * + * * FILETIME ft; * GetSystemTimeAsFileTime(&ft); * UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; - * + * * // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z * // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. * Timestamp timestamp; * timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); * timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); - * + * * Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. - * + * * long millis = System.currentTimeMillis(); - * + * * Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) * .setNanos((int) ((millis % 1000) * 1000000)).build(); - * - * + * + * * Example 5: Compute Timestamp from current time in Python. - * + * * now = time.time() * seconds = int(now) * nanos = int((now - seconds) * 10**9) diff --git a/objectivec/google/protobuf/Wrappers.pbobjc.h b/objectivec/google/protobuf/Wrappers.pbobjc.h index fc7d5abe42..e397c480f9 100644 --- a/objectivec/google/protobuf/Wrappers.pbobjc.h +++ b/objectivec/google/protobuf/Wrappers.pbobjc.h @@ -49,7 +49,7 @@ typedef GPB_ENUM(GPBDoubleValue_FieldNumber) { /** * Wrapper message for `double`. - * + * * The JSON representation for `DoubleValue` is JSON number. **/ @interface GPBDoubleValue : GPBMessage @@ -67,7 +67,7 @@ typedef GPB_ENUM(GPBFloatValue_FieldNumber) { /** * Wrapper message for `float`. - * + * * The JSON representation for `FloatValue` is JSON number. **/ @interface GPBFloatValue : GPBMessage @@ -85,7 +85,7 @@ typedef GPB_ENUM(GPBInt64Value_FieldNumber) { /** * Wrapper message for `int64`. - * + * * The JSON representation for `Int64Value` is JSON string. **/ @interface GPBInt64Value : GPBMessage @@ -103,7 +103,7 @@ typedef GPB_ENUM(GPBUInt64Value_FieldNumber) { /** * Wrapper message for `uint64`. - * + * * The JSON representation for `UInt64Value` is JSON string. **/ @interface GPBUInt64Value : GPBMessage @@ -121,7 +121,7 @@ typedef GPB_ENUM(GPBInt32Value_FieldNumber) { /** * Wrapper message for `int32`. - * + * * The JSON representation for `Int32Value` is JSON number. **/ @interface GPBInt32Value : GPBMessage @@ -139,7 +139,7 @@ typedef GPB_ENUM(GPBUInt32Value_FieldNumber) { /** * Wrapper message for `uint32`. - * + * * The JSON representation for `UInt32Value` is JSON number. **/ @interface GPBUInt32Value : GPBMessage @@ -157,7 +157,7 @@ typedef GPB_ENUM(GPBBoolValue_FieldNumber) { /** * Wrapper message for `bool`. - * + * * The JSON representation for `BoolValue` is JSON `true` and `false`. **/ @interface GPBBoolValue : GPBMessage @@ -175,7 +175,7 @@ typedef GPB_ENUM(GPBStringValue_FieldNumber) { /** * Wrapper message for `string`. - * + * * The JSON representation for `StringValue` is JSON string. **/ @interface GPBStringValue : GPBMessage @@ -193,7 +193,7 @@ typedef GPB_ENUM(GPBBytesValue_FieldNumber) { /** * Wrapper message for `bytes`. - * + * * The JSON representation for `BytesValue` is JSON string. **/ @interface GPBBytesValue : GPBMessage diff --git a/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc b/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc index 28b3f5aecd..4a94373aec 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc @@ -850,14 +850,17 @@ string BuildCommentsString(const SourceLocation& location, string final_comments; string epilogue; + bool add_leading_space = false; + if (prefer_single_line && lines.size() == 1) { prefix = "/** "; suffix = " */\n"; } else { - prefix = " * "; + prefix = "* "; suffix = "\n"; final_comments += "/**\n"; epilogue = " **/\n"; + add_leading_space = true; } for (int i = 0; i < lines.size(); i++) { @@ -868,7 +871,12 @@ string BuildCommentsString(const SourceLocation& location, // Decouple / from * to not have inline comments inside comments. line = StringReplace(line, "/*", "/\\*", true); line = StringReplace(line, "*/", "*\\/", true); - final_comments += prefix + line + suffix; + line = prefix + line; + StripWhitespace(&line); + // If not a one line, need to add the first space before *, as + // StripWhitespace would have removed it. + line = (add_leading_space ? " " : "") + line; + final_comments += line + suffix; } final_comments += epilogue; return final_comments;