diff options
author | Sergio Campamá <kaipi@google.com> | 2016-08-09 05:26:24 -0700 |
---|---|---|
committer | Thomas Van Lenten <thomasvl@google.com> | 2016-08-09 08:26:24 -0400 |
commit | 237f321e338b50503eb38728afa6ad29bea6076a (patch) | |
tree | 0b6c77f4349b1fdb223c59179e286fb83d70ddc7 /objectivec/google/protobuf/FieldMask.pbobjc.h | |
parent | 56b8f44eede93463f7ec4fbecd5bc7dfc8d6d648 (diff) | |
download | protobuf-237f321e338b50503eb38728afa6ad29bea6076a.tar.gz protobuf-237f321e338b50503eb38728afa6ad29bea6076a.tar.bz2 protobuf-237f321e338b50503eb38728afa6ad29bea6076a.zip |
Adds support for appledoc in generated code. (#1928)
Convert mapping of proto comments to appledoc format so they show up in Xcode and cocoadocs.
Fixes https://github.com/google/protobuf/issues/1866
Diffstat (limited to 'objectivec/google/protobuf/FieldMask.pbobjc.h')
-rw-r--r-- | objectivec/google/protobuf/FieldMask.pbobjc.h | 426 |
1 files changed, 215 insertions, 211 deletions
diff --git a/objectivec/google/protobuf/FieldMask.pbobjc.h b/objectivec/google/protobuf/FieldMask.pbobjc.h index 06053f1a..175db600 100644 --- a/objectivec/google/protobuf/FieldMask.pbobjc.h +++ b/objectivec/google/protobuf/FieldMask.pbobjc.h @@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - GPBFieldMaskRoot -/// Exposes the extension registry for this file. -/// -/// The base class provides: -/// @code -/// + (GPBExtensionRegistry *)extensionRegistry; -/// @endcode -/// which is a @c GPBExtensionRegistry that includes all the extensions defined by -/// this file and all files that it depends on. +/** + * Exposes the extension registry for this file. + * + * The base class provides: + * @code + * + (GPBExtensionRegistry *)extensionRegistry; + * @endcode + * which is a @c GPBExtensionRegistry that includes all the extensions defined by + * this file and all files that it depends on. + **/ @interface GPBFieldMaskRoot : GPBRootObject @end @@ -45,212 +47,214 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) { GPBFieldMask_FieldNumber_PathsArray = 1, }; -/// `FieldMask` represents a set of symbolic field paths, for example: -/// -/// paths: "f.a" -/// paths: "f.b.d" -/// -/// Here `f` represents a field in some root message, `a` and `b` -/// fields in the message found in `f`, and `d` a field found in the -/// message in `f.b`. -/// -/// Field masks are used to specify a subset of fields that should be -/// returned by a get operation or modified by an update operation. -/// Field masks also have a custom JSON encoding (see below). -/// -/// # Field Masks in Projections -/// -/// When used in the context of a projection, a response message or -/// sub-message is filtered by the API to only contain those fields as -/// specified in the mask. For example, if the mask in the previous -/// example is applied to a response message as follows: -/// -/// f { -/// a : 22 -/// b { -/// d : 1 -/// x : 2 -/// } -/// y : 13 -/// } -/// z: 8 -/// -/// The result will not contain specific values for fields x,y and z -/// (their value will be set to the default, and omitted in proto text -/// output): -/// -/// -/// f { -/// a : 22 -/// b { -/// d : 1 -/// } -/// } -/// -/// A repeated field is not allowed except at the last position of a -/// field mask. -/// -/// If a FieldMask object is not present in a get operation, the -/// operation applies to all fields (as if a FieldMask of all fields -/// had been specified). -/// -/// Note that a field mask does not necessarily apply to the -/// top-level response message. In case of a REST get operation, the -/// field mask applies directly to the response, but in case of a REST -/// list operation, the mask instead applies to each individual message -/// in the returned resource list. In case of a REST custom method, -/// other definitions may be used. Where the mask applies will be -/// clearly documented together with its declaration in the API. In -/// any case, the effect on the returned resource/resources is required -/// behavior for APIs. -/// -/// # Field Masks in Update Operations -/// -/// A field mask in update operations specifies which fields of the -/// targeted resource are going to be updated. The API is required -/// to only change the values of the fields as specified in the mask -/// and leave the others untouched. If a resource is passed in to -/// describe the updated values, the API ignores the values of all -/// fields not covered by the mask. -/// -/// If a repeated field is specified for an update operation, the existing -/// repeated values in the target resource will be overwritten by the new values. -/// Note that a repeated field is only allowed in the last position of a field -/// mask. -/// -/// If a sub-message is specified in the last position of the field mask for an -/// update operation, then the existing sub-message in the target resource is -/// overwritten. Given the target message: -/// -/// f { -/// b { -/// d : 1 -/// x : 2 -/// } -/// c : 1 -/// } -/// -/// And an update message: -/// -/// f { -/// b { -/// d : 10 -/// } -/// } -/// -/// then if the field mask is: -/// -/// paths: "f.b" -/// -/// then the result will be: -/// -/// f { -/// b { -/// d : 10 -/// } -/// c : 1 -/// } -/// -/// However, if the update mask was: -/// -/// paths: "f.b.d" -/// -/// then the result would be: -/// -/// f { -/// b { -/// d : 10 -/// x : 2 -/// } -/// c : 1 -/// } -/// -/// In order to reset a field's value to the default, the field must -/// be in the mask and set to the default value in the provided resource. -/// Hence, in order to reset all fields of a resource, provide a default -/// instance of the resource and set all fields in the mask, or do -/// not provide a mask as described below. -/// -/// If a field mask is not present on update, the operation applies to -/// all fields (as if a field mask of all fields has been specified). -/// Note that in the presence of schema evolution, this may mean that -/// fields the client does not know and has therefore not filled into -/// the request will be reset to their default. If this is unwanted -/// behavior, a specific service may require a client to always specify -/// a field mask, producing an error if not. -/// -/// As with get operations, the location of the resource which -/// describes the updated values in the request message depends on the -/// operation kind. In any case, the effect of the field mask is -/// required to be honored by the API. -/// -/// ## Considerations for HTTP REST -/// -/// The HTTP kind of an update operation which uses a field mask must -/// be set to PATCH instead of PUT in order to satisfy HTTP semantics -/// (PUT must only be used for full updates). -/// -/// # JSON Encoding of Field Masks -/// -/// In JSON, a field mask is encoded as a single string where paths are -/// separated by a comma. Fields name in each path are converted -/// to/from lower-camel naming conventions. -/// -/// As an example, consider the following message declarations: -/// -/// message Profile { -/// User user = 1; -/// Photo photo = 2; -/// } -/// message User { -/// string display_name = 1; -/// string address = 2; -/// } -/// -/// In proto a field mask for `Profile` may look as such: -/// -/// mask { -/// paths: "user.display_name" -/// paths: "photo" -/// } -/// -/// In JSON, the same mask is represented as below: -/// -/// { -/// mask: "user.displayName,photo" -/// } -/// -/// # Field Masks and Oneof Fields -/// -/// Field masks treat fields in oneofs just as regular fields. Consider the -/// following message: -/// -/// message SampleMessage { -/// oneof test_oneof { -/// string name = 4; -/// SubMessage sub_message = 9; -/// } -/// } -/// -/// The field mask can be: -/// -/// mask { -/// paths: "name" -/// } -/// -/// Or: -/// -/// mask { -/// paths: "sub_message" -/// } -/// -/// Note that oneof type names ("test_oneof" in this case) cannot be used in -/// paths. +/** + * `FieldMask` represents a set of symbolic field paths, for example: + * + * paths: "f.a" + * paths: "f.b.d" + * + * Here `f` represents a field in some root message, `a` and `b` + * fields in the message found in `f`, and `d` a field found in the + * message in `f.b`. + * + * Field masks are used to specify a subset of fields that should be + * returned by a get operation or modified by an update operation. + * Field masks also have a custom JSON encoding (see below). + * + * # Field Masks in Projections + * + * When used in the context of a projection, a response message or + * sub-message is filtered by the API to only contain those fields as + * specified in the mask. For example, if the mask in the previous + * example is applied to a response message as follows: + * + * f { + * a : 22 + * b { + * d : 1 + * x : 2 + * } + * y : 13 + * } + * z: 8 + * + * The result will not contain specific values for fields x,y and z + * (their value will be set to the default, and omitted in proto text + * output): + * + * + * f { + * a : 22 + * b { + * d : 1 + * } + * } + * + * A repeated field is not allowed except at the last position of a + * field mask. + * + * If a FieldMask object is not present in a get operation, the + * operation applies to all fields (as if a FieldMask of all fields + * had been specified). + * + * Note that a field mask does not necessarily apply to the + * top-level response message. In case of a REST get operation, the + * field mask applies directly to the response, but in case of a REST + * list operation, the mask instead applies to each individual message + * in the returned resource list. In case of a REST custom method, + * other definitions may be used. Where the mask applies will be + * clearly documented together with its declaration in the API. In + * any case, the effect on the returned resource/resources is required + * behavior for APIs. + * + * # Field Masks in Update Operations + * + * A field mask in update operations specifies which fields of the + * targeted resource are going to be updated. The API is required + * to only change the values of the fields as specified in the mask + * and leave the others untouched. If a resource is passed in to + * describe the updated values, the API ignores the values of all + * fields not covered by the mask. + * + * If a repeated field is specified for an update operation, the existing + * repeated values in the target resource will be overwritten by the new values. + * Note that a repeated field is only allowed in the last position of a field + * mask. + * + * If a sub-message is specified in the last position of the field mask for an + * update operation, then the existing sub-message in the target resource is + * overwritten. Given the target message: + * + * f { + * b { + * d : 1 + * x : 2 + * } + * c : 1 + * } + * + * And an update message: + * + * f { + * b { + * d : 10 + * } + * } + * + * then if the field mask is: + * + * paths: "f.b" + * + * then the result will be: + * + * f { + * b { + * d : 10 + * } + * c : 1 + * } + * + * However, if the update mask was: + * + * paths: "f.b.d" + * + * then the result would be: + * + * f { + * b { + * d : 10 + * x : 2 + * } + * c : 1 + * } + * + * In order to reset a field's value to the default, the field must + * be in the mask and set to the default value in the provided resource. + * Hence, in order to reset all fields of a resource, provide a default + * instance of the resource and set all fields in the mask, or do + * not provide a mask as described below. + * + * If a field mask is not present on update, the operation applies to + * all fields (as if a field mask of all fields has been specified). + * Note that in the presence of schema evolution, this may mean that + * fields the client does not know and has therefore not filled into + * the request will be reset to their default. If this is unwanted + * behavior, a specific service may require a client to always specify + * a field mask, producing an error if not. + * + * As with get operations, the location of the resource which + * describes the updated values in the request message depends on the + * operation kind. In any case, the effect of the field mask is + * required to be honored by the API. + * + * ## Considerations for HTTP REST + * + * The HTTP kind of an update operation which uses a field mask must + * be set to PATCH instead of PUT in order to satisfy HTTP semantics + * (PUT must only be used for full updates). + * + * # JSON Encoding of Field Masks + * + * In JSON, a field mask is encoded as a single string where paths are + * separated by a comma. Fields name in each path are converted + * to/from lower-camel naming conventions. + * + * As an example, consider the following message declarations: + * + * message Profile { + * User user = 1; + * Photo photo = 2; + * } + * message User { + * string display_name = 1; + * string address = 2; + * } + * + * In proto a field mask for `Profile` may look as such: + * + * mask { + * paths: "user.display_name" + * paths: "photo" + * } + * + * In JSON, the same mask is represented as below: + * + * { + * mask: "user.displayName,photo" + * } + * + * # Field Masks and Oneof Fields + * + * Field masks treat fields in oneofs just as regular fields. Consider the + * following message: + * + * message SampleMessage { + * oneof test_oneof { + * string name = 4; + * SubMessage sub_message = 9; + * } + * } + * + * The field mask can be: + * + * mask { + * paths: "name" + * } + * + * Or: + * + * mask { + * paths: "sub_message" + * } + * + * Note that oneof type names ("test_oneof" in this case) cannot be used in + * paths. + **/ @interface GPBFieldMask : GPBMessage -/// The set of field mask paths. +/** The set of field mask paths. */ @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<NSString*> *pathsArray; -/// The number of items in @c pathsArray without causing the array to be created. +/** The number of items in @c pathsArray without causing the array to be created. */ @property(nonatomic, readonly) NSUInteger pathsArray_Count; @end |