From 237f321e338b50503eb38728afa6ad29bea6076a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sergio=20Campam=C3=A1?= Date: Tue, 9 Aug 2016 05:26:24 -0700 Subject: [PATCH] Adds support for appledoc in generated code. (#1928) Convert mapping of proto comments to appledoc format so they show up in Xcode and cocoadocs. Fixes https://github.com/google/protobuf/issues/1866 --- objectivec/Tests/unittest_objc.proto | 9 + objectivec/google/protobuf/Any.pbobjc.h | 204 +++++---- objectivec/google/protobuf/Api.pbobjc.h | 304 +++++++------ objectivec/google/protobuf/Duration.pbobjc.h | 120 ++--- objectivec/google/protobuf/Empty.pbobjc.h | 38 +- objectivec/google/protobuf/FieldMask.pbobjc.h | 426 +++++++++--------- .../google/protobuf/SourceContext.pbobjc.h | 30 +- objectivec/google/protobuf/Struct.pbobjc.h | 124 ++--- objectivec/google/protobuf/Timestamp.pbobjc.h | 144 +++--- objectivec/google/protobuf/Type.pbobjc.h | 274 ++++++----- objectivec/google/protobuf/Wrappers.pbobjc.h | 108 +++-- .../compiler/objectivec/objectivec_enum.cc | 18 +- .../objectivec/objectivec_enum_field.cc | 14 +- .../objectivec/objectivec_extension.cc | 2 +- .../compiler/objectivec/objectivec_field.cc | 6 +- .../compiler/objectivec/objectivec_file.cc | 18 +- .../compiler/objectivec/objectivec_helpers.cc | 39 +- .../compiler/objectivec/objectivec_helpers.h | 6 +- .../compiler/objectivec/objectivec_message.cc | 2 +- .../compiler/objectivec/objectivec_oneof.cc | 6 +- 20 files changed, 1041 insertions(+), 851 deletions(-) diff --git a/objectivec/Tests/unittest_objc.proto b/objectivec/Tests/unittest_objc.proto index 914945ebd3..e5577faf0d 100644 --- a/objectivec/Tests/unittest_objc.proto +++ b/objectivec/Tests/unittest_objc.proto @@ -34,6 +34,15 @@ import "google/protobuf/unittest.proto"; package protobuf_unittest; +// Used to check that Headerdocs and appledoc work correctly. If these comments +// are not handled correctly, Xcode will fail to build the tests. +message TestGeneratedComments { + // This is a string that could contain stuff like + // mime types as image/* or */plain. Maybe twitter usernames + // like @protobuf, @google or @something. + optional string string_field = 1; +} + // Using the messages in unittest.proto, setup for recursive cases for testing // extensions at various depths. extend TestAllExtensions { diff --git a/objectivec/google/protobuf/Any.pbobjc.h b/objectivec/google/protobuf/Any.pbobjc.h index 4253b604ee..940206b651 100644 --- a/objectivec/google/protobuf/Any.pbobjc.h +++ b/objectivec/google/protobuf/Any.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBAnyRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBAnyRoot : GPBRootObject @end @@ -46,101 +48,105 @@ typedef GPB_ENUM(GPBAny_FieldNumber) { GPBAny_FieldNumber_Value = 2, }; -/// `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); -/// ... -/// 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) -/// ... -/// 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" -/// } +/** + * `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); + * ... + * 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) + * ... + * 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" + * } + **/ @interface GPBAny : GPBMessage -/// 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`). -/// 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 -/// URL, or have them precompiled into a binary to avoid any -/// 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. +/** + * 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`). + * 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 + * URL, or have them precompiled into a binary to avoid any + * 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. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *typeURL; -/// Must be a valid serialized protocol buffer of the above specified type. +/** Must be a valid serialized protocol buffer of the above specified type. */ @property(nonatomic, readwrite, copy, null_resettable) NSData *value; @end diff --git a/objectivec/google/protobuf/Api.pbobjc.h b/objectivec/google/protobuf/Api.pbobjc.h index 04341f4741..3dda769877 100644 --- a/objectivec/google/protobuf/Api.pbobjc.h +++ b/objectivec/google/protobuf/Api.pbobjc.h @@ -34,14 +34,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBApiRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBApiRoot : GPBRootObject @end @@ -57,67 +59,79 @@ typedef GPB_ENUM(GPBApi_FieldNumber) { GPBApi_FieldNumber_Syntax = 7, }; -/// Api is a light-weight descriptor for a protocol buffer service. +/** + * Api is a light-weight descriptor for a protocol buffer service. + **/ @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 api, including package name + * followed by the api's simple name. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The methods of this api, in unspecified order. +/** The methods of this api, in unspecified order. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *methodsArray; -/// The number of items in @c methodsArray without causing the array to be created. +/** 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 API. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** 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. -/// -/// 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 -/// be omitted. Zero major versions must only be used for -/// experimental, none-GA apis. +/** + * 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. + * + * 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 + * be omitted. Zero major versions must only be used for + * experimental, none-GA apis. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *version; -/// Source context for the protocol buffer service represented by this -/// message. +/** + * Source context for the protocol buffer service represented by this + * message. + **/ @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext; -/// Test to see if @c sourceContext has been set. +/** Test to see if @c sourceContext has been set. */ @property(nonatomic, readwrite) BOOL hasSourceContext; -/// Included APIs. See [Mixin][]. +/** Included APIs. See [Mixin][]. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *mixinsArray; -/// The number of items in @c mixinsArray without causing the array to be created. +/** The number of items in @c mixinsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger mixinsArray_Count; -/// The source syntax of the service. +/** The source syntax of the service. */ @property(nonatomic, readwrite) enum GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBApi's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBApi's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBApi_Syntax_RawValue(GPBApi *message); -/// Sets the raw value of an @c GPBApi's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBApi's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBApi_Syntax_RawValue(GPBApi *message, int32_t value); #pragma mark - GPBMethod @@ -132,40 +146,46 @@ typedef GPB_ENUM(GPBMethod_FieldNumber) { GPBMethod_FieldNumber_Syntax = 7, }; -/// Method represents a method of an api. +/** + * Method represents a method of an api. + **/ @interface GPBMethod : GPBMessage -/// The simple name of this method. +/** The simple name of this method. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// A URL of the input message type. +/** A URL of the input message type. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *requestTypeURL; -/// If true, the request is streamed. +/** If true, the request is streamed. */ @property(nonatomic, readwrite) BOOL requestStreaming; -/// The URL of the output message type. +/** The URL of the output message type. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *responseTypeURL; -/// If true, the response is streamed. +/** If true, the response is streamed. */ @property(nonatomic, readwrite) BOOL responseStreaming; -/// Any metadata attached to the method. +/** Any metadata attached to the method. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The source syntax of this method. +/** The source syntax of this method. */ @property(nonatomic, readwrite) enum GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBMethod's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBMethod's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBMethod_Syntax_RawValue(GPBMethod *message); -/// Sets the raw value of an @c GPBMethod's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBMethod's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBMethod_Syntax_RawValue(GPBMethod *message, int32_t value); #pragma mark - GPBMixin @@ -175,90 +195,94 @@ typedef GPB_ENUM(GPBMixin_FieldNumber) { GPBMixin_FieldNumber_Root = 2, }; -/// 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. -/// rpc GetAcl(GetAclRequest) returns (Acl) { -/// 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) { -/// option (google.api.http).get = "/v2/{resource=**}:getAcl"; -/// } -/// ... -/// } -/// -/// 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) { -/// option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; -/// } -/// ... -/// } +/** + * 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. + * rpc GetAcl(GetAclRequest) returns (Acl) { + * 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) { + * option (google.api.http).get = "/v2/{resource=**}:getAcl"; + * } + * ... + * } + * + * 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) { + * option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; + * } + * ... + * } + **/ @interface GPBMixin : GPBMessage -/// The fully qualified name of the API which is included. +/** The fully qualified name of the API which is included. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// If non-empty specifies a path under which inherited HTTP paths -/// are rooted. +/** + * If non-empty specifies a path under which inherited HTTP paths + * are rooted. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *root; @end diff --git a/objectivec/google/protobuf/Duration.pbobjc.h b/objectivec/google/protobuf/Duration.pbobjc.h index 4c3173d3e4..8f9b351589 100644 --- a/objectivec/google/protobuf/Duration.pbobjc.h +++ b/objectivec/google/protobuf/Duration.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBDurationRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBDurationRoot : GPBRootObject @end @@ -46,58 +48,64 @@ typedef GPB_ENUM(GPBDuration_FieldNumber) { GPBDuration_FieldNumber_Nanos = 2, }; -/// A Duration represents a signed, fixed-length span of time represented -/// as a count of seconds and fractions of seconds at nanosecond -/// resolution. It is independent of any calendar and concepts like "day" -/// 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; -/// } else if (durations.seconds > 0 && duration.nanos < 0) { -/// 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; -/// } else if (end.nanos >= 1000000000) { -/// end.seconds += 1; -/// end.nanos -= 1000000000; -/// } +/** + * A Duration represents a signed, fixed-length span of time represented + * as a count of seconds and fractions of seconds at nanosecond + * resolution. It is independent of any calendar and concepts like "day" + * 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; + * } else if (durations.seconds > 0 && duration.nanos < 0) { + * 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; + * } else if (end.nanos >= 1000000000) { + * end.seconds += 1; + * end.nanos -= 1000000000; + * } + **/ @interface GPBDuration : GPBMessage -/// Signed seconds of the span of time. Must be from -315,576,000,000 -/// to +315,576,000,000 inclusive. +/** + * Signed seconds of the span of time. Must be from -315,576,000,000 + * to +315,576,000,000 inclusive. + **/ @property(nonatomic, readwrite) int64_t seconds; -/// Signed fractions of a second at nanosecond resolution of the span -/// of time. Durations less than one second are represented with a 0 -/// `seconds` field and a positive or negative `nanos` field. For durations -/// of one second or more, a non-zero value for the `nanos` field must be -/// of the same sign as the `seconds` field. Must be from -999,999,999 -/// to +999,999,999 inclusive. +/** + * Signed fractions of a second at nanosecond resolution of the span + * of time. Durations less than one second are represented with a 0 + * `seconds` field and a positive or negative `nanos` field. For durations + * of one second or more, a non-zero value for the `nanos` field must be + * of the same sign as the `seconds` field. Must be from -999,999,999 + * to +999,999,999 inclusive. + **/ @property(nonatomic, readwrite) int32_t nanos; @end diff --git a/objectivec/google/protobuf/Empty.pbobjc.h b/objectivec/google/protobuf/Empty.pbobjc.h index 2d2a86bc7e..d85efd2c25 100644 --- a/objectivec/google/protobuf/Empty.pbobjc.h +++ b/objectivec/google/protobuf/Empty.pbobjc.h @@ -28,28 +28,32 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBEmptyRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBEmptyRoot : GPBRootObject @end #pragma mark - GPBEmpty -/// 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 `{}`. +/** + * 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 @end diff --git a/objectivec/google/protobuf/FieldMask.pbobjc.h b/objectivec/google/protobuf/FieldMask.pbobjc.h index 06053f1a5a..175db600f4 100644 --- a/objectivec/google/protobuf/FieldMask.pbobjc.h +++ b/objectivec/google/protobuf/FieldMask.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBFieldMaskRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBFieldMaskRoot : GPBRootObject @end @@ -45,212 +47,214 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) { GPBFieldMask_FieldNumber_PathsArray = 1, }; -/// `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 { -/// d : 1 -/// x : 2 -/// } -/// 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 -/// list operation, the mask instead applies to each individual message -/// in the returned resource list. In case of a REST custom method, -/// other definitions may be used. Where the mask applies will be -/// 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 -/// x : 2 -/// } -/// 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 -/// x : 2 -/// } -/// 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 -/// fields the client does not know and has therefore not filled into -/// 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; -/// } -/// message User { -/// 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. +/** + * `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 { + * d : 1 + * x : 2 + * } + * 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 + * list operation, the mask instead applies to each individual message + * in the returned resource list. In case of a REST custom method, + * other definitions may be used. Where the mask applies will be + * 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 + * x : 2 + * } + * 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 + * x : 2 + * } + * 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 + * fields the client does not know and has therefore not filled into + * 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; + * } + * message User { + * 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. + **/ @interface GPBFieldMask : GPBMessage -/// The set of field mask paths. +/** The set of field mask paths. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *pathsArray; -/// The number of items in @c pathsArray without causing the array to be created. +/** The number of items in @c pathsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger pathsArray_Count; @end diff --git a/objectivec/google/protobuf/SourceContext.pbobjc.h b/objectivec/google/protobuf/SourceContext.pbobjc.h index 4514fa9f16..d9450057e1 100644 --- a/objectivec/google/protobuf/SourceContext.pbobjc.h +++ b/objectivec/google/protobuf/SourceContext.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBSourceContextRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBSourceContextRoot : GPBRootObject @end @@ -45,12 +47,16 @@ typedef GPB_ENUM(GPBSourceContext_FieldNumber) { GPBSourceContext_FieldNumber_FileName = 1, }; -/// `SourceContext` represents information about the source of a -/// protobuf element, like the file in which it is defined. +/** + * `SourceContext` represents information about the source of a + * protobuf element, like the file in which it is defined. + **/ @interface GPBSourceContext : GPBMessage -/// The path-qualified name of the .proto file that contained the associated -/// protobuf element. For example: `"google/protobuf/source_context.proto"`. +/** + * The path-qualified name of the .proto file that contained the associated + * protobuf element. For example: `"google/protobuf/source_context.proto"`. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *fileName; @end diff --git a/objectivec/google/protobuf/Struct.pbobjc.h b/objectivec/google/protobuf/Struct.pbobjc.h index 3e2d55fdda..670e049dd1 100644 --- a/objectivec/google/protobuf/Struct.pbobjc.h +++ b/objectivec/google/protobuf/Struct.pbobjc.h @@ -32,35 +32,43 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Enum GPBNullValue -/// `NullValue` is a singleton enumeration to represent the null value for the -/// `Value` type union. -/// -/// The JSON representation for `NullValue` is JSON `null`. +/** + * `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) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBNullValue_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// Null value. + /** Null value. */ GPBNullValue_NullValue = 0, }; GPBEnumDescriptor *GPBNullValue_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBNullValue_IsValidValue(int32_t value); #pragma mark - GPBStructRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBStructRoot : GPBRootObject @end @@ -70,19 +78,21 @@ typedef GPB_ENUM(GPBStruct_FieldNumber) { GPBStruct_FieldNumber_Fields = 1, }; -/// `Struct` represents a structured data value, consisting of fields -/// which map to dynamically typed values. In some languages, `Struct` -/// might be supported by a native representation. For example, in -/// 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. +/** + * `Struct` represents a structured data value, consisting of fields + * which map to dynamically typed values. In some languages, `Struct` + * might be supported by a native representation. For example, in + * 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 -/// Unordered map of dynamically typed values. +/** Unordered map of dynamically typed values. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableDictionary *fields; -/// The number of items in @c fields without causing the array to be created. +/** The number of items in @c fields without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger fields_Count; @end @@ -108,46 +118,54 @@ typedef GPB_ENUM(GPBValue_Kind_OneOfCase) { GPBValue_Kind_OneOfCase_ListValue = 6, }; -/// `Value` represents a dynamically typed value which can be either -/// 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. +/** + * `Value` represents a dynamically typed value which can be either + * 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 -/// The kind of value. +/** The kind of value. */ @property(nonatomic, readonly) GPBValue_Kind_OneOfCase kindOneOfCase; -/// Represents a null value. +/** Represents a null value. */ @property(nonatomic, readwrite) GPBNullValue nullValue; -/// Represents a double value. +/** Represents a double value. */ @property(nonatomic, readwrite) double numberValue; -/// Represents a string value. +/** Represents a string value. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *stringValue; -/// Represents a boolean value. +/** Represents a boolean value. */ @property(nonatomic, readwrite) BOOL boolValue; -/// Represents a structured value. +/** Represents a structured value. */ @property(nonatomic, readwrite, strong, null_resettable) GPBStruct *structValue; -/// Represents a repeated `Value`. +/** Represents a repeated `Value`. */ @property(nonatomic, readwrite, strong, null_resettable) GPBListValue *listValue; @end -/// Fetches the raw value of a @c GPBValue's @c nullValue property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBValue's @c nullValue property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBValue_NullValue_RawValue(GPBValue *message); -/// Sets the raw value of an @c GPBValue's @c nullValue property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBValue's @c nullValue property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBValue_NullValue_RawValue(GPBValue *message, int32_t value); -/// Clears whatever value was set for the oneof 'kind'. +/** + * Clears whatever value was set for the oneof 'kind'. + **/ void GPBValue_ClearKindOneOfCase(GPBValue *message); #pragma mark - GPBListValue @@ -156,14 +174,16 @@ typedef GPB_ENUM(GPBListValue_FieldNumber) { GPBListValue_FieldNumber_ValuesArray = 1, }; -/// `ListValue` is a wrapper around a repeated field of values. -/// -/// The JSON representation for `ListValue` is JSON array. +/** + * `ListValue` is a wrapper around a repeated field of values. + * + * The JSON representation for `ListValue` is JSON array. + **/ @interface GPBListValue : GPBMessage -/// Repeated field of dynamically typed values. +/** Repeated field of dynamically typed values. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *valuesArray; -/// The number of items in @c valuesArray without causing the array to be created. +/** The number of items in @c valuesArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger valuesArray_Count; @end diff --git a/objectivec/google/protobuf/Timestamp.pbobjc.h b/objectivec/google/protobuf/Timestamp.pbobjc.h index d15de7c701..352c260b88 100644 --- a/objectivec/google/protobuf/Timestamp.pbobjc.h +++ b/objectivec/google/protobuf/Timestamp.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBTimestampRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBTimestampRoot : GPBRootObject @end @@ -46,70 +48,76 @@ typedef GPB_ENUM(GPBTimestamp_FieldNumber) { GPBTimestamp_FieldNumber_Nanos = 2, }; -/// A Timestamp represents a point in time independent of any time zone -/// or calendar, represented as seconds and fractions of seconds at -/// nanosecond resolution in UTC Epoch time. It is encoded using the -/// Proleptic Gregorian Calendar which extends the Gregorian calendar -/// backwards to year one. It is encoded assuming all minutes are 60 -/// seconds long, i.e. leap seconds are "smeared" so that no leap second -/// table is needed for interpretation. Range is from -/// 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. -/// 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) -/// timestamp = Timestamp(seconds=seconds, nanos=nanos) +/** + * A Timestamp represents a point in time independent of any time zone + * or calendar, represented as seconds and fractions of seconds at + * nanosecond resolution in UTC Epoch time. It is encoded using the + * Proleptic Gregorian Calendar which extends the Gregorian calendar + * backwards to year one. It is encoded assuming all minutes are 60 + * seconds long, i.e. leap seconds are "smeared" so that no leap second + * table is needed for interpretation. Range is from + * 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. + * 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) + * timestamp = Timestamp(seconds=seconds, nanos=nanos) + **/ @interface GPBTimestamp : GPBMessage -/// Represents seconds of UTC time since Unix epoch -/// 1970-01-01T00:00:00Z. Must be from from 0001-01-01T00:00:00Z to -/// 9999-12-31T23:59:59Z inclusive. +/** + * Represents seconds of UTC time since Unix epoch + * 1970-01-01T00:00:00Z. Must be from from 0001-01-01T00:00:00Z to + * 9999-12-31T23:59:59Z inclusive. + **/ @property(nonatomic, readwrite) int64_t seconds; -/// Non-negative fractions of a second at nanosecond resolution. Negative -/// second values with fractions must still have non-negative nanos values -/// that count forward in time. Must be from 0 to 999,999,999 -/// inclusive. +/** + * Non-negative fractions of a second at nanosecond resolution. Negative + * second values with fractions must still have non-negative nanos values + * that count forward in time. Must be from 0 to 999,999,999 + * inclusive. + **/ @property(nonatomic, readwrite) int32_t nanos; @end diff --git a/objectivec/google/protobuf/Type.pbobjc.h b/objectivec/google/protobuf/Type.pbobjc.h index 93ee3cece5..0541195897 100644 --- a/objectivec/google/protobuf/Type.pbobjc.h +++ b/objectivec/google/protobuf/Type.pbobjc.h @@ -34,134 +34,148 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Enum GPBSyntax -/// The syntax in which a protocol buffer element is defined. +/** The syntax in which a protocol buffer element is defined. */ typedef GPB_ENUM(GPBSyntax) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBSyntax_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// Syntax `proto2`. + /** Syntax `proto2`. */ GPBSyntax_SyntaxProto2 = 0, - /// Syntax `proto3`. + /** Syntax `proto3`. */ GPBSyntax_SyntaxProto3 = 1, }; GPBEnumDescriptor *GPBSyntax_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBSyntax_IsValidValue(int32_t value); #pragma mark - Enum GPBField_Kind -/// Basic field types. +/** Basic field types. */ typedef GPB_ENUM(GPBField_Kind) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBField_Kind_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// Field type unknown. + /** Field type unknown. */ GPBField_Kind_TypeUnknown = 0, - /// Field type double. + /** Field type double. */ GPBField_Kind_TypeDouble = 1, - /// Field type float. + /** Field type float. */ GPBField_Kind_TypeFloat = 2, - /// Field type int64. + /** Field type int64. */ GPBField_Kind_TypeInt64 = 3, - /// Field type uint64. + /** Field type uint64. */ GPBField_Kind_TypeUint64 = 4, - /// Field type int32. + /** Field type int32. */ GPBField_Kind_TypeInt32 = 5, - /// Field type fixed64. + /** Field type fixed64. */ GPBField_Kind_TypeFixed64 = 6, - /// Field type fixed32. + /** Field type fixed32. */ GPBField_Kind_TypeFixed32 = 7, - /// Field type bool. + /** Field type bool. */ GPBField_Kind_TypeBool = 8, - /// Field type string. + /** Field type string. */ GPBField_Kind_TypeString = 9, - /// Field type group. Proto2 syntax only, and deprecated. + /** Field type group. Proto2 syntax only, and deprecated. */ GPBField_Kind_TypeGroup = 10, - /// Field type message. + /** Field type message. */ GPBField_Kind_TypeMessage = 11, - /// Field type bytes. + /** Field type bytes. */ GPBField_Kind_TypeBytes = 12, - /// Field type uint32. + /** Field type uint32. */ GPBField_Kind_TypeUint32 = 13, - /// Field type enum. + /** Field type enum. */ GPBField_Kind_TypeEnum = 14, - /// Field type sfixed32. + /** Field type sfixed32. */ GPBField_Kind_TypeSfixed32 = 15, - /// Field type sfixed64. + /** Field type sfixed64. */ GPBField_Kind_TypeSfixed64 = 16, - /// Field type sint32. + /** Field type sint32. */ GPBField_Kind_TypeSint32 = 17, - /// Field type sint64. + /** Field type sint64. */ GPBField_Kind_TypeSint64 = 18, }; GPBEnumDescriptor *GPBField_Kind_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBField_Kind_IsValidValue(int32_t value); #pragma mark - Enum GPBField_Cardinality -/// Whether a field is optional, required, or repeated. +/** Whether a field is optional, required, or repeated. */ typedef GPB_ENUM(GPBField_Cardinality) { - /// Value used if any message's field encounters a value that is not defined - /// by this enum. The message will also have C functions to get/set the rawValue - /// of the field. + /** + * Value used if any message's field encounters a value that is not defined + * by this enum. The message will also have C functions to get/set the rawValue + * of the field. + **/ GPBField_Cardinality_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue, - /// For fields with unknown cardinality. + /** For fields with unknown cardinality. */ GPBField_Cardinality_CardinalityUnknown = 0, - /// For optional fields. + /** For optional fields. */ GPBField_Cardinality_CardinalityOptional = 1, - /// For required fields. Proto2 syntax only. + /** For required fields. Proto2 syntax only. */ GPBField_Cardinality_CardinalityRequired = 2, - /// For repeated fields. + /** For repeated fields. */ GPBField_Cardinality_CardinalityRepeated = 3, }; GPBEnumDescriptor *GPBField_Cardinality_EnumDescriptor(void); -/// Checks to see if the given value is defined by the enum or was not known at -/// the time this source was generated. +/** + * Checks to see if the given value is defined by the enum or was not known at + * the time this source was generated. + **/ BOOL GPBField_Cardinality_IsValidValue(int32_t value); #pragma mark - GPBTypeRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBTypeRoot : GPBRootObject @end @@ -176,43 +190,49 @@ typedef GPB_ENUM(GPBType_FieldNumber) { GPBType_FieldNumber_Syntax = 6, }; -/// A protocol buffer message type. +/** + * A protocol buffer message type. + **/ @interface GPBType : GPBMessage -/// The fully qualified message name. +/** The fully qualified message name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The list of fields. +/** The list of fields. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *fieldsArray; -/// The number of items in @c fieldsArray without causing the array to be created. +/** The number of items in @c fieldsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger fieldsArray_Count; -/// The list of types appearing in `oneof` definitions in this type. +/** The list of types appearing in `oneof` definitions in this type. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *oneofsArray; -/// The number of items in @c oneofsArray without causing the array to be created. +/** The number of items in @c oneofsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger oneofsArray_Count; -/// The protocol buffer options. +/** The protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The source context. +/** The source context. */ @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext; -/// Test to see if @c sourceContext has been set. +/** Test to see if @c sourceContext has been set. */ @property(nonatomic, readwrite) BOOL hasSourceContext; -/// The source syntax. +/** The source syntax. */ @property(nonatomic, readwrite) GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBType's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBType's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBType_Syntax_RawValue(GPBType *message); -/// Sets the raw value of an @c GPBType's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBType's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBType_Syntax_RawValue(GPBType *message, int32_t value); #pragma mark - GPBField @@ -230,59 +250,73 @@ typedef GPB_ENUM(GPBField_FieldNumber) { GPBField_FieldNumber_DefaultValue = 11, }; -/// A single field of a message type. +/** + * A single field of a message type. + **/ @interface GPBField : GPBMessage -/// The field type. +/** The field type. */ @property(nonatomic, readwrite) GPBField_Kind kind; -/// The field cardinality. +/** The field cardinality. */ @property(nonatomic, readwrite) GPBField_Cardinality cardinality; -/// The field number. +/** The field number. */ @property(nonatomic, readwrite) int32_t number; -/// The field name. +/** The field name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The field type URL, without the scheme, for message or enumeration -/// types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`. +/** + * The field type URL, without the scheme, for message or enumeration + * types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`. + **/ @property(nonatomic, readwrite, copy, null_resettable) NSString *typeURL; -/// The index of the field type in `Type.oneofs`, for message or enumeration -/// types. The first type has index 1; zero means the type is not in the list. +/** + * The index of the field type in `Type.oneofs`, for message or enumeration + * types. The first type has index 1; zero means the type is not in the list. + **/ @property(nonatomic, readwrite) int32_t oneofIndex; -/// Whether to use alternative packed wire representation. +/** Whether to use alternative packed wire representation. */ @property(nonatomic, readwrite) BOOL packed; -/// The protocol buffer options. +/** The protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The field JSON name. +/** The field JSON name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *jsonName; -/// The string value of the default value of this field. Proto2 syntax only. +/** The string value of the default value of this field. Proto2 syntax only. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *defaultValue; @end -/// Fetches the raw value of a @c GPBField's @c kind property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBField's @c kind property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBField_Kind_RawValue(GPBField *message); -/// Sets the raw value of an @c GPBField's @c kind property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBField's @c kind property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBField_Kind_RawValue(GPBField *message, int32_t value); -/// Fetches the raw value of a @c GPBField's @c cardinality property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBField's @c cardinality property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBField_Cardinality_RawValue(GPBField *message); -/// Sets the raw value of an @c GPBField's @c cardinality property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBField's @c cardinality property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBField_Cardinality_RawValue(GPBField *message, int32_t value); #pragma mark - GPBEnum @@ -295,38 +329,44 @@ typedef GPB_ENUM(GPBEnum_FieldNumber) { GPBEnum_FieldNumber_Syntax = 5, }; -/// Enum type definition. +/** + * Enum type definition. + **/ @interface GPBEnum : GPBMessage -/// Enum type name. +/** Enum type name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// Enum value definitions. +/** Enum value definitions. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *enumvalueArray; -/// The number of items in @c enumvalueArray without causing the array to be created. +/** The number of items in @c enumvalueArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger enumvalueArray_Count; -/// Protocol buffer options. +/** Protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; -/// The source context. +/** The source context. */ @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext; -/// Test to see if @c sourceContext has been set. +/** Test to see if @c sourceContext has been set. */ @property(nonatomic, readwrite) BOOL hasSourceContext; -/// The source syntax. +/** The source syntax. */ @property(nonatomic, readwrite) GPBSyntax syntax; @end -/// Fetches the raw value of a @c GPBEnum's @c syntax property, even -/// if the value was not defined by the enum at the time the code was generated. +/** + * Fetches the raw value of a @c GPBEnum's @c syntax property, even + * if the value was not defined by the enum at the time the code was generated. + **/ int32_t GPBEnum_Syntax_RawValue(GPBEnum *message); -/// Sets the raw value of an @c GPBEnum's @c syntax property, allowing -/// it to be set to a value that was not defined by the enum at the time the code -/// was generated. +/** + * Sets the raw value of an @c GPBEnum's @c syntax property, allowing + * it to be set to a value that was not defined by the enum at the time the code + * was generated. + **/ void SetGPBEnum_Syntax_RawValue(GPBEnum *message, int32_t value); #pragma mark - GPBEnumValue @@ -337,18 +377,20 @@ typedef GPB_ENUM(GPBEnumValue_FieldNumber) { GPBEnumValue_FieldNumber_OptionsArray = 3, }; -/// Enum value definition. +/** + * Enum value definition. + **/ @interface GPBEnumValue : GPBMessage -/// Enum value name. +/** Enum value name. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// Enum value number. +/** Enum value number. */ @property(nonatomic, readwrite) int32_t number; -/// Protocol buffer options. +/** Protocol buffer options. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *optionsArray; -/// The number of items in @c optionsArray without causing the array to be created. +/** The number of items in @c optionsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger optionsArray_Count; @end @@ -360,16 +402,18 @@ typedef GPB_ENUM(GPBOption_FieldNumber) { GPBOption_FieldNumber_Value = 2, }; -/// A protocol buffer option, which can be attached to a message, field, -/// enumeration, etc. +/** + * A protocol buffer option, which can be attached to a message, field, + * enumeration, etc. + **/ @interface GPBOption : GPBMessage -/// The option's name. For example, `"java_package"`. +/** The option's name. For example, `"java_package"`. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *name; -/// The option's value. For example, `"com.google.protobuf"`. +/** The option's value. For example, `"com.google.protobuf"`. */ @property(nonatomic, readwrite, strong, null_resettable) GPBAny *value; -/// Test to see if @c value has been set. +/** Test to see if @c value has been set. */ @property(nonatomic, readwrite) BOOL hasValue; @end diff --git a/objectivec/google/protobuf/Wrappers.pbobjc.h b/objectivec/google/protobuf/Wrappers.pbobjc.h index 5593d3489f..fc7d5abe42 100644 --- a/objectivec/google/protobuf/Wrappers.pbobjc.h +++ b/objectivec/google/protobuf/Wrappers.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBWrappersRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBWrappersRoot : GPBRootObject @end @@ -45,12 +47,14 @@ typedef GPB_ENUM(GPBDoubleValue_FieldNumber) { GPBDoubleValue_FieldNumber_Value = 1, }; -/// Wrapper message for `double`. -/// -/// The JSON representation for `DoubleValue` is JSON number. +/** + * Wrapper message for `double`. + * + * The JSON representation for `DoubleValue` is JSON number. + **/ @interface GPBDoubleValue : GPBMessage -/// The double value. +/** The double value. */ @property(nonatomic, readwrite) double value; @end @@ -61,12 +65,14 @@ typedef GPB_ENUM(GPBFloatValue_FieldNumber) { GPBFloatValue_FieldNumber_Value = 1, }; -/// Wrapper message for `float`. -/// -/// The JSON representation for `FloatValue` is JSON number. +/** + * Wrapper message for `float`. + * + * The JSON representation for `FloatValue` is JSON number. + **/ @interface GPBFloatValue : GPBMessage -/// The float value. +/** The float value. */ @property(nonatomic, readwrite) float value; @end @@ -77,12 +83,14 @@ typedef GPB_ENUM(GPBInt64Value_FieldNumber) { GPBInt64Value_FieldNumber_Value = 1, }; -/// Wrapper message for `int64`. -/// -/// The JSON representation for `Int64Value` is JSON string. +/** + * Wrapper message for `int64`. + * + * The JSON representation for `Int64Value` is JSON string. + **/ @interface GPBInt64Value : GPBMessage -/// The int64 value. +/** The int64 value. */ @property(nonatomic, readwrite) int64_t value; @end @@ -93,12 +101,14 @@ typedef GPB_ENUM(GPBUInt64Value_FieldNumber) { GPBUInt64Value_FieldNumber_Value = 1, }; -/// Wrapper message for `uint64`. -/// -/// The JSON representation for `UInt64Value` is JSON string. +/** + * Wrapper message for `uint64`. + * + * The JSON representation for `UInt64Value` is JSON string. + **/ @interface GPBUInt64Value : GPBMessage -/// The uint64 value. +/** The uint64 value. */ @property(nonatomic, readwrite) uint64_t value; @end @@ -109,12 +119,14 @@ typedef GPB_ENUM(GPBInt32Value_FieldNumber) { GPBInt32Value_FieldNumber_Value = 1, }; -/// Wrapper message for `int32`. -/// -/// The JSON representation for `Int32Value` is JSON number. +/** + * Wrapper message for `int32`. + * + * The JSON representation for `Int32Value` is JSON number. + **/ @interface GPBInt32Value : GPBMessage -/// The int32 value. +/** The int32 value. */ @property(nonatomic, readwrite) int32_t value; @end @@ -125,12 +137,14 @@ typedef GPB_ENUM(GPBUInt32Value_FieldNumber) { GPBUInt32Value_FieldNumber_Value = 1, }; -/// Wrapper message for `uint32`. -/// -/// The JSON representation for `UInt32Value` is JSON number. +/** + * Wrapper message for `uint32`. + * + * The JSON representation for `UInt32Value` is JSON number. + **/ @interface GPBUInt32Value : GPBMessage -/// The uint32 value. +/** The uint32 value. */ @property(nonatomic, readwrite) uint32_t value; @end @@ -141,12 +155,14 @@ typedef GPB_ENUM(GPBBoolValue_FieldNumber) { GPBBoolValue_FieldNumber_Value = 1, }; -/// Wrapper message for `bool`. -/// -/// The JSON representation for `BoolValue` is JSON `true` and `false`. +/** + * Wrapper message for `bool`. + * + * The JSON representation for `BoolValue` is JSON `true` and `false`. + **/ @interface GPBBoolValue : GPBMessage -/// The bool value. +/** The bool value. */ @property(nonatomic, readwrite) BOOL value; @end @@ -157,12 +173,14 @@ typedef GPB_ENUM(GPBStringValue_FieldNumber) { GPBStringValue_FieldNumber_Value = 1, }; -/// Wrapper message for `string`. -/// -/// The JSON representation for `StringValue` is JSON string. +/** + * Wrapper message for `string`. + * + * The JSON representation for `StringValue` is JSON string. + **/ @interface GPBStringValue : GPBMessage -/// The string value. +/** The string value. */ @property(nonatomic, readwrite, copy, null_resettable) NSString *value; @end @@ -173,12 +191,14 @@ typedef GPB_ENUM(GPBBytesValue_FieldNumber) { GPBBytesValue_FieldNumber_Value = 1, }; -/// Wrapper message for `bytes`. -/// -/// The JSON representation for `BytesValue` is JSON string. +/** + * Wrapper message for `bytes`. + * + * The JSON representation for `BytesValue` is JSON string. + **/ @interface GPBBytesValue : GPBMessage -/// The bytes value. +/** The bytes value. */ @property(nonatomic, readwrite, copy, null_resettable) NSData *value; @end diff --git a/src/google/protobuf/compiler/objectivec/objectivec_enum.cc b/src/google/protobuf/compiler/objectivec/objectivec_enum.cc index e76f8e9915..34e1782384 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_enum.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_enum.cc @@ -62,7 +62,7 @@ void EnumGenerator::GenerateHeader(io::Printer* printer) { string enum_comments; SourceLocation location; if (descriptor_->GetSourceLocation(&location)) { - enum_comments = BuildCommentsString(location); + enum_comments = BuildCommentsString(location, true); } else { enum_comments = ""; } @@ -81,16 +81,18 @@ void EnumGenerator::GenerateHeader(io::Printer* printer) { if (HasPreservingUnknownEnumSemantics(descriptor_->file())) { // Include the unknown value. printer->Print( - "/// Value used if any message's field encounters a value that is not defined\n" - "/// by this enum. The message will also have C functions to get/set the rawValue\n" - "/// of the field.\n" + "/**\n" + " * Value used if any message's field encounters a value that is not defined\n" + " * by this enum. The message will also have C functions to get/set the rawValue\n" + " * of the field.\n" + " **/\n" "$name$_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue,\n", "name", name_); } for (int i = 0; i < all_values_.size(); i++) { SourceLocation location; if (all_values_[i]->GetSourceLocation(&location)) { - string comments = BuildCommentsString(location).c_str(); + string comments = BuildCommentsString(location, true).c_str(); if (comments.length() > 0) { if (i > 0) { printer->Print("\n"); @@ -111,8 +113,10 @@ void EnumGenerator::GenerateHeader(io::Printer* printer) { "\n" "GPBEnumDescriptor *$name$_EnumDescriptor(void);\n" "\n" - "/// Checks to see if the given value is defined by the enum or was not known at\n" - "/// the time this source was generated.\n" + "/**\n" + " * Checks to see if the given value is defined by the enum or was not known at\n" + " * the time this source was generated.\n" + " **/\n" "BOOL $name$_IsValidValue(int32_t value);\n" "\n", "name", name_); diff --git a/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc b/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc index b63bc0de63..7a774a0922 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc @@ -83,12 +83,16 @@ void EnumFieldGenerator::GenerateCFunctionDeclarations( printer->Print( variables_, - "/// Fetches the raw value of a @c $owning_message_class$'s @c $name$ property, even\n" - "/// if the value was not defined by the enum at the time the code was generated.\n" + "/**\n" + " * Fetches the raw value of a @c $owning_message_class$'s @c $name$ property, even\n" + " * if the value was not defined by the enum at the time the code was generated.\n" + " **/\n" "int32_t $owning_message_class$_$capitalized_name$_RawValue($owning_message_class$ *message);\n" - "/// Sets the raw value of an @c $owning_message_class$'s @c $name$ property, allowing\n" - "/// it to be set to a value that was not defined by the enum at the time the code\n" - "/// was generated.\n" + "/**\n" + " * Sets the raw value of an @c $owning_message_class$'s @c $name$ property, allowing\n" + " * it to be set to a value that was not defined by the enum at the time the code\n" + " * was generated.\n" + " **/\n" "void Set$owning_message_class$_$capitalized_name$_RawValue($owning_message_class$ *message, int32_t value);\n" "\n"); } diff --git a/src/google/protobuf/compiler/objectivec/objectivec_extension.cc b/src/google/protobuf/compiler/objectivec/objectivec_extension.cc index 3f7ab9d392..c0e7253a79 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_extension.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_extension.cc @@ -63,7 +63,7 @@ void ExtensionGenerator::GenerateMembersHeader(io::Printer* printer) { vars["method_name"] = method_name_; SourceLocation location; if (descriptor_->GetSourceLocation(&location)) { - vars["comments"] = BuildCommentsString(location); + vars["comments"] = BuildCommentsString(location, true); } else { vars["comments"] = ""; } diff --git a/src/google/protobuf/compiler/objectivec/objectivec_field.cc b/src/google/protobuf/compiler/objectivec/objectivec_field.cc index 812b4a1c13..d2a6e882df 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_field.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_field.cc @@ -64,7 +64,7 @@ void SetCommonFieldVariables(const FieldDescriptor* descriptor, SourceLocation location; if (descriptor->GetSourceLocation(&location)) { - (*variables)["comments"] = BuildCommentsString(location); + (*variables)["comments"] = BuildCommentsString(location, true); } else { (*variables)["comments"] = "\n"; } @@ -335,7 +335,7 @@ void ObjCObjFieldGenerator::GeneratePropertyDeclaration( if (WantsHasProperty()) { printer->Print( variables_, - "/// Test to see if @c $name$ has been set.\n" + "/** Test to see if @c $name$ has been set. */\n" "@property(nonatomic, readwrite) BOOL has$capitalized_name$$deprecated_attribute$;\n"); } if (IsInitName(variables_.find("name")->second)) { @@ -387,7 +387,7 @@ void RepeatedFieldGenerator::GeneratePropertyDeclaration( "$comments$" "$array_comment$" "@property(nonatomic, readwrite, strong, null_resettable) $array_property_type$ *$name$$storage_attribute$$deprecated_attribute$;\n" - "/// The number of items in @c $name$ without causing the array to be created.\n" + "/** The number of items in @c $name$ without causing the array to be created. */\n" "@property(nonatomic, readonly) NSUInteger $name$_Count$deprecated_attribute$;\n"); if (IsInitName(variables_.find("name")->second)) { // If property name starts with init we need to annotate it to get past ARC. diff --git a/src/google/protobuf/compiler/objectivec/objectivec_file.cc b/src/google/protobuf/compiler/objectivec/objectivec_file.cc index b864ef129e..438f411324 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_file.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_file.cc @@ -357,14 +357,16 @@ void FileGenerator::GenerateHeader(io::Printer *printer) { printer->Print( "#pragma mark - $root_class_name$\n" "\n" - "/// Exposes the extension registry for this file.\n" - "///\n" - "/// The base class provides:\n" - "/// @code\n" - "/// + (GPBExtensionRegistry *)extensionRegistry;\n" - "/// @endcode\n" - "/// which is a @c GPBExtensionRegistry that includes all the extensions defined by\n" - "/// this file and all files that it depends on.\n" + "/**\n" + " * Exposes the extension registry for this file.\n" + " *\n" + " * The base class provides:\n" + " * @code\n" + " * + (GPBExtensionRegistry *)extensionRegistry;\n" + " * @endcode\n" + " * which is a @c GPBExtensionRegistry that includes all the extensions defined by\n" + " * this file and all files that it depends on.\n" + " **/\n" "@interface $root_class_name$ : GPBRootObject\n" "@end\n" "\n", diff --git a/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc b/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc index 22c7a883d0..28b3f5aecd 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc @@ -830,7 +830,8 @@ string BuildFlagsString(const vector& strings) { return string; } -string BuildCommentsString(const SourceLocation& location) { +string BuildCommentsString(const SourceLocation& location, + bool prefer_single_line) { const string& comments = location.leading_comments.empty() ? location.trailing_comments : location.leading_comments; @@ -839,15 +840,37 @@ string BuildCommentsString(const SourceLocation& location) { while (!lines.empty() && lines.back().empty()) { lines.pop_back(); } - string prefix("///"); - string suffix("\n"); + // If there are no comments, just return an empty string. + if (lines.size() == 0) { + return ""; + } + + string prefix; + string suffix; string final_comments; - for (int i = 0; i < lines.size(); i++) { - // HeaderDoc uses '\' and '@' for markers; escape them. - const string line = StringReplace(lines[i], "\\", "\\\\", true); - final_comments += - prefix + StringReplace(line, "@", "\\@", true) + suffix; + string epilogue; + + if (prefer_single_line && lines.size() == 1) { + prefix = "/** "; + suffix = " */\n"; + } else { + prefix = " * "; + suffix = "\n"; + final_comments += "/**\n"; + epilogue = " **/\n"; } + + for (int i = 0; i < lines.size(); i++) { + string line = StripPrefixString(lines[i], " "); + // HeaderDoc and appledoc use '\' and '@' for markers; escape them. + line = StringReplace(line, "\\", "\\\\", true); + line = StringReplace(line, "@", "\\@", true); + // Decouple / from * to not have inline comments inside comments. + line = StringReplace(line, "/*", "/\\*", true); + line = StringReplace(line, "*/", "*\\/", true); + final_comments += prefix + line + suffix; + } + final_comments += epilogue; return final_comments; } diff --git a/src/google/protobuf/compiler/objectivec/objectivec_helpers.h b/src/google/protobuf/compiler/objectivec/objectivec_helpers.h index be20beeea5..998c6281c1 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_helpers.h +++ b/src/google/protobuf/compiler/objectivec/objectivec_helpers.h @@ -170,8 +170,10 @@ bool HasNonZeroDefaultValue(const FieldDescriptor* field); string BuildFlagsString(const vector& strings); -// Builds a HeaderDoc style comment out of the comments in the .proto file. -string BuildCommentsString(const SourceLocation& location); +// Builds HeaderDoc/appledoc style comments out of the comments in the .proto +// file. +string BuildCommentsString(const SourceLocation& location, + bool prefer_single_line); // The name the commonly used by the library when built as a framework. // This lines up to the name used in the CocoaPod. diff --git a/src/google/protobuf/compiler/objectivec/objectivec_message.cc b/src/google/protobuf/compiler/objectivec/objectivec_message.cc index e1a7861971..822da893e2 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_message.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_message.cc @@ -331,7 +331,7 @@ void MessageGenerator::GenerateMessageHeader(io::Printer* printer) { string message_comments; SourceLocation location; if (descriptor_->GetSourceLocation(&location)) { - message_comments = BuildCommentsString(location); + message_comments = BuildCommentsString(location, false); } else { message_comments = ""; } diff --git a/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc b/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc index 3dda903bbf..5531ae249f 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc @@ -53,7 +53,7 @@ OneofGenerator::OneofGenerator(const OneofDescriptor* descriptor) string comments; SourceLocation location; if (descriptor_->GetSourceLocation(&location)) { - comments = BuildCommentsString(location); + comments = BuildCommentsString(location, true); } else { comments = ""; } @@ -104,7 +104,9 @@ void OneofGenerator::GeneratePublicCasePropertyDeclaration( void OneofGenerator::GenerateClearFunctionDeclaration(io::Printer* printer) { printer->Print( variables_, - "/// Clears whatever value was set for the oneof '$name$'.\n" + "/**\n" + " * Clears whatever value was set for the oneof '$name$'.\n" + " **/\n" "void $owning_message_class$_Clear$capitalized_name$OneOfCase($owning_message_class$ *message);\n"); }