docs: Add product neutral documentation and examples.

- Show retry example
- Add documentation and examples for update masks and updates with optimistic concurrency control.

Author: bshaffer

docs/devsite-help/call-settings.md

@@ -113,3 +113,5 @@ The backoff between retries is more complex. It consists of:
 
 - [RetrySettings.FromConstantBackoff](xref:Google.Api.Gax.Grpc.RetrySettings#Google_Api_Gax_Grpc_RetrySettings_FromConstantBackoff_System_Int32_System_TimeSpan_System_Predicate_System_Exception__Google_Api_Gax_Grpc_RetrySettings_IJitter_) which uses a multiplier of 1 and no maximum (because it's constant)
 - [RetrySettings.FromExponentialBackoff](xref:Google.Api.Gax.Grpc.RetrySettings#Google_Api_Gax_Grpc_RetrySettings_FromExponentialBackoff_System_Int32_System_TimeSpan_System_TimeSpan_System_Double_System_Predicate_System_Exception__Google_Api_Gax_Grpc_RetrySettings_IJitter_) which allows every aspect to be specified
+
+[!code-cs[](../examples/help.CallSettings.txt#RetrySettingsTiming)]

docs/devsite-help/occ.md

@@ -0,0 +1,15 @@
+# Optimistic Concurrency Control (OCC)
+
+## Introduction to OCC
+
+Optimistic Concurrency Control (OCC) is a strategy used to manage shared resources and prevent "lost updates" or race conditions when multiple users or processes attempt to modify the same resource simultaneously.
+
+Google API resources contain an `Etag` property used by the server to control for optimistic concurrency. If the `Etag` value provided when modifying a resource does not match the current value on the server, it returns an error, usually with status `Aborted` (Check the documentation of the API you are using for specific OCC error codes).
+
+## OCC Steps demonstrated with IAM
+
+### Example
+
+The following example demonstrates how to implement OCC with IAM and the `Google.Cloud.PubSub.V1` library.
+
+[!code-cs[](../examples/help.Occ.txt#OccForIam)]

docs/devsite-help/toc.yml

@@ -28,6 +28,8 @@
     href: long-running-operations.md
   - name: Pagination (page streaming)
     href: page-streaming.md
+  - name: Update masks
+    href: update-masks.md
   - name: Resource names and IDs
     href: resource-names.md
   - name: API layers
@@ -36,6 +38,8 @@
     href: call-settings.md
   - name: Streaming RPCs
     href: grpc-streaming.md
+  - name: OCC
+    href: occ.md
   - name: Resource clean-up
     href: cleanup.md
   - name: Versioning

docs/devsite-help/update-masks.md

@@ -0,0 +1,19 @@
+# Update Masks
+
+## Optimizing Resource Updates with FieldMask
+
+When updating resources (often corresponding to HTTP PATCH requests) in Google Cloud APIs, you generally use an **Update Mask** (represented by `Google.Protobuf.WellKnownTypes.FieldMask`).
+
+The purpose of the Update Mask is to tell the server exactly which fields you intend to modify, preventing accidental overwrites or resetting of other fields that you did not include in your request object.
+
+By providing a `FieldMask`, you explicitly declare the subset of fields in the resource object that should be updated.
+
+## Constructing and Applying the FieldMask
+
+The `FieldMask` object is part of the `Google.Protobuf` library and contains a collection of strings representing the fields paths to be modified.
+
+**Crucial Point:** The strings in the `FieldMask.Paths` collection **must** correspond to the **original** field names defined in the Protocol Buffer (protobuf) schema, not the C\# property names (which are PascalCase).
+
+## Example
+
+[!code-cs[](../examples/help.UpdateMask.txt#UpdateMasks)]

tools/Google.Cloud.Docs.Snippets/OccSnippets.cs

@@ -0,0 +1,89 @@
+// Copyright 2025 Google Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using Google.Cloud.Iam.V1;
+using Google.Cloud.PubSub.V1;
+using Grpc.Core;
+using System.Linq;
+using Xunit;
+
+namespace Google.Cloud.Tools.Snippets;
+
+[Collection(nameof(SnippetFixture))]
+public class OccSnippets
+{
+    private readonly SnippetFixture _fixture;
+
+    public OccSnippets(SnippetFixture fixture) => _fixture = fixture;
+
+    [Fact]
+    public void OccForIam()
+    {
+        string role = "roles/pubsub.viewer";
+        string member = "domain:google.com";
+
+        var topicName = _fixture.CreateTopic();
+
+        // Sample: OccForIam
+        PublisherServiceApiClient client = PublisherServiceApiClient.Create();
+
+        try
+        {
+            // Get the current IAM Policy with the current Etag.
+            Policy policy = client.IAMPolicyClient.GetIamPolicy(new GetIamPolicyRequest
+            {
+                Resource = topicName,
+            });
+
+            // Modify the local IAM Policy object.
+            Binding binding = policy.Bindings.FirstOrDefault(b => b.Role == role);
+
+            if (binding != null)
+            {
+                if (!binding.Members.Contains(member))
+                {
+                    binding.Members.Add(member);
+                }
+            }
+            else
+            {
+                policy.Bindings.Add(new Binding
+                {
+                    Role = role,
+                    Members = { member }
+                });
+            }
+
+            // Attempt to set the modified policy, it contains the Etag value from when it was read.
+            client.IAMPolicyClient.SetIamPolicy(new SetIamPolicyRequest
+            {
+                Resource = topicName,
+                Policy = policy
+            });
+
+            // The policy was modified successfully.
+        }
+        catch (RpcException ex) when ( ex.StatusCode == StatusCode.Aborted )
+        {
+            // A concurrency conflict usually manifests as Aborted but depending on the API
+            // other error codes may be used, like FailedPrecondition.
+            // To ensure the OCC mechanism is robust, check the documentation for the API
+            // you are implementing OCC for.
+
+            // Handle the etag mismatch. For example, retry the change or prompt the user to
+            // submit their changes again.
+        }
+        // End sample
+    }
+}

tools/Google.Cloud.Docs.Snippets/SnippetFixture.cs

@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2018 Google LLC
 // 
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -12,10 +12,12 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+using Google.Api.Gax.Grpc;
 using Google.Api.Gax.ResourceNames;
 using Google.Cloud.ClientTesting;
 using Google.Cloud.PubSub.V1;
 using System.Linq;
+using System.Threading.Tasks;
 using Xunit;
 
 namespace Google.Cloud.Tools.Snippets
@@ -45,6 +47,14 @@ public SnippetFixture()
         /// </summary>
         internal string CreateSubscriptionId() => IdGenerator.FromGuid(prefix: SubscriptionPrefix);
 
+        internal string CreateTopic()
+        {
+            PublisherServiceApiClient client = PublisherServiceApiClient.Create();
+            TopicName topicName = new TopicName(ProjectId, CreateTopicId());
+            Topic topic = client.CreateTopic(topicName);
+            return topic.Name;
+        }
+
         public override void Dispose()
         {
             var subscriber = SubscriberServiceApiClient.Create();

tools/Google.Cloud.Docs.Snippets/UpdateMaskSnippets.cs

@@ -0,0 +1,56 @@
+// Copyright 2025 Google Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using Google.Cloud.PubSub.V1;
+using Google.Protobuf.WellKnownTypes;
+using Xunit;
+
+namespace Google.Cloud.Tools.Snippets;
+
+[Collection(nameof(SnippetFixture))]
+public class UpdateMaskSnippets
+{
+    private readonly SnippetFixture _fixture;
+
+    public UpdateMaskSnippets(SnippetFixture fixture) => _fixture = fixture;
+
+    [Fact]
+    public void UpdateMasks()
+    {
+        var topicName = _fixture.CreateTopic();
+
+        // Sample: UpdateMasks
+        PublisherServiceApiClient client = PublisherServiceApiClient.Create();
+
+        // Create a resource with the values you want to update
+        Topic topic = new Topic
+        {
+            // Set the full resource name
+            Name = topicName,
+            // Populate the fields we intend to change
+            Labels = { { "env", "production" } }
+        };
+
+        // Create the FieldMask
+        FieldMask updateMask = new FieldMask
+        {
+            // Add the original protobuf field name.
+            // In this example, the C# property is 'Labels', but the protobuf field name is 'labels'.
+            Paths = { "labels" }
+        };
+
+        client.UpdateTopic(topic, updateMask);
+        // End sample
+    }
+}