field_mask.proto in grpc-tools-1.0.0.pre2

- old
+ new
@@ -105,9 +105,61 @@
 // 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.