From cff900e8f9e4b8f3a8f314f0f44eab222ebb870b Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Fri, 6 Nov 2015 18:38:31 +0000 Subject: Generated code for previous commit. --- .../Google.Protobuf/WellKnownTypes/FieldMask.cs | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs') diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs b/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs index 33c814ef..e71e4af6 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs @@ -42,19 +42,25 @@ namespace Google.Protobuf.WellKnownTypes { #region Messages /// /// `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 { @@ -64,20 +70,25 @@ namespace Google.Protobuf.WellKnownTypes { /// y : 13 /// } /// z: 8 + /// /// The result will not contain specific values for fields x,y and z /// (there 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 @@ -87,18 +98,22 @@ namespace Google.Protobuf.WellKnownTypes { /// 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 @@ -106,19 +121,26 @@ namespace Google.Protobuf.WellKnownTypes { /// 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; @@ -127,12 +149,16 @@ namespace Google.Protobuf.WellKnownTypes { /// 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" /// } -- cgit v1.2.3