From 36650a07cf98ee4e734e07f2403fe5d20e300fc8 Mon Sep 17 00:00:00 2001 From: Thomas Van Lenten Date: Mon, 7 Mar 2016 12:07:03 -0500 Subject: HeaderDoc support in the library and generated sources - Convert most of the core library headers over to HeaderDoc format. - Switch the generated comments over to HeaderDoc. - Create GPBCodedOutputStream_PackagePrivate and move some things into there that should be more internal. --- objectivec/google/protobuf/Any.pbobjc.h | 116 +-- objectivec/google/protobuf/Api.pbobjc.h | 265 +++--- objectivec/google/protobuf/Descriptor.pbobjc.h | 1052 +++++++++++---------- objectivec/google/protobuf/Duration.pbobjc.h | 110 +-- objectivec/google/protobuf/Empty.pbobjc.h | 32 +- objectivec/google/protobuf/FieldMask.pbobjc.h | 261 ++--- objectivec/google/protobuf/SourceContext.pbobjc.h | 22 +- objectivec/google/protobuf/Struct.pbobjc.h | 89 +- objectivec/google/protobuf/Timestamp.pbobjc.h | 134 +-- objectivec/google/protobuf/Type.pbobjc.h | 189 ++-- objectivec/google/protobuf/Wrappers.pbobjc.h | 86 +- 11 files changed, 1265 insertions(+), 1091 deletions(-) (limited to 'objectivec/google') diff --git a/objectivec/google/protobuf/Any.pbobjc.h b/objectivec/google/protobuf/Any.pbobjc.h index 9866b5b1..a204ae9a 100644 --- a/objectivec/google/protobuf/Any.pbobjc.h +++ b/objectivec/google/protobuf/Any.pbobjc.h @@ -15,13 +15,15 @@ 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. @interface GPBAnyRoot : GPBRootObject - -// The base class provides: -// + (GPBExtensionRegistry *)extensionRegistry; -// which is an GPBExtensionRegistry that includes all the extensions defined by -// this file and all files that it depends on. - @end #pragma mark - GPBAny @@ -31,61 +33,61 @@ typedef GPB_ENUM(GPBAny_FieldNumber) { GPBAny_FieldNumber_Value = 2, }; -// `Any` contains an arbitrary serialized message along with a URL -// that describes the type of the serialized message. -// -// -// 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 message along with a URL +/// that describes the type of the serialized message. +/// +/// +/// 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 message. -// -// For URLs which use the schema `http`, `https`, or no schema, the -// following restrictions and interpretations apply: -// -// * If no schema 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`). -// * 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.) -// -// Schemas other than `http`, `https` (or the empty schema) might be -// used with implementation specific semantics. +/// A URL/resource name whose content describes the type of the +/// serialized message. +/// +/// For URLs which use the schema `http`, `https`, or no schema, the +/// following restrictions and interpretations apply: +/// +/// * If no schema 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`). +/// * 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.) +/// +/// Schemas other than `http`, `https` (or the empty schema) might be +/// used with implementation specific semantics. @property(nonatomic, readwrite, copy, null_resettable) NSString *typeURL; -// Must be valid serialized data of the above specified type. +/// Must be valid serialized data 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 8d82b15f..271a166f 100644 --- a/objectivec/google/protobuf/Api.pbobjc.h +++ b/objectivec/google/protobuf/Api.pbobjc.h @@ -21,13 +21,15 @@ 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. @interface GPBApiRoot : GPBRootObject - -// The base class provides: -// + (GPBExtensionRegistry *)extensionRegistry; -// which is an GPBExtensionRegistry that includes all the extensions defined by -// this file and all files that it depends on. - @end #pragma mark - GPBApi @@ -42,58 +44,67 @@ 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. @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. @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. -@property(nonatomic, readwrite) BOOL hasSourceContext; +/// 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. +@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. @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. 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. void SetGPBApi_Syntax_RawValue(GPBApi *message, int32_t value); #pragma mark - GPBMethod @@ -108,34 +119,40 @@ 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. @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. 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. void SetGPBMethod_Syntax_RawValue(GPBMethod *message, int32_t value); #pragma mark - GPBMixin @@ -145,90 +162,90 @@ 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/Descriptor.pbobjc.h b/objectivec/google/protobuf/Descriptor.pbobjc.h index 2ab20243..109711c7 100644 --- a/objectivec/google/protobuf/Descriptor.pbobjc.h +++ b/objectivec/google/protobuf/Descriptor.pbobjc.h @@ -39,85 +39,91 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Enum GPBFieldDescriptorProto_Type typedef GPB_ENUM(GPBFieldDescriptorProto_Type) { - // 0 is reserved for errors. - // Order is weird for historical reasons. + /// 0 is reserved for errors. + /// Order is weird for historical reasons. GPBFieldDescriptorProto_Type_TypeDouble = 1, GPBFieldDescriptorProto_Type_TypeFloat = 2, - // Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT64 if - // negative values are likely. + /// Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT64 if + /// negative values are likely. GPBFieldDescriptorProto_Type_TypeInt64 = 3, GPBFieldDescriptorProto_Type_TypeUint64 = 4, - // Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT32 if - // negative values are likely. + /// Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT32 if + /// negative values are likely. GPBFieldDescriptorProto_Type_TypeInt32 = 5, GPBFieldDescriptorProto_Type_TypeFixed64 = 6, GPBFieldDescriptorProto_Type_TypeFixed32 = 7, GPBFieldDescriptorProto_Type_TypeBool = 8, GPBFieldDescriptorProto_Type_TypeString = 9, - // Tag-delimited aggregate. + /// Tag-delimited aggregate. GPBFieldDescriptorProto_Type_TypeGroup = 10, - // Length-delimited aggregate. + /// Length-delimited aggregate. GPBFieldDescriptorProto_Type_TypeMessage = 11, - // New in version 2. + /// New in version 2. GPBFieldDescriptorProto_Type_TypeBytes = 12, GPBFieldDescriptorProto_Type_TypeUint32 = 13, GPBFieldDescriptorProto_Type_TypeEnum = 14, GPBFieldDescriptorProto_Type_TypeSfixed32 = 15, GPBFieldDescriptorProto_Type_TypeSfixed64 = 16, - // Uses ZigZag encoding. + /// Uses ZigZag encoding. GPBFieldDescriptorProto_Type_TypeSint32 = 17, - // Uses ZigZag encoding. + /// Uses ZigZag encoding. GPBFieldDescriptorProto_Type_TypeSint64 = 18, }; GPBEnumDescriptor *GPBFieldDescriptorProto_Type_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. BOOL GPBFieldDescriptorProto_Type_IsValidValue(int32_t value); #pragma mark - Enum GPBFieldDescriptorProto_Label typedef GPB_ENUM(GPBFieldDescriptorProto_Label) { - // 0 is reserved for errors + /// 0 is reserved for errors GPBFieldDescriptorProto_Label_LabelOptional = 1, GPBFieldDescriptorProto_Label_LabelRequired = 2, - // TODO(sanjay): Should we add LABEL_MAP? + /// TODO(sanjay): Should we add LABEL_MAP? GPBFieldDescriptorProto_Label_LabelRepeated = 3, }; GPBEnumDescriptor *GPBFieldDescriptorProto_Label_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. BOOL GPBFieldDescriptorProto_Label_IsValidValue(int32_t value); #pragma mark - Enum GPBFileOptions_OptimizeMode -// Generated classes can be optimized for speed or code size. +/// Generated classes can be optimized for speed or code size. typedef GPB_ENUM(GPBFileOptions_OptimizeMode) { - // Generate complete code for parsing, serialization, + /// Generate complete code for parsing, serialization, GPBFileOptions_OptimizeMode_Speed = 1, - // etc. + /// etc. GPBFileOptions_OptimizeMode_CodeSize = 2, - // Generate code using MessageLite and the lite runtime. + /// Generate code using MessageLite and the lite runtime. GPBFileOptions_OptimizeMode_LiteRuntime = 3, }; GPBEnumDescriptor *GPBFileOptions_OptimizeMode_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. BOOL GPBFileOptions_OptimizeMode_IsValidValue(int32_t value); #pragma mark - Enum GPBFieldOptions_CType typedef GPB_ENUM(GPBFieldOptions_CType) { - // Default mode. + /// Default mode. GPBFieldOptions_CType_String = 0, GPBFieldOptions_CType_Cord = 1, GPBFieldOptions_CType_StringPiece = 2, @@ -125,34 +131,40 @@ typedef GPB_ENUM(GPBFieldOptions_CType) { GPBEnumDescriptor *GPBFieldOptions_CType_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. BOOL GPBFieldOptions_CType_IsValidValue(int32_t value); #pragma mark - Enum GPBFieldOptions_JSType typedef GPB_ENUM(GPBFieldOptions_JSType) { - // Use the default type. + /// Use the default type. GPBFieldOptions_JSType_JsNormal = 0, - // Use JavaScript strings. + /// Use JavaScript strings. GPBFieldOptions_JSType_JsString = 1, - // Use JavaScript numbers. + /// Use JavaScript numbers. GPBFieldOptions_JSType_JsNumber = 2, }; GPBEnumDescriptor *GPBFieldOptions_JSType_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. BOOL GPBFieldOptions_JSType_IsValidValue(int32_t value); #pragma mark - GPBDescriptorRoot +/// 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 GPBDescriptorRoot : GPBRootObject - -// The base class provides: -// + (GPBExtensionRegistry *)extensionRegistry; -// which is an GPBExtensionRegistry that includes all the extensions defined by -// this file and all files that it depends on. - @end #pragma mark - GPBFileDescriptorSet @@ -161,11 +173,12 @@ typedef GPB_ENUM(GPBFileDescriptorSet_FieldNumber) { GPBFileDescriptorSet_FieldNumber_FileArray = 1, }; -// The protocol compiler can output a FileDescriptorSet containing the .proto -// files it parses. +/// The protocol compiler can output a FileDescriptorSet containing the .proto +/// files it parses. @interface GPBFileDescriptorSet : GPBMessage @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *fileArray; +/// The number of items in @c fileArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger fileArray_Count; @end @@ -187,57 +200,69 @@ typedef GPB_ENUM(GPBFileDescriptorProto_FieldNumber) { GPBFileDescriptorProto_FieldNumber_Syntax = 12, }; -// Describes a complete .proto file. +/// Describes a complete .proto file. @interface GPBFileDescriptorProto : GPBMessage -// file name, relative to root of source tree -@property(nonatomic, readwrite) BOOL hasName; +/// file name, relative to root of source tree @property(nonatomic, readwrite, copy, null_resettable) NSString *name; +/// Test to see if @c name has been set. +@property(nonatomic, readwrite) BOOL hasName; -// e.g. "foo", "foo.bar", etc. -@property(nonatomic, readwrite) BOOL hasPackage; +/// e.g. "foo", "foo.bar", etc. @property(nonatomic, readwrite, copy, null_resettable) NSString *package; +/// Test to see if @c package has been set. +@property(nonatomic, readwrite) BOOL hasPackage; -// Names of files imported by this file. +/// Names of files imported by this file. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *dependencyArray; +/// The number of items in @c dependencyArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger dependencyArray_Count; -// Indexes of the public imported files in the dependency list above. +/// Indexes of the public imported files in the dependency list above. @property(nonatomic, readwrite, strong, null_resettable) GPBInt32Array *publicDependencyArray; +/// The number of items in @c publicDependencyArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger publicDependencyArray_Count; -// Indexes of the weak imported files in the dependency list. -// For Google-internal migration only. Do not use. +/// Indexes of the weak imported files in the dependency list. +/// For Google-internal migration only. Do not use. @property(nonatomic, readwrite, strong, null_resettable) GPBInt32Array *weakDependencyArray; +/// The number of items in @c weakDependencyArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger weakDependencyArray_Count; -// All top-level definitions in this file. +/// All top-level definitions in this file. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *messageTypeArray; +/// The number of items in @c messageTypeArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger messageTypeArray_Count; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *enumTypeArray; +/// The number of items in @c enumTypeArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger enumTypeArray_Count; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *serviceArray; +/// The number of items in @c serviceArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger serviceArray_Count; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *extensionArray; +/// The number of items in @c extensionArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger extensionArray_Count; -@property(nonatomic, readwrite) BOOL hasOptions; @property(nonatomic, readwrite, strong, null_resettable) GPBFileOptions *options; +/// Test to see if @c options has been set. +@property(nonatomic, readwrite) BOOL hasOptions; -// This field contains optional information about the original source code. -// You may safely remove this entire field without harming runtime -// functionality of the descriptors -- the information is needed only by -// development tools. -@property(nonatomic, readwrite) BOOL hasSourceCodeInfo; +/// This field contains optional information about the original source code. +/// You may safely remove this entire field without harming runtime +/// functionality of the descriptors -- the information is needed only by +/// development tools. @property(nonatomic, readwrite, strong, null_resettable) GPBSourceCodeInfo *sourceCodeInfo; +/// Test to see if @c sourceCodeInfo has been set. +@property(nonatomic, readwrite) BOOL hasSourceCodeInfo; -// The syntax of the proto file. -// The supported values are "proto2" and "proto3". -@property(nonatomic, readwrite) BOOL hasSyntax; +/// The syntax of the proto file. +/// The supported values are "proto2" and "proto3". @property(nonatomic, readwrite, copy, null_resettable) NSString *syntax; +/// Test to see if @c syntax has been set. +@property(nonatomic, readwrite) BOOL hasSyntax; @end @@ -256,39 +281,49 @@ typedef GPB_ENUM(GPBDescriptorProto_FieldNumber) { GPBDescriptorProto_FieldNumber_ReservedNameArray = 10, }; -// Describes a message type. +/// Describes a message type. @interface GPBDescriptorProto : GPBMessage -@property(nonatomic, readwrite) BOOL hasName; @property(nonatomic, readwrite, copy, null_resettable) NSString *name; +/// Test to see if @c name has been set. +@property(nonatomic, readwrite) BOOL hasName; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *fieldArray; +/// The number of items in @c fieldArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger fieldArray_Count; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *extensionArray; +/// The number of items in @c extensionArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger extensionArray_Count; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *nestedTypeArray; +/// The number of items in @c nestedTypeArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger nestedTypeArray_Count; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *enumTypeArray; +/// The number of items in @c enumTypeArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger enumTypeArray_Count; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *extensionRangeArray; +/// The number of items in @c extensionRangeArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger extensionRangeArray_Count; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *oneofDeclArray; +/// The number of items in @c oneofDeclArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger oneofDeclArray_Count; -@property(nonatomic, readwrite) BOOL hasOptions; @property(nonatomic, readwrite, strong, null_resettable) GPBMessageOptions *options; +/// Test to see if @c options has been set. +@property(nonatomic, readwrite) BOOL hasOptions; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *reservedRangeArray; +/// The number of items in @c reservedRangeArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger reservedRangeArray_Count; -// Reserved field names, which may not be used by fields in the same message. -// A given name may only be reserved once. +/// Reserved field names, which may not be used by fields in the same message. +/// A given name may only be reserved once. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *reservedNameArray; +/// The number of items in @c reservedNameArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger reservedNameArray_Count; @end @@ -302,12 +337,12 @@ typedef GPB_ENUM(GPBDescriptorProto_ExtensionRange_FieldNumber) { @interface GPBDescriptorProto_ExtensionRange : GPBMessage -@property(nonatomic, readwrite) BOOL hasStart; @property(nonatomic, readwrite) int32_t start; -@property(nonatomic, readwrite) BOOL hasEnd; +@property(nonatomic, readwrite) BOOL hasStart; @property(nonatomic, readwrite) int32_t end; +@property(nonatomic, readwrite) BOOL hasEnd; @end #pragma mark - GPBDescriptorProto_ReservedRange @@ -317,19 +352,19 @@ typedef GPB_ENUM(GPBDescriptorProto_ReservedRange_FieldNumber) { GPBDescriptorProto_ReservedRange_FieldNumber_End = 2, }; -// Range of reserved tag numbers. Reserved tag numbers may not be used by -// fields or extension ranges in the same message. Reserved ranges may -// not overlap. +/// Range of reserved tag numbers. Reserved tag numbers may not be used by +/// fields or extension ranges in the same message. Reserved ranges may +/// not overlap. @interface GPBDescriptorProto_ReservedRange : GPBMessage -// Inclusive. -@property(nonatomic, readwrite) BOOL hasStart; +/// Inclusive. @property(nonatomic, readwrite) int32_t start; -// Exclusive. -@property(nonatomic, readwrite) BOOL hasEnd; +@property(nonatomic, readwrite) BOOL hasStart; +/// Exclusive. @property(nonatomic, readwrite) int32_t end; +@property(nonatomic, readwrite) BOOL hasEnd; @end #pragma mark - GPBFieldDescriptorProto @@ -347,58 +382,64 @@ typedef GPB_ENUM(GPBFieldDescriptorProto_FieldNumber) { GPBFieldDescriptorProto_FieldNumber_JsonName = 10, }; -// Describes a field within a message. +/// Describes a field within a message. @interface GPBFieldDescriptorProto : GPBMessage -@property(nonatomic, readwrite) BOOL hasName; @property(nonatomic, readwrite, copy, null_resettable) NSString *name; +/// Test to see if @c name has been set. +@property(nonatomic, readwrite) BOOL hasName; -@property(nonatomic, readwrite) BOOL hasNumber; @property(nonatomic, readwrite) int32_t number; -@property(nonatomic, readwrite) BOOL hasLabel; +@property(nonatomic, readwrite) BOOL hasNumber; @property(nonatomic, readwrite) GPBFieldDescriptorProto_Label label; -// If type_name is set, this need not be set. If both this and type_name -// are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP. -@property(nonatomic, readwrite) BOOL hasType; +@property(nonatomic, readwrite) BOOL hasLabel; +/// If type_name is set, this need not be set. If both this and type_name +/// are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP. @property(nonatomic, readwrite) GPBFieldDescriptorProto_Type type; -// For message and enum types, this is the name of the type. If the name -// starts with a '.', it is fully-qualified. Otherwise, C++-like scoping -// rules are used to find the type (i.e. first the nested types within this -// message are searched, then within the parent, on up to the root -// namespace). -@property(nonatomic, readwrite) BOOL hasTypeName; +@property(nonatomic, readwrite) BOOL hasType; +/// For message and enum types, this is the name of the type. If the name +/// starts with a '.', it is fully-qualified. Otherwise, C++-like scoping +/// rules are used to find the type (i.e. first the nested types within this +/// message are searched, then within the parent, on up to the root +/// namespace). @property(nonatomic, readwrite, copy, null_resettable) NSString *typeName; +/// Test to see if @c typeName has been set. +@property(nonatomic, readwrite) BOOL hasTypeName; -// For extensions, this is the name of the type being extended. It is -// resolved in the same manner as type_name. -@property(nonatomic, readwrite) BOOL hasExtendee; +/// For extensions, this is the name of the type being extended. It is +/// resolved in the same manner as type_name. @property(nonatomic, readwrite, copy, null_resettable) NSString *extendee; +/// Test to see if @c extendee has been set. +@property(nonatomic, readwrite) BOOL hasExtendee; -// For numeric types, contains the original text representation of the value. -// For booleans, "true" or "false". -// For strings, contains the default text contents (not escaped in any way). -// For bytes, contains the C escaped value. All bytes >= 128 are escaped. -// TODO(kenton): Base-64 encode? -@property(nonatomic, readwrite) BOOL hasDefaultValue; +/// For numeric types, contains the original text representation of the value. +/// For booleans, "true" or "false". +/// For strings, contains the default text contents (not escaped in any way). +/// For bytes, contains the C escaped value. All bytes >= 128 are escaped. +/// TODO(kenton): Base-64 encode? @property(nonatomic, readwrite, copy, null_resettable) NSString *defaultValue; +/// Test to see if @c defaultValue has been set. +@property(nonatomic, readwrite) BOOL hasDefaultValue; -// If set, gives the index of a oneof in the containing type's oneof_decl -// list. This field is a member of that oneof. -@property(nonatomic, readwrite) BOOL hasOneofIndex; +/// If set, gives the index of a oneof in the containing type's oneof_decl +/// list. This field is a member of that oneof. @property(nonatomic, readwrite) int32_t oneofIndex; -// JSON name of this field. The value is set by protocol compiler. If the -// user has set a "json_name" option on this field, that option's value -// will be used. Otherwise, it's deduced from the field's name by converting -// it to camelCase. -@property(nonatomic, readwrite) BOOL hasJsonName; +@property(nonatomic, readwrite) BOOL hasOneofIndex; +/// JSON name of this field. The value is set by protocol compiler. If the +/// user has set a "json_name" option on this field, that option's value +/// will be used. Otherwise, it's deduced from the field's name by converting +/// it to camelCase. @property(nonatomic, readwrite, copy, null_resettable) NSString *jsonName; +/// Test to see if @c jsonName has been set. +@property(nonatomic, readwrite) BOOL hasJsonName; -@property(nonatomic, readwrite) BOOL hasOptions; @property(nonatomic, readwrite, strong, null_resettable) GPBFieldOptions *options; +/// Test to see if @c options has been set. +@property(nonatomic, readwrite) BOOL hasOptions; @end @@ -408,11 +449,12 @@ typedef GPB_ENUM(GPBOneofDescriptorProto_FieldNumber) { GPBOneofDescriptorProto_FieldNumber_Name = 1, }; -// Describes a oneof. +/// Describes a oneof. @interface GPBOneofDescriptorProto : GPBMessage -@property(nonatomic, readwrite) BOOL hasName; @property(nonatomic, readwrite, copy, null_resettable) NSString *name; +/// Test to see if @c name has been set. +@property(nonatomic, readwrite) BOOL hasName; @end @@ -424,17 +466,20 @@ typedef GPB_ENUM(GPBEnumDescriptorProto_FieldNumber) { GPBEnumDescriptorProto_FieldNumber_Options = 3, }; -// Describes an enum type. +/// Describes an enum type. @interface GPBEnumDescriptorProto : GPBMessage -@property(nonatomic, readwrite) BOOL hasName; @property(nonatomic, readwrite, copy, null_resettable) NSString *name; +/// Test to see if @c name has been set. +@property(nonatomic, readwrite) BOOL hasName; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *valueArray; +/// The number of items in @c valueArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger valueArray_Count; -@property(nonatomic, readwrite) BOOL hasOptions; @property(nonatomic, readwrite, strong, null_resettable) GPBEnumOptions *options; +/// Test to see if @c options has been set. +@property(nonatomic, readwrite) BOOL hasOptions; @end @@ -446,17 +491,19 @@ typedef GPB_ENUM(GPBEnumValueDescriptorProto_FieldNumber) { GPBEnumValueDescriptorProto_FieldNumber_Options = 3, }; -// Describes a value within an enum. +/// Describes a value within an enum. @interface GPBEnumValueDescriptorProto : GPBMessage -@property(nonatomic, readwrite) BOOL hasName; @property(nonatomic, readwrite, copy, null_resettable) NSString *name; +/// Test to see if @c name has been set. +@property(nonatomic, readwrite) BOOL hasName; -@property(nonatomic, readwrite) BOOL hasNumber; @property(nonatomic, readwrite) int32_t number; -@property(nonatomic, readwrite) BOOL hasOptions; +@property(nonatomic, readwrite) BOOL hasNumber; @property(nonatomic, readwrite, strong, null_resettable) GPBEnumValueOptions *options; +/// Test to see if @c options has been set. +@property(nonatomic, readwrite) BOOL hasOptions; @end @@ -468,17 +515,20 @@ typedef GPB_ENUM(GPBServiceDescriptorProto_FieldNumber) { GPBServiceDescriptorProto_FieldNumber_Options = 3, }; -// Describes a service. +/// Describes a service. @interface GPBServiceDescriptorProto : GPBMessage -@property(nonatomic, readwrite) BOOL hasName; @property(nonatomic, readwrite, copy, null_resettable) NSString *name; +/// Test to see if @c name has been set. +@property(nonatomic, readwrite) BOOL hasName; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *methodArray; +/// The number of items in @c methodArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger methodArray_Count; -@property(nonatomic, readwrite) BOOL hasOptions; @property(nonatomic, readwrite, strong, null_resettable) GPBServiceOptions *options; +/// Test to see if @c options has been set. +@property(nonatomic, readwrite) BOOL hasOptions; @end @@ -493,31 +543,35 @@ typedef GPB_ENUM(GPBMethodDescriptorProto_FieldNumber) { GPBMethodDescriptorProto_FieldNumber_ServerStreaming = 6, }; -// Describes a method of a service. +/// Describes a method of a service. @interface GPBMethodDescriptorProto : GPBMessage -@property(nonatomic, readwrite) BOOL hasName; @property(nonatomic, readwrite, copy, null_resettable) NSString *name; +/// Test to see if @c name has been set. +@property(nonatomic, readwrite) BOOL hasName; -// Input and output type names. These are resolved in the same way as -// FieldDescriptorProto.type_name, but must refer to a message type. -@property(nonatomic, readwrite) BOOL hasInputType; +/// Input and output type names. These are resolved in the same way as +/// FieldDescriptorProto.type_name, but must refer to a message type. @property(nonatomic, readwrite, copy, null_resettable) NSString *inputType; +/// Test to see if @c inputType has been set. +@property(nonatomic, readwrite) BOOL hasInputType; -@property(nonatomic, readwrite) BOOL hasOutputType; @property(nonatomic, readwrite, copy, null_resettable) NSString *outputType; +/// Test to see if @c outputType has been set. +@property(nonatomic, readwrite) BOOL hasOutputType; -@property(nonatomic, readwrite) BOOL hasOptions; @property(nonatomic, readwrite, strong, null_resettable) GPBMethodOptions *options; +/// Test to see if @c options has been set. +@property(nonatomic, readwrite) BOOL hasOptions; -// Identifies if client streams multiple client messages -@property(nonatomic, readwrite) BOOL hasClientStreaming; +/// Identifies if client streams multiple client messages @property(nonatomic, readwrite) BOOL clientStreaming; -// Identifies if server streams multiple server messages -@property(nonatomic, readwrite) BOOL hasServerStreaming; +@property(nonatomic, readwrite) BOOL hasClientStreaming; +/// Identifies if server streams multiple server messages @property(nonatomic, readwrite) BOOL serverStreaming; +@property(nonatomic, readwrite) BOOL hasServerStreaming; @end #pragma mark - GPBFileOptions @@ -543,112 +597,118 @@ typedef GPB_ENUM(GPBFileOptions_FieldNumber) { @interface GPBFileOptions : GPBMessage -// Sets the Java package where classes generated from this .proto will be -// placed. By default, the proto package is used, but this is often -// inappropriate because proto packages do not normally start with backwards -// domain names. -@property(nonatomic, readwrite) BOOL hasJavaPackage; +/// Sets the Java package where classes generated from this .proto will be +/// placed. By default, the proto package is used, but this is often +/// inappropriate because proto packages do not normally start with backwards +/// domain names. @property(nonatomic, readwrite, copy, null_resettable) NSString *javaPackage; +/// Test to see if @c javaPackage has been set. +@property(nonatomic, readwrite) BOOL hasJavaPackage; -// If set, all the classes from the .proto file are wrapped in a single -// outer class with the given name. This applies to both Proto1 -// (equivalent to the old "--one_java_file" option) and Proto2 (where -// a .proto always translates to a single class, but you may want to -// explicitly choose the class name). -@property(nonatomic, readwrite) BOOL hasJavaOuterClassname; +/// If set, all the classes from the .proto file are wrapped in a single +/// outer class with the given name. This applies to both Proto1 +/// (equivalent to the old "--one_java_file" option) and Proto2 (where +/// a .proto always translates to a single class, but you may want to +/// explicitly choose the class name). @property(nonatomic, readwrite, copy, null_resettable) NSString *javaOuterClassname; +/// Test to see if @c javaOuterClassname has been set. +@property(nonatomic, readwrite) BOOL hasJavaOuterClassname; -// If set true, then the Java code generator will generate a separate .java -// file for each top-level message, enum, and service defined in the .proto -// file. Thus, these types will *not* be nested inside the outer class -// named by java_outer_classname. However, the outer class will still be -// generated to contain the file's getDescriptor() method as well as any -// top-level extensions defined in the file. -@property(nonatomic, readwrite) BOOL hasJavaMultipleFiles; +/// If set true, then the Java code generator will generate a separate .java +/// file for each top-level message, enum, and service defined in the .proto +/// file. Thus, these types will *not* be nested inside the outer class +/// named by java_outer_classname. However, the outer class will still be +/// generated to contain the file's getDescriptor() method as well as any +/// top-level extensions defined in the file. @property(nonatomic, readwrite) BOOL javaMultipleFiles; -// If set true, then the Java code generator will generate equals() and -// hashCode() methods for all messages defined in the .proto file. -// This increases generated code size, potentially substantially for large -// protos, which may harm a memory-constrained application. -// - In the full runtime this is a speed optimization, as the -// AbstractMessage base class includes reflection-based implementations of -// these methods. -// - In the lite runtime, setting this option changes the semantics of -// equals() and hashCode() to more closely match those of the full runtime; -// the generated methods compute their results based on field values rather -// than object identity. (Implementations should not assume that hashcodes -// will be consistent across runtimes or versions of the protocol compiler.) -@property(nonatomic, readwrite) BOOL hasJavaGenerateEqualsAndHash; +@property(nonatomic, readwrite) BOOL hasJavaMultipleFiles; +/// If set true, then the Java code generator will generate equals() and +/// hashCode() methods for all messages defined in the .proto file. +/// This increases generated code size, potentially substantially for large +/// protos, which may harm a memory-constrained application. +/// - In the full runtime this is a speed optimization, as the +/// AbstractMessage base class includes reflection-based implementations of +/// these methods. +/// - In the lite runtime, setting this option changes the semantics of +/// equals() and hashCode() to more closely match those of the full runtime; +/// the generated methods compute their results based on field values rather +/// than object identity. (Implementations should not assume that hashcodes +/// will be consistent across runtimes or versions of the protocol compiler.) @property(nonatomic, readwrite) BOOL javaGenerateEqualsAndHash; -// If set true, then the Java2 code generator will generate code that -// throws an exception whenever an attempt is made to assign a non-UTF-8 -// byte sequence to a string field. -// Message reflection will do the same. -// However, an extension field still accepts non-UTF-8 byte sequences. -// This option has no effect on when used with the lite runtime. -@property(nonatomic, readwrite) BOOL hasJavaStringCheckUtf8; +@property(nonatomic, readwrite) BOOL hasJavaGenerateEqualsAndHash; +/// If set true, then the Java2 code generator will generate code that +/// throws an exception whenever an attempt is made to assign a non-UTF-8 +/// byte sequence to a string field. +/// Message reflection will do the same. +/// However, an extension field still accepts non-UTF-8 byte sequences. +/// This option has no effect on when used with the lite runtime. @property(nonatomic, readwrite) BOOL javaStringCheckUtf8; -@property(nonatomic, readwrite) BOOL hasOptimizeFor; +@property(nonatomic, readwrite) BOOL hasJavaStringCheckUtf8; @property(nonatomic, readwrite) GPBFileOptions_OptimizeMode optimizeFor; -// Sets the Go package where structs generated from this .proto will be -// placed. If omitted, the Go package will be derived from the following: -// - The basename of the package import path, if provided. -// - Otherwise, the package statement in the .proto file, if present. -// - Otherwise, the basename of the .proto file, without extension. -@property(nonatomic, readwrite) BOOL hasGoPackage; +@property(nonatomic, readwrite) BOOL hasOptimizeFor; +/// Sets the Go package where structs generated from this .proto will be +/// placed. If omitted, the Go package will be derived from the following: +/// - The basename of the package import path, if provided. +/// - Otherwise, the package statement in the .proto file, if present. +/// - Otherwise, the basename of the .proto file, without extension. @property(nonatomic, readwrite, copy, null_resettable) NSString *goPackage; +/// Test to see if @c goPackage has been set. +@property(nonatomic, readwrite) BOOL hasGoPackage; -// Should generic services be generated in each language? "Generic" services -// are not specific to any particular RPC system. They are generated by the -// main code generators in each language (without additional plugins). -// Generic services were the only kind of service generation supported by -// early versions of google.protobuf. -// -// Generic services are now considered deprecated in favor of using plugins -// that generate code specific to your particular RPC system. Therefore, -// these default to false. Old code which depends on generic services should -// explicitly set them to true. -@property(nonatomic, readwrite) BOOL hasCcGenericServices; +/// Should generic services be generated in each language? "Generic" services +/// are not specific to any particular RPC system. They are generated by the +/// main code generators in each language (without additional plugins). +/// Generic services were the only kind of service generation supported by +/// early versions of google.protobuf. +/// +/// Generic services are now considered deprecated in favor of using plugins +/// that generate code specific to your particular RPC system. Therefore, +/// these default to false. Old code which depends on generic services should +/// explicitly set them to true. @property(nonatomic, readwrite) BOOL ccGenericServices; -@property(nonatomic, readwrite) BOOL hasJavaGenericServices; +@property(nonatomic, readwrite) BOOL hasCcGenericServices; @property(nonatomic, readwrite) BOOL javaGenericServices; -@property(nonatomic, readwrite) BOOL hasPyGenericServices; +@property(nonatomic, readwrite) BOOL hasJavaGenericServices; @property(nonatomic, readwrite) BOOL pyGenericServices; -// Is this file deprecated? -// Depending on the target platform, this can emit Deprecated annotations -// for everything in the file, or it will be completely ignored; in the very -// least, this is a formalization for deprecating files. -@property(nonatomic, readwrite) BOOL hasDeprecated; +@property(nonatomic, readwrite) BOOL hasPyGenericServices; +/// Is this file deprecated? +/// Depending on the target platform, this can emit Deprecated annotations +/// for everything in the file, or it will be completely ignored; in the very +/// least, this is a formalization for deprecating files. @property(nonatomic, readwrite) BOOL deprecated; -// Enables the use of arenas for the proto messages in this file. This applies -// only to generated classes for C++. -@property(nonatomic, readwrite) BOOL hasCcEnableArenas; +@property(nonatomic, readwrite) BOOL hasDeprecated; +/// Enables the use of arenas for the proto messages in this file. This applies +/// only to generated classes for C++. @property(nonatomic, readwrite) BOOL ccEnableArenas; -// Sets the objective c class prefix which is prepended to all objective c -// generated classes from this .proto. There is no default. -@property(nonatomic, readwrite) BOOL hasObjcClassPrefix; +@property(nonatomic, readwrite) BOOL hasCcEnableArenas; +/// Sets the objective c class prefix which is prepended to all objective c +/// generated classes from this .proto. There is no default. @property(nonatomic, readwrite, copy, null_resettable) NSString *objcClassPrefix; +/// Test to see if @c objcClassPrefix has been set. +@property(nonatomic, readwrite) BOOL hasObjcClassPrefix; -// Namespace for generated classes; defaults to the package. -@property(nonatomic, readwrite) BOOL hasCsharpNamespace; +/// Namespace for generated classes; defaults to the package. @property(nonatomic, readwrite, copy, null_resettable) NSString *csharpNamespace; +/// Test to see if @c csharpNamespace has been set. +@property(nonatomic, readwrite) BOOL hasCsharpNamespace; -// Whether the nano proto compiler should generate in the deprecated non-nano -// suffixed package. -@property(nonatomic, readwrite) BOOL hasJavananoUseDeprecatedPackage; +/// Whether the nano proto compiler should generate in the deprecated non-nano +/// suffixed package. @property(nonatomic, readwrite) BOOL javananoUseDeprecatedPackage; -// The parser stores options it doesn't recognize here. See above. +@property(nonatomic, readwrite) BOOL hasJavananoUseDeprecatedPackage; +/// The parser stores options it doesn't recognize here. See above. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *uninterpretedOptionArray; +/// The number of items in @c uninterpretedOptionArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger uninterpretedOptionArray_Count; @end @@ -665,66 +725,67 @@ typedef GPB_ENUM(GPBMessageOptions_FieldNumber) { @interface GPBMessageOptions : GPBMessage -// Set true to use the old proto1 MessageSet wire format for extensions. -// This is provided for backwards-compatibility with the MessageSet wire -// format. You should not use this for any other reason: It's less -// efficient, has fewer features, and is more complicated. -// -// The message must be defined exactly as follows: -// message Foo { -// option message_set_wire_format = true; -// extensions 4 to max; -// } -// Note that the message cannot have any defined fields; MessageSets only -// have extensions. -// -// All extensions of your type must be singular messages; e.g. they cannot -// be int32s, enums, or repeated messages. -// -// Because this is an option, the above two restrictions are not enforced by -// the protocol compiler. -@property(nonatomic, readwrite) BOOL hasMessageSetWireFormat; +/// Set true to use the old proto1 MessageSet wire format for extensions. +/// This is provided for backwards-compatibility with the MessageSet wire +/// format. You should not use this for any other reason: It's less +/// efficient, has fewer features, and is more complicated. +/// +/// The message must be defined exactly as follows: +/// message Foo { +/// option message_set_wire_format = true; +/// extensions 4 to max; +/// } +/// Note that the message cannot have any defined fields; MessageSets only +/// have extensions. +/// +/// All extensions of your type must be singular messages; e.g. they cannot +/// be int32s, enums, or repeated messages. +/// +/// Because this is an option, the above two restrictions are not enforced by +/// the protocol compiler. @property(nonatomic, readwrite) BOOL messageSetWireFormat; -// Disables the generation of the standard "descriptor()" accessor, which can -// conflict with a field of the same name. This is meant to make migration -// from proto1 easier; new code should avoid fields named "descriptor". -@property(nonatomic, readwrite) BOOL hasNoStandardDescriptorAccessor; +@property(nonatomic, readwrite) BOOL hasMessageSetWireFormat; +/// Disables the generation of the standard "descriptor()" accessor, which can +/// conflict with a field of the same name. This is meant to make migration +/// from proto1 easier; new code should avoid fields named "descriptor". @property(nonatomic, readwrite) BOOL noStandardDescriptorAccessor; -// Is this message deprecated? -// Depending on the target platform, this can emit Deprecated annotations -// for the message, or it will be completely ignored; in the very least, -// this is a formalization for deprecating messages. -@property(nonatomic, readwrite) BOOL hasDeprecated; +@property(nonatomic, readwrite) BOOL hasNoStandardDescriptorAccessor; +/// Is this message deprecated? +/// Depending on the target platform, this can emit Deprecated annotations +/// for the message, or it will be completely ignored; in the very least, +/// this is a formalization for deprecating messages. @property(nonatomic, readwrite) BOOL deprecated; -// Whether the message is an automatically generated map entry type for the -// maps field. -// -// For maps fields: -// map map_field = 1; -// The parsed descriptor looks like: -// message MapFieldEntry { -// option map_entry = true; -// optional KeyType key = 1; -// optional ValueType value = 2; -// } -// repeated MapFieldEntry map_field = 1; -// -// Implementations may choose not to generate the map_entry=true message, but -// use a native map in the target language to hold the keys and values. -// The reflection APIs in such implementions still need to work as -// if the field is a repeated message field. -// -// NOTE: Do not set the option in .proto files. Always use the maps syntax -// instead. The option should only be implicitly set by the proto compiler -// parser. -@property(nonatomic, readwrite) BOOL hasMapEntry; +@property(nonatomic, readwrite) BOOL hasDeprecated; +/// Whether the message is an automatically generated map entry type for the +/// maps field. +/// +/// For maps fields: +/// map map_field = 1; +/// The parsed descriptor looks like: +/// message MapFieldEntry { +/// option map_entry = true; +/// optional KeyType key = 1; +/// optional ValueType value = 2; +/// } +/// repeated MapFieldEntry map_field = 1; +/// +/// Implementations may choose not to generate the map_entry=true message, but +/// use a native map in the target language to hold the keys and values. +/// The reflection APIs in such implementions still need to work as +/// if the field is a repeated message field. +/// +/// NOTE: Do not set the option in .proto files. Always use the maps syntax +/// instead. The option should only be implicitly set by the proto compiler +/// parser. @property(nonatomic, readwrite) BOOL mapEntry; -// The parser stores options it doesn't recognize here. See above. +@property(nonatomic, readwrite) BOOL hasMapEntry; +/// The parser stores options it doesn't recognize here. See above. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *uninterpretedOptionArray; +/// The number of items in @c uninterpretedOptionArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger uninterpretedOptionArray_Count; @end @@ -743,77 +804,78 @@ typedef GPB_ENUM(GPBFieldOptions_FieldNumber) { @interface GPBFieldOptions : GPBMessage -// The ctype option instructs the C++ code generator to use a different -// representation of the field than it normally would. See the specific -// options below. This option is not yet implemented in the open source -// release -- sorry, we'll try to include it in a future version! -@property(nonatomic, readwrite) BOOL hasCtype; +/// The ctype option instructs the C++ code generator to use a different +/// representation of the field than it normally would. See the specific +/// options below. This option is not yet implemented in the open source +/// release -- sorry, we'll try to include it in a future version! @property(nonatomic, readwrite) GPBFieldOptions_CType ctype; -// The packed option can be enabled for repeated primitive fields to enable -// a more efficient representation on the wire. Rather than repeatedly -// writing the tag and type for each element, the entire array is encoded as -// a single length-delimited blob. In proto3, only explicit setting it to -// false will avoid using packed encoding. -@property(nonatomic, readwrite) BOOL hasPacked; +@property(nonatomic, readwrite) BOOL hasCtype; +/// The packed option can be enabled for repeated primitive fields to enable +/// a more efficient representation on the wire. Rather than repeatedly +/// writing the tag and type for each element, the entire array is encoded as +/// a single length-delimited blob. In proto3, only explicit setting it to +/// false will avoid using packed encoding. @property(nonatomic, readwrite) BOOL packed; -// The jstype option determines the JavaScript type used for values of the -// field. The option is permitted only for 64 bit integral and fixed types -// (int64, uint64, sint64, fixed64, sfixed64). By default these types are -// represented as JavaScript strings. This avoids loss of precision that can -// happen when a large value is converted to a floating point JavaScript -// numbers. Specifying JS_NUMBER for the jstype causes the generated -// JavaScript code to use the JavaScript "number" type instead of strings. -// This option is an enum to permit additional types to be added, -// e.g. goog.math.Integer. -@property(nonatomic, readwrite) BOOL hasJstype; +@property(nonatomic, readwrite) BOOL hasPacked; +/// The jstype option determines the JavaScript type used for values of the +/// field. The option is permitted only for 64 bit integral and fixed types +/// (int64, uint64, sint64, fixed64, sfixed64). By default these types are +/// represented as JavaScript strings. This avoids loss of precision that can +/// happen when a large value is converted to a floating point JavaScript +/// numbers. Specifying JS_NUMBER for the jstype causes the generated +/// JavaScript code to use the JavaScript "number" type instead of strings. +/// This option is an enum to permit additional types to be added, +/// e.g. goog.math.Integer. @property(nonatomic, readwrite) GPBFieldOptions_JSType jstype; -// Should this field be parsed lazily? Lazy applies only to message-type -// fields. It means that when the outer message is initially parsed, the -// inner message's contents will not be parsed but instead stored in encoded -// form. The inner message will actually be parsed when it is first accessed. -// -// This is only a hint. Implementations are free to choose whether to use -// eager or lazy parsing regardless of the value of this option. However, -// setting this option true suggests that the protocol author believes that -// using lazy parsing on this field is worth the additional bookkeeping -// overhead typically needed to implement it. -// -// This option does not affect the public interface of any generated code; -// all method signatures remain the same. Furthermore, thread-safety of the -// interface is not affected by this option; const methods remain safe to -// call from multiple threads concurrently, while non-const methods continue -// to require exclusive access. -// -// -// Note that implementations may choose not to check required fields within -// a lazy sub-message. That is, calling IsInitialized() on the outher message -// may return true even if the inner message has missing required fields. -// This is necessary because otherwise the inner message would have to be -// parsed in order to perform the check, defeating the purpose of lazy -// parsing. An implementation which chooses not to check required fields -// must be consistent about it. That is, for any particular sub-message, the -// implementation must either *always* check its required fields, or *never* -// check its required fields, regardless of whether or not the message has -// been parsed. -@property(nonatomic, readwrite) BOOL hasLazy; +@property(nonatomic, readwrite) BOOL hasJstype; +/// Should this field be parsed lazily? Lazy applies only to message-type +/// fields. It means that when the outer message is initially parsed, the +/// inner message's contents will not be parsed but instead stored in encoded +/// form. The inner message will actually be parsed when it is first accessed. +/// +/// This is only a hint. Implementations are free to choose whether to use +/// eager or lazy parsing regardless of the value of this option. However, +/// setting this option true suggests that the protocol author believes that +/// using lazy parsing on this field is worth the additional bookkeeping +/// overhead typically needed to implement it. +/// +/// This option does not affect the public interface of any generated code; +/// all method signatures remain the same. Furthermore, thread-safety of the +/// interface is not affected by this option; const methods remain safe to +/// call from multiple threads concurrently, while non-const methods continue +/// to require exclusive access. +/// +/// +/// Note that implementations may choose not to check required fields within +/// a lazy sub-message. That is, calling IsInitialized() on the outher message +/// may return true even if the inner message has missing required fields. +/// This is necessary because otherwise the inner message would have to be +/// parsed in order to perform the check, defeating the purpose of lazy +/// parsing. An implementation which chooses not to check required fields +/// must be consistent about it. That is, for any particular sub-message, the +/// implementation must either *always* check its required fields, or *never* +/// check its required fields, regardless of whether or not the message has +/// been parsed. @property(nonatomic, readwrite) BOOL lazy; -// Is this field deprecated? -// Depending on the target platform, this can emit Deprecated annotations -// for accessors, or it will be completely ignored; in the very least, this -// is a formalization for deprecating fields. -@property(nonatomic, readwrite) BOOL hasDeprecated; +@property(nonatomic, readwrite) BOOL hasLazy; +/// Is this field deprecated? +/// Depending on the target platform, this can emit Deprecated annotations +/// for accessors, or it will be completely ignored; in the very least, this +/// is a formalization for deprecating fields. @property(nonatomic, readwrite) BOOL deprecated; -// For Google-internal migration only. Do not use. -@property(nonatomic, readwrite) BOOL hasWeak; +@property(nonatomic, readwrite) BOOL hasDeprecated; +/// For Google-internal migration only. Do not use. @property(nonatomic, readwrite) BOOL weak; -// The parser stores options it doesn't recognize here. See above. +@property(nonatomic, readwrite) BOOL hasWeak; +/// The parser stores options it doesn't recognize here. See above. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *uninterpretedOptionArray; +/// The number of items in @c uninterpretedOptionArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger uninterpretedOptionArray_Count; @end @@ -828,20 +890,21 @@ typedef GPB_ENUM(GPBEnumOptions_FieldNumber) { @interface GPBEnumOptions : GPBMessage -// Set this option to true to allow mapping different tag names to the same -// value. -@property(nonatomic, readwrite) BOOL hasAllowAlias; +/// Set this option to true to allow mapping different tag names to the same +/// value. @property(nonatomic, readwrite) BOOL allowAlias; -// Is this enum deprecated? -// Depending on the target platform, this can emit Deprecated annotations -// for the enum, or it will be completely ignored; in the very least, this -// is a formalization for deprecating enums. -@property(nonatomic, readwrite) BOOL hasDeprecated; +@property(nonatomic, readwrite) BOOL hasAllowAlias; +/// Is this enum deprecated? +/// Depending on the target platform, this can emit Deprecated annotations +/// for the enum, or it will be completely ignored; in the very least, this +/// is a formalization for deprecating enums. @property(nonatomic, readwrite) BOOL deprecated; -// The parser stores options it doesn't recognize here. See above. +@property(nonatomic, readwrite) BOOL hasDeprecated; +/// The parser stores options it doesn't recognize here. See above. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *uninterpretedOptionArray; +/// The number of items in @c uninterpretedOptionArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger uninterpretedOptionArray_Count; @end @@ -855,15 +918,16 @@ typedef GPB_ENUM(GPBEnumValueOptions_FieldNumber) { @interface GPBEnumValueOptions : GPBMessage -// Is this enum value deprecated? -// Depending on the target platform, this can emit Deprecated annotations -// for the enum value, or it will be completely ignored; in the very least, -// this is a formalization for deprecating enum values. -@property(nonatomic, readwrite) BOOL hasDeprecated; +/// Is this enum value deprecated? +/// Depending on the target platform, this can emit Deprecated annotations +/// for the enum value, or it will be completely ignored; in the very least, +/// this is a formalization for deprecating enum values. @property(nonatomic, readwrite) BOOL deprecated; -// The parser stores options it doesn't recognize here. See above. +@property(nonatomic, readwrite) BOOL hasDeprecated; +/// The parser stores options it doesn't recognize here. See above. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *uninterpretedOptionArray; +/// The number of items in @c uninterpretedOptionArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger uninterpretedOptionArray_Count; @end @@ -877,15 +941,16 @@ typedef GPB_ENUM(GPBServiceOptions_FieldNumber) { @interface GPBServiceOptions : GPBMessage -// Is this service deprecated? -// Depending on the target platform, this can emit Deprecated annotations -// for the service, or it will be completely ignored; in the very least, -// this is a formalization for deprecating services. -@property(nonatomic, readwrite) BOOL hasDeprecated; +/// Is this service deprecated? +/// Depending on the target platform, this can emit Deprecated annotations +/// for the service, or it will be completely ignored; in the very least, +/// this is a formalization for deprecating services. @property(nonatomic, readwrite) BOOL deprecated; -// The parser stores options it doesn't recognize here. See above. +@property(nonatomic, readwrite) BOOL hasDeprecated; +/// The parser stores options it doesn't recognize here. See above. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *uninterpretedOptionArray; +/// The number of items in @c uninterpretedOptionArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger uninterpretedOptionArray_Count; @end @@ -899,15 +964,16 @@ typedef GPB_ENUM(GPBMethodOptions_FieldNumber) { @interface GPBMethodOptions : GPBMessage -// Is this method deprecated? -// Depending on the target platform, this can emit Deprecated annotations -// for the method, or it will be completely ignored; in the very least, -// this is a formalization for deprecating methods. -@property(nonatomic, readwrite) BOOL hasDeprecated; +/// Is this method deprecated? +/// Depending on the target platform, this can emit Deprecated annotations +/// for the method, or it will be completely ignored; in the very least, +/// this is a formalization for deprecating methods. @property(nonatomic, readwrite) BOOL deprecated; -// The parser stores options it doesn't recognize here. See above. +@property(nonatomic, readwrite) BOOL hasDeprecated; +/// The parser stores options it doesn't recognize here. See above. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *uninterpretedOptionArray; +/// The number of items in @c uninterpretedOptionArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger uninterpretedOptionArray_Count; @end @@ -924,36 +990,40 @@ typedef GPB_ENUM(GPBUninterpretedOption_FieldNumber) { GPBUninterpretedOption_FieldNumber_AggregateValue = 8, }; -// A message representing a option the parser does not recognize. This only -// appears in options protos created by the compiler::Parser class. -// DescriptorPool resolves these when building Descriptor objects. Therefore, -// options protos in descriptor objects (e.g. returned by Descriptor::options(), -// or produced by Descriptor::CopyTo()) will never have UninterpretedOptions -// in them. +/// A message representing a option the parser does not recognize. This only +/// appears in options protos created by the compiler::Parser class. +/// DescriptorPool resolves these when building Descriptor objects. Therefore, +/// options protos in descriptor objects (e.g. returned by Descriptor::options(), +/// or produced by Descriptor::CopyTo()) will never have UninterpretedOptions +/// in them. @interface GPBUninterpretedOption : GPBMessage @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *nameArray; +/// The number of items in @c nameArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger nameArray_Count; -// The value of the uninterpreted option, in whatever type the tokenizer -// identified it as during parsing. Exactly one of these should be set. -@property(nonatomic, readwrite) BOOL hasIdentifierValue; +/// The value of the uninterpreted option, in whatever type the tokenizer +/// identified it as during parsing. Exactly one of these should be set. @property(nonatomic, readwrite, copy, null_resettable) NSString *identifierValue; +/// Test to see if @c identifierValue has been set. +@property(nonatomic, readwrite) BOOL hasIdentifierValue; -@property(nonatomic, readwrite) BOOL hasPositiveIntValue; @property(nonatomic, readwrite) uint64_t positiveIntValue; -@property(nonatomic, readwrite) BOOL hasNegativeIntValue; +@property(nonatomic, readwrite) BOOL hasPositiveIntValue; @property(nonatomic, readwrite) int64_t negativeIntValue; -@property(nonatomic, readwrite) BOOL hasDoubleValue; +@property(nonatomic, readwrite) BOOL hasNegativeIntValue; @property(nonatomic, readwrite) double doubleValue; -@property(nonatomic, readwrite) BOOL hasStringValue; +@property(nonatomic, readwrite) BOOL hasDoubleValue; @property(nonatomic, readwrite, copy, null_resettable) NSData *stringValue; +/// Test to see if @c stringValue has been set. +@property(nonatomic, readwrite) BOOL hasStringValue; -@property(nonatomic, readwrite) BOOL hasAggregateValue; @property(nonatomic, readwrite, copy, null_resettable) NSString *aggregateValue; +/// Test to see if @c aggregateValue has been set. +@property(nonatomic, readwrite) BOOL hasAggregateValue; @end @@ -964,19 +1034,20 @@ typedef GPB_ENUM(GPBUninterpretedOption_NamePart_FieldNumber) { GPBUninterpretedOption_NamePart_FieldNumber_IsExtension = 2, }; -// The name of the uninterpreted option. Each string represents a segment in -// a dot-separated name. is_extension is true iff a segment represents an -// extension (denoted with parentheses in options specs in .proto files). -// E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents -// "foo.(bar.baz).qux". +/// The name of the uninterpreted option. Each string represents a segment in +/// a dot-separated name. is_extension is true iff a segment represents an +/// extension (denoted with parentheses in options specs in .proto files). +/// E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents +/// "foo.(bar.baz).qux". @interface GPBUninterpretedOption_NamePart : GPBMessage -@property(nonatomic, readwrite) BOOL hasNamePart; @property(nonatomic, readwrite, copy, null_resettable) NSString *namePart; +/// Test to see if @c namePart has been set. +@property(nonatomic, readwrite) BOOL hasNamePart; -@property(nonatomic, readwrite) BOOL hasIsExtension; @property(nonatomic, readwrite) BOOL isExtension; +@property(nonatomic, readwrite) BOOL hasIsExtension; @end #pragma mark - GPBSourceCodeInfo @@ -985,54 +1056,55 @@ typedef GPB_ENUM(GPBSourceCodeInfo_FieldNumber) { GPBSourceCodeInfo_FieldNumber_LocationArray = 1, }; -// Encapsulates information about the original source file from which a -// FileDescriptorProto was generated. +/// Encapsulates information about the original source file from which a +/// FileDescriptorProto was generated. @interface GPBSourceCodeInfo : GPBMessage -// A Location identifies a piece of source code in a .proto file which -// corresponds to a particular definition. This information is intended -// to be useful to IDEs, code indexers, documentation generators, and similar -// tools. -// -// For example, say we have a file like: -// message Foo { -// optional string foo = 1; -// } -// Let's look at just the field definition: -// optional string foo = 1; -// ^ ^^ ^^ ^ ^^^ -// a bc de f ghi -// We have the following locations: -// span path represents -// [a,i) [ 4, 0, 2, 0 ] The whole field definition. -// [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). -// [c,d) [ 4, 0, 2, 0, 5 ] The type (string). -// [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). -// [g,h) [ 4, 0, 2, 0, 3 ] The number (1). -// -// Notes: -// - A location may refer to a repeated field itself (i.e. not to any -// particular index within it). This is used whenever a set of elements are -// logically enclosed in a single code segment. For example, an entire -// extend block (possibly containing multiple extension definitions) will -// have an outer location whose path refers to the "extensions" repeated -// field without an index. -// - Multiple locations may have the same path. This happens when a single -// logical declaration is spread out across multiple places. The most -// obvious example is the "extend" block again -- there may be multiple -// extend blocks in the same scope, each of which will have the same path. -// - A location's span is not always a subset of its parent's span. For -// example, the "extendee" of an extension declaration appears at the -// beginning of the "extend" block and is shared by all extensions within -// the block. -// - Just because a location's span is a subset of some other location's span -// does not mean that it is a descendent. For example, a "group" defines -// both a type and a field in a single declaration. Thus, the locations -// corresponding to the type and field and their components will overlap. -// - Code which tries to interpret locations should probably be designed to -// ignore those that it doesn't understand, as more types of locations could -// be recorded in the future. +/// A Location identifies a piece of source code in a .proto file which +/// corresponds to a particular definition. This information is intended +/// to be useful to IDEs, code indexers, documentation generators, and similar +/// tools. +/// +/// For example, say we have a file like: +/// message Foo { +/// optional string foo = 1; +/// } +/// Let's look at just the field definition: +/// optional string foo = 1; +/// ^ ^^ ^^ ^ ^^^ +/// a bc de f ghi +/// We have the following locations: +/// span path represents +/// [a,i) [ 4, 0, 2, 0 ] The whole field definition. +/// [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). +/// [c,d) [ 4, 0, 2, 0, 5 ] The type (string). +/// [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). +/// [g,h) [ 4, 0, 2, 0, 3 ] The number (1). +/// +/// Notes: +/// - A location may refer to a repeated field itself (i.e. not to any +/// particular index within it). This is used whenever a set of elements are +/// logically enclosed in a single code segment. For example, an entire +/// extend block (possibly containing multiple extension definitions) will +/// have an outer location whose path refers to the "extensions" repeated +/// field without an index. +/// - Multiple locations may have the same path. This happens when a single +/// logical declaration is spread out across multiple places. The most +/// obvious example is the "extend" block again -- there may be multiple +/// extend blocks in the same scope, each of which will have the same path. +/// - A location's span is not always a subset of its parent's span. For +/// example, the "extendee" of an extension declaration appears at the +/// beginning of the "extend" block and is shared by all extensions within +/// the block. +/// - Just because a location's span is a subset of some other location's span +/// does not mean that it is a descendent. For example, a "group" defines +/// both a type and a field in a single declaration. Thus, the locations +/// corresponding to the type and field and their components will overlap. +/// - Code which tries to interpret locations should probably be designed to +/// ignore those that it doesn't understand, as more types of locations could +/// be recorded in the future. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *locationArray; +/// The number of items in @c locationArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger locationArray_Count; @end @@ -1049,94 +1121,99 @@ typedef GPB_ENUM(GPBSourceCodeInfo_Location_FieldNumber) { @interface GPBSourceCodeInfo_Location : GPBMessage -// Identifies which part of the FileDescriptorProto was defined at this -// location. -// -// Each element is a field number or an index. They form a path from -// the root FileDescriptorProto to the place where the definition. For -// example, this path: -// [ 4, 3, 2, 7, 1 ] -// refers to: -// file.message_type(3) // 4, 3 -// .field(7) // 2, 7 -// .name() // 1 -// This is because FileDescriptorProto.message_type has field number 4: -// repeated DescriptorProto message_type = 4; -// and DescriptorProto.field has field number 2: -// repeated FieldDescriptorProto field = 2; -// and FieldDescriptorProto.name has field number 1: -// optional string name = 1; -// -// Thus, the above path gives the location of a field name. If we removed -// the last element: -// [ 4, 3, 2, 7 ] -// this path refers to the whole field declaration (from the beginning -// of the label to the terminating semicolon). +/// Identifies which part of the FileDescriptorProto was defined at this +/// location. +/// +/// Each element is a field number or an index. They form a path from +/// the root FileDescriptorProto to the place where the definition. For +/// example, this path: +/// [ 4, 3, 2, 7, 1 ] +/// refers to: +/// file.message_type(3) // 4, 3 +/// .field(7) // 2, 7 +/// .name() // 1 +/// This is because FileDescriptorProto.message_type has field number 4: +/// repeated DescriptorProto message_type = 4; +/// and DescriptorProto.field has field number 2: +/// repeated FieldDescriptorProto field = 2; +/// and FieldDescriptorProto.name has field number 1: +/// optional string name = 1; +/// +/// Thus, the above path gives the location of a field name. If we removed +/// the last element: +/// [ 4, 3, 2, 7 ] +/// this path refers to the whole field declaration (from the beginning +/// of the label to the terminating semicolon). @property(nonatomic, readwrite, strong, null_resettable) GPBInt32Array *pathArray; +/// The number of items in @c pathArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger pathArray_Count; -// Always has exactly three or four elements: start line, start column, -// end line (optional, otherwise assumed same as start line), end column. -// These are packed into a single field for efficiency. Note that line -// and column numbers are zero-based -- typically you will want to add -// 1 to each before displaying to a user. +/// Always has exactly three or four elements: start line, start column, +/// end line (optional, otherwise assumed same as start line), end column. +/// These are packed into a single field for efficiency. Note that line +/// and column numbers are zero-based -- typically you will want to add +/// 1 to each before displaying to a user. @property(nonatomic, readwrite, strong, null_resettable) GPBInt32Array *spanArray; +/// The number of items in @c spanArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger spanArray_Count; -// If this SourceCodeInfo represents a complete declaration, these are any -// comments appearing before and after the declaration which appear to be -// attached to the declaration. -// -// A series of line comments appearing on consecutive lines, with no other -// tokens appearing on those lines, will be treated as a single comment. -// -// leading_detached_comments will keep paragraphs of comments that appear -// before (but not connected to) the current element. Each paragraph, -// separated by empty lines, will be one comment element in the repeated -// field. -// -// Only the comment content is provided; comment markers (e.g. //) are -// stripped out. For block comments, leading whitespace and an asterisk -// will be stripped from the beginning of each line other than the first. -// Newlines are included in the output. -// -// Examples: -// -// optional int32 foo = 1; // Comment attached to foo. -// // Comment attached to bar. -// optional int32 bar = 2; -// -// optional string baz = 3; -// // Comment attached to baz. -// // Another line attached to baz. -// -// // Comment attached to qux. -// // -// // Another line attached to qux. -// optional double qux = 4; -// -// // Detached comment for corge. This is not leading or trailing comments -// // to qux or corge because there are blank lines separating it from -// // both. -// -// // Detached comment for corge paragraph 2. -// -// optional string corge = 5; -// /* Block comment attached -// * to corge. Leading asterisks -// * will be removed. */ -// /* Block comment attached to -// * grault. */ -// optional int32 grault = 6; -// -// // ignored detached comments. -@property(nonatomic, readwrite) BOOL hasLeadingComments; +/// If this SourceCodeInfo represents a complete declaration, these are any +/// comments appearing before and after the declaration which appear to be +/// attached to the declaration. +/// +/// A series of line comments appearing on consecutive lines, with no other +/// tokens appearing on those lines, will be treated as a single comment. +/// +/// leading_detached_comments will keep paragraphs of comments that appear +/// before (but not connected to) the current element. Each paragraph, +/// separated by empty lines, will be one comment element in the repeated +/// field. +/// +/// Only the comment content is provided; comment markers (e.g. //) are +/// stripped out. For block comments, leading whitespace and an asterisk +/// will be stripped from the beginning of each line other than the first. +/// Newlines are included in the output. +/// +/// Examples: +/// +/// optional int32 foo = 1; // Comment attached to foo. +/// // Comment attached to bar. +/// optional int32 bar = 2; +/// +/// optional string baz = 3; +/// // Comment attached to baz. +/// // Another line attached to baz. +/// +/// // Comment attached to qux. +/// // +/// // Another line attached to qux. +/// optional double qux = 4; +/// +/// // Detached comment for corge. This is not leading or trailing comments +/// // to qux or corge because there are blank lines separating it from +/// // both. +/// +/// // Detached comment for corge paragraph 2. +/// +/// optional string corge = 5; +/// /* Block comment attached +/// * to corge. Leading asterisks +/// * will be removed. */ +/// /* Block comment attached to +/// * grault. */ +/// optional int32 grault = 6; +/// +/// // ignored detached comments. @property(nonatomic, readwrite, copy, null_resettable) NSString *leadingComments; +/// Test to see if @c leadingComments has been set. +@property(nonatomic, readwrite) BOOL hasLeadingComments; -@property(nonatomic, readwrite) BOOL hasTrailingComments; @property(nonatomic, readwrite, copy, null_resettable) NSString *trailingComments; +/// Test to see if @c trailingComments has been set. +@property(nonatomic, readwrite) BOOL hasTrailingComments; @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *leadingDetachedCommentsArray; +/// The number of items in @c leadingDetachedCommentsArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger leadingDetachedCommentsArray_Count; @end @@ -1147,14 +1224,15 @@ typedef GPB_ENUM(GPBGeneratedCodeInfo_FieldNumber) { GPBGeneratedCodeInfo_FieldNumber_AnnotationArray = 1, }; -// Describes the relationship between generated code and its original source -// file. A GeneratedCodeInfo message is associated with only one generated -// source file, but may contain references to different source .proto files. +/// Describes the relationship between generated code and its original source +/// file. A GeneratedCodeInfo message is associated with only one generated +/// source file, but may contain references to different source .proto files. @interface GPBGeneratedCodeInfo : GPBMessage -// An Annotation connects some span of text in generated code to an element -// of its generating .proto file. +/// An Annotation connects some span of text in generated code to an element +/// of its generating .proto file. @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray *annotationArray; +/// The number of items in @c annotationArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger annotationArray_Count; @end @@ -1170,26 +1248,28 @@ typedef GPB_ENUM(GPBGeneratedCodeInfo_Annotation_FieldNumber) { @interface GPBGeneratedCodeInfo_Annotation : GPBMessage -// Identifies the element in the original source .proto file. This field -// is formatted the same as SourceCodeInfo.Location.path. +/// Identifies the element in the original source .proto file. This field +/// is formatted the same as SourceCodeInfo.Location.path. @property(nonatomic, readwrite, strong, null_resettable) GPBInt32Array *pathArray; +/// The number of items in @c pathArray without causing the array to be created. @property(nonatomic, readonly) NSUInteger pathArray_Count; -// Identifies the filesystem path to the original source .proto. -@property(nonatomic, readwrite) BOOL hasSourceFile; +/// Identifies the filesystem path to the original source .proto. @property(nonatomic, readwrite, copy, null_resettable) NSString *sourceFile; +/// Test to see if @c sourceFile has been set. +@property(nonatomic, readwrite) BOOL hasSourceFile; -// Identifies the starting offset in bytes in the generated code -// that relates to the identified object. -@property(nonatomic, readwrite) BOOL hasBegin; +/// Identifies the starting offset in bytes in the generated code +/// that relates to the identified object. @property(nonatomic, readwrite) int32_t begin; -// Identifies the ending offset in bytes in the generated code that -// relates to the identified offset. The end offset should be one past -// the last relevant byte (so the length of the text = end - begin). -@property(nonatomic, readwrite) BOOL hasEnd; +@property(nonatomic, readwrite) BOOL hasBegin; +/// Identifies the ending offset in bytes in the generated code that +/// relates to the identified offset. The end offset should be one past +/// the last relevant byte (so the length of the text = end - begin). @property(nonatomic, readwrite) int32_t end; +@property(nonatomic, readwrite) BOOL hasEnd; @end NS_ASSUME_NONNULL_END diff --git a/objectivec/google/protobuf/Duration.pbobjc.h b/objectivec/google/protobuf/Duration.pbobjc.h index b592640b..ebf9119e 100644 --- a/objectivec/google/protobuf/Duration.pbobjc.h +++ b/objectivec/google/protobuf/Duration.pbobjc.h @@ -15,13 +15,15 @@ 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. @interface GPBDurationRoot : GPBRootObject - -// The base class provides: -// + (GPBExtensionRegistry *)extensionRegistry; -// which is an GPBExtensionRegistry that includes all the extensions defined by -// this file and all files that it depends on. - @end #pragma mark - GPBDuration @@ -31,58 +33,58 @@ 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 bace614d..ca09f71d 100644 --- a/objectivec/google/protobuf/Empty.pbobjc.h +++ b/objectivec/google/protobuf/Empty.pbobjc.h @@ -15,26 +15,28 @@ 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. @interface GPBEmptyRoot : GPBRootObject - -// The base class provides: -// + (GPBExtensionRegistry *)extensionRegistry; -// which is an GPBExtensionRegistry that includes all the extensions defined by -// this file and all files that it depends on. - @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 f4bc2653..f861a986 100644 --- a/objectivec/google/protobuf/FieldMask.pbobjc.h +++ b/objectivec/google/protobuf/FieldMask.pbobjc.h @@ -15,13 +15,15 @@ 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. @interface GPBFieldMaskRoot : GPBRootObject - -// The base class provides: -// + (GPBExtensionRegistry *)extensionRegistry; -// which is an GPBExtensionRegistry that includes all the extensions defined by -// this file and all files that it depends on. - @end #pragma mark - GPBFieldMask @@ -30,132 +32,133 @@ 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 applies 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. -// -// 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" -// } +/// `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 applies 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. +/// +/// 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" +/// } @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. @property(nonatomic, readonly) NSUInteger pathsArray_Count; @end diff --git a/objectivec/google/protobuf/SourceContext.pbobjc.h b/objectivec/google/protobuf/SourceContext.pbobjc.h index 8480db1d..546db674 100644 --- a/objectivec/google/protobuf/SourceContext.pbobjc.h +++ b/objectivec/google/protobuf/SourceContext.pbobjc.h @@ -15,13 +15,15 @@ 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. @interface GPBSourceContextRoot : GPBRootObject - -// The base class provides: -// + (GPBExtensionRegistry *)extensionRegistry; -// which is an GPBExtensionRegistry that includes all the extensions defined by -// this file and all files that it depends on. - @end #pragma mark - GPBSourceContext @@ -30,12 +32,12 @@ 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.proto"`. +/// The path-qualified name of the .proto file that contained the associated +/// protobuf element. For example: `"google/protobuf/source.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 293dea40..7b9c45a0 100644 --- a/objectivec/google/protobuf/Struct.pbobjc.h +++ b/objectivec/google/protobuf/Struct.pbobjc.h @@ -19,29 +19,36 @@ 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. 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. 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. @interface GPBStructRoot : GPBRootObject - -// The base class provides: -// + (GPBExtensionRegistry *)extensionRegistry; -// which is an GPBExtensionRegistry that includes all the extensions defined by -// this file and all files that it depends on. - @end #pragma mark - GPBStruct @@ -50,18 +57,19 @@ 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 -// Map of dynamically typed values. +/// 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. @property(nonatomic, readonly) NSUInteger fields_Count; @end @@ -87,40 +95,46 @@ 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. 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. void SetGPBValue_NullValue_RawValue(GPBValue *message, int32_t value); +/// Clears whatever value was set for the oneof 'kind'. void GPBValue_ClearKindOneOfCase(GPBValue *message); #pragma mark - GPBListValue @@ -129,13 +143,14 @@ 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. @property(nonatomic, readonly) NSUInteger valuesArray_Count; @end diff --git a/objectivec/google/protobuf/Timestamp.pbobjc.h b/objectivec/google/protobuf/Timestamp.pbobjc.h index 79b24ec6..d17c2860 100644 --- a/objectivec/google/protobuf/Timestamp.pbobjc.h +++ b/objectivec/google/protobuf/Timestamp.pbobjc.h @@ -15,13 +15,15 @@ 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. @interface GPBTimestampRoot : GPBRootObject - -// The base class provides: -// + (GPBExtensionRegistry *)extensionRegistry; -// which is an GPBExtensionRegistry that includes all the extensions defined by -// this file and all files that it depends on. - @end #pragma mark - GPBTimestamp @@ -31,70 +33,70 @@ 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 a7d03a2a..9301e4f4 100644 --- a/objectivec/google/protobuf/Type.pbobjc.h +++ b/objectivec/google/protobuf/Type.pbobjc.h @@ -21,118 +21,135 @@ 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. 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. 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. 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. 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. 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. 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. @interface GPBTypeRoot : GPBRootObject - -// The base class provides: -// + (GPBExtensionRegistry *)extensionRegistry; -// which is an GPBExtensionRegistry that includes all the extensions defined by -// this file and all files that it depends on. - @end #pragma mark - GPBType @@ -146,34 +163,43 @@ 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. @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. @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. @property(nonatomic, readonly) NSUInteger optionsArray_Count; -// The source context. -@property(nonatomic, readwrite) BOOL hasSourceContext; +/// The source context. @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext; +/// 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. 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. void SetGPBType_Syntax_RawValue(GPBType *message, int32_t value); #pragma mark - GPBField @@ -191,48 +217,59 @@ 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. @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. 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. 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. 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. void SetGPBField_Cardinality_RawValue(GPBField *message, int32_t value); #pragma mark - GPBEnum @@ -245,30 +282,38 @@ 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. @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. @property(nonatomic, readonly) NSUInteger optionsArray_Count; -// The source context. -@property(nonatomic, readwrite) BOOL hasSourceContext; +/// The source context. @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext; +/// 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. 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. void SetGPBEnum_Syntax_RawValue(GPBEnum *message, int32_t value); #pragma mark - GPBEnumValue @@ -279,17 +324,18 @@ 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. @property(nonatomic, readonly) NSUInteger optionsArray_Count; @end @@ -301,16 +347,17 @@ 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"`. -@property(nonatomic, readwrite) BOOL hasValue; +/// 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. +@property(nonatomic, readwrite) BOOL hasValue; @end diff --git a/objectivec/google/protobuf/Wrappers.pbobjc.h b/objectivec/google/protobuf/Wrappers.pbobjc.h index 580945c4..38b99622 100644 --- a/objectivec/google/protobuf/Wrappers.pbobjc.h +++ b/objectivec/google/protobuf/Wrappers.pbobjc.h @@ -15,13 +15,15 @@ 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. @interface GPBWrappersRoot : GPBRootObject - -// The base class provides: -// + (GPBExtensionRegistry *)extensionRegistry; -// which is an GPBExtensionRegistry that includes all the extensions defined by -// this file and all files that it depends on. - @end #pragma mark - GPBDoubleValue @@ -30,12 +32,12 @@ 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 @@ -46,12 +48,12 @@ 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 @@ -62,12 +64,12 @@ 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 @@ -78,12 +80,12 @@ 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 @@ -94,12 +96,12 @@ 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 @@ -110,12 +112,12 @@ 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 @@ -126,12 +128,12 @@ 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 @@ -142,12 +144,12 @@ 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 @@ -158,12 +160,12 @@ 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 -- cgit v1.2.3