add documentation

Author: pouyayarandi

Documentation/API.md

@@ -615,6 +615,16 @@ public func -(lhs: Google_Protobuf_Timestamp, rhs: Google_Protobuf_Duration) ->
 public func +(lhs: Google_Protobuf_Timestamp, rhs: Google_Protobuf_Duration) -> Google_Protobuf_Timestamp
 ```
 
+## Google_Protobuf_FieldMask
+
+The `Google_Protobuf_FieldMask` contains a list of field paths, where each path is a string that identifies a particular field or nested field in the message. This is particularly useful for selectively updating or trimming messages.
+
+```protobuf
+message FieldMask {
+  // The set of field mask paths.
+  repeated string paths = 1;
+}
+```
 
 ## Extensions
 
@@ -696,6 +706,69 @@ Descriptor objects. It is something that could get revisited in the future,
 but will need careful consideration; the bloat/size issues is of the most
 concern because of Swift's common use for mobile applications.
 
+## FieldMask Utilities
+
+### Merging Two Messages
+
+The `merge(from:fieldMask:)` function in Swift Protobuf enables developers to selectively merge fields from one message into another, guided by a `Google_Protobuf_FieldMask`. This method is particularly useful when you need to update only specific fields in a message without affecting others. The `merge` function is available as a method on `Message` types and requires two parameters: the source message (`from`) containing the data to merge and the `fieldMask` that specifies which fields should be updated.
+
+For example, consider a message with the following structure:
+
+```protobuf
+message ExampleMessage {
+  string foo = 1;
+  string bar = 2;
+}
+```
+
+Assume we have two instances of `ExampleMessage`:
+
+```swift
+let message1: ExampleMessage = .with { $0.foo = "foo1" }
+let message2: ExampleMessage = .with { $0.bar = "bar2" }
+```
+
+To merge `message2` into `message1` but only update the `bar` field, you can define a `Google_Protobuf_FieldMask` like this:
+
+```swift
+let fieldMask = Google_Protobuf_FieldMask.with { $0.paths = ["bar"] }
+```
+
+Then, you apply the merge:
+
+```swift
+try message1.merge(from: message2, fieldMask: fieldMask)
+```
+
+After this operation, `message1.bar` will have the value `"bar2"` from `message2`, while `message1.foo` remains `"foo1"`. The `merge` function operates in-place, meaning it directly modifies `message1`. This targeted approach is beneficial when handling partial updates, as it prevents unintended changes to other fields. Proper configuration of the `fieldMask` is essential to ensure that only the desired fields are updated. Additionally, since the `merge` function may throw errors if the operation fails, it's important to handle these exceptions appropriately. This API is a powerful tool for managing partial updates in protocol buffer messages, providing developers with precise control over the merging process.
+
+### Trimming a Message
+
+The `trim(keeping:)` function allows developers to retain only specific fields in a protocol buffer message while clearing the rest. This function is particularly useful when you want to ensure that only certain fields are preserved in a message, effectively "trimming" the message to contain just the necessary data.
+
+Consider the `ExampleMessage` structure from the previous example. Suppose you have an instance of `ExampleMessage` initialized as follows:
+
+```swift
+let message = ExampleMessage.with {
+  $0.foo = "foo"
+  $0.bar = "bar"
+}
+```
+
+If you want to trim this message so that only the `bar` field retains its value, you can define a `Google_Protobuf_FieldMask` like this:
+
+```swift
+let fieldMask = Google_Protobuf_FieldMask.with { $0.paths = ["bar"] }
+```
+
+Then, you apply the `trim` function:
+
+```swift
+message.trim(keeping: fieldMask)
+```
+
+After this operation, the `bar` field in `message` will still have the value `"bar"`, while the `foo` field will be cleared, resetting to its default value (an empty string, in this case). The `trim(keeping:)` function is performed in-place, meaning it directly modifies the original message. This function is ideal for scenarios where it's necessary to remove all but a few specified fields, ensuring that the resulting message contains only the data you want to keep. This precise control over the message structure can be essential when working with large or complex messages, where only a subset of the data is relevant for a particular operation or transmission. The `trim` function enhances the flexibility of message management in Swift Protobuf, making it easier to handle scenarios where selective field retention is required.
+
 ## Aside:  proto2 vs. proto3
 
 The terms *proto2* and *proto3* refer to two different dialects of the proto