field_mask.rb in google-cloud-pubsub-0.24.0

- old
+ new

@@ -55,11 +55,11 @@
     #         d : 1
     #       }
     #     }
     #
     # A repeated field is not allowed except at the last position of a
-    # field mask.
+    # paths string.
     #
     # 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).
     #
@@ -79,9 +79,61 @@
     # 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 +paths+
+    # string.
+    #
+    # 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
\ No newline at end of file