feat: product neutral guides

cmake/GoogleCloudCppDoxygen.cmake

@@ -32,7 +32,7 @@ function (google_cloud_cpp_doxygen_targets_impl library)
         return()
     endif ()
 
-    cmake_parse_arguments(opt "RECURSIVE;THREADED" "" "INPUTS;TAGFILES;DEPENDS"
+    cmake_parse_arguments(opt "RECURSIVE;THREADED" "" "INPUTS;TAGFILES;DEPENDS;FILE_PATTERNS"
                           ${ARGN})
 
     # Options controlling the inputs into Doxygen
@@ -59,7 +59,11 @@ function (google_cloud_cpp_doxygen_targets_impl library)
                 " using DOXYGEN_NUM_PROC_THREADS=${DOXYGEN_NUM_PROC_THREADS}")
     endif ()
 
-    set(DOXYGEN_FILE_PATTERNS "*.dox" "*.h")
+    if (_opt_FILE_PATTERNS)
+        set(DOXYGEN_FILE_PATTERNS ${_opt_FILE_PATTERNS})
+    else()
+        set(DOXYGEN_FILE_PATTERNS "*.dox" "*.h")
+    endif()
     set(DOXYGEN_EXCLUDE_PATTERNS
         # We should skip internal directories to speed up the build. We do not
         # use "*/internal/*" because Doxygen breaks when we include

doc/product-neutral-guides/client-configuration.md

@@ -0,0 +1,64 @@
+# Google Cloud Platform C++ Client Libraries: Client Configuration
+
+The Google Cloud C++ Client Libraries allow you to configure client behavior via the `google::cloud::Options` class passed to the client constructor or the connection factory functions.
+
+## 1. Common Configuration Options
+
+The `google::cloud::Options` class is a type-safe map where you set specific option structs.
+
+| Option Struct | Description |
+| ----- | ----- |
+| `google::cloud::EndpointOption` | The address of the API remote host. Used for Regional Endpoints. |
+| `google::cloud::UserProjectOption` | Quota project to use for the request. |
+| `google::cloud::AuthorityOption` | Sets the `:authority` pseudo-header (useful for testing/emulators). |
+| `google::cloud::UnifiedCredentialsOption` | Explicit credentials object (overrides default discovery). |
+| `google::cloud::TracingComponentsOption` | Controls client-side logging/tracing. |
+
+## 2. Customizing the API Endpoint
+
+You can modify the API endpoint to connect to a specific Google Cloud region or to a private endpoint.
+
+### Connecting to a Regional Endpoint
+
+[!code-cpp[](../../google/cloud/pubsub/samples/client_samples.cc#publisher-set-endpoint)]
+
+## 3. Configuring a Proxy
+
+### Proxy with gRPC
+
+The C++ gRPC layer respects standard environment variables. You generally do not configure this in C++ code.
+
+Set the following environment variables in your shell or Docker container:
+
+```
+export http_proxy="http://proxy.example.com:3128"
+export https_proxy="http://proxy.example.com:3128"
+```
+
+**Handling Self-Signed Certificates:** If your proxy uses a self-signed certificate, use the standard gRPC environment variable:
+
+```
+export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="/path/to/roots.pem"
+```
+
+### Proxy with REST
+
+If using a library that supports REST (like `google-cloud-storage`), it primarily relies on `libcurl`, which also respects the standard `http_proxy` and `https_proxy` environment variables.
+
+## 4. Configuring Retries and Timeouts
+
+In C++, retry policies are configured via `Options` or passed specifically to the connection factory.
+
+### Configuring Retry Policies
+
+You can set the `RetryPolicyOption` and `BackoffPolicyOption`.
+
+[!code-cpp[](../../google/cloud/secretmanager/v1/samples/secret_manager_client_samples.cc#set-retry-policy)]
+
+### Configuring Timeouts
+
+There isn't a single "timeout" integer. Instead, you can configure the **Idempotency Policy** (to determine which RPCs are safe to retry) or use `google::cloud::Options` to set specific RPC timeouts if the library exposes a specific option, though usually, the `RetryPolicy` (Total Timeout) governs the duration of the call.
+
+For per-call context (like deadlines), you can sometimes use `grpc::ClientContext` if dropping down to the raw stub level, but idiomatic Google Cloud C++ usage prefers the Policy approach.
+
+

doc/product-neutral-guides/core-concepts.md

@@ -0,0 +1,186 @@
+# Google Cloud Platform C++ Client Libraries: Core Concepts
+
+This documentation covers essential patterns and usage for the Google Cloud C++ Client Library, focusing on performance, data handling (`StatusOr`), and flow control (Pagination, Futures, Streaming).
+
+## 1. Installation & Setup
+
+The C++ libraries are typically installed via **vcpkg** or **Conda**, or compiled from source using **CMake**.
+
+**Example using vcpkg:**
+
+```
+vcpkg install google-cloud-cpp
+```
+
+**CMakeLists.txt:**
+
+```c
+find_package(google_cloud_cpp_pubsub REQUIRED)
+add_executable(my_app main.cc)
+target_link_libraries(my_app google-cloud-cpp::pubsub)
+```
+
+## 2. StatusOr\<T\> and Error Handling
+
+C++ does not use exceptions for API errors by default. Instead, it uses `google::cloud::StatusOr<T>`.
+
+* **Success:** The object contains the requested value.  
+* **Failure:** The object contains a `Status` (error code and message).
+
+```c
+void HandleResponse(google::cloud::StatusOr<std::string> response) {
+  if (!response) {
+    // Handle error
+    std::cerr << "RPC failed: " << response.status().message() << "\n";
+    return;
+  }
+  // Access value
+  std::cout << "Success: " << *response << "\n";
+}
+```
+
+## 3. Pagination (StreamRange)
+
+List methods in C++ return a `google::cloud::StreamRange<T>`. This works like a standard C++ input iterator. The library automatically fetches new pages in the background as you iterate.
+
+```c
+#include "google/cloud/secretmanager/secret_manager_client.h"
+
+void ListSecrets(google::cloud::secretmanager::SecretManagerServiceClient client) {
+  // Call the API
+  // Returns StreamRange<google::cloud::secretmanager::v1::Secret>
+  auto range = client.ListSecrets("projects/my-project");
+
+  for (auto const& secret : range) {
+    if (!secret) {
+      // StreamRange returns StatusOr<T> on dereference to handle failures mid-stream
+      std::cerr << "Error listing secret: " << secret.status() << "\n";
+      break;
+    }
+    std::cout << "Secret: " << secret->name() << "\n";
+  }
+}
+```
+
+## 4. Long Running Operations (LROs)
+
+LROs in C++ return a `std::future<StatusOr<T>>`.
+
+### Blocking Wait
+
+```c
+#include "google/cloud/compute/instances_client.h"
+
+void CreateInstance(google::cloud::compute::InstancesClient client) {
+  google::cloud::compute::v1::InsertInstanceRequest request;
+  // ... set request fields ...
+
+  // Start the operation
+  // Returns future<StatusOr<Operation>>
+  auto future = client.InsertInstance(request);
+
+  // Block until complete
+  auto result = future.get();
+
+  if (!result) {
+    std::cerr << "Creation failed: " << result.status() << "\n";
+  } else {
+    std::cout << "Instance created successfully\n";
+  }
+}
+```
+
+### Async / Non-Blocking
+
+You can use standard C++ `future` capabilities, such as polling `wait_for` or attaching continuations (via `.then` if using the library's future extension, though standard `std::future` is strictly blocking/polling).
+
+## 5. Update Masks
+
+The C++ libraries use `google::protobuf::FieldMask`.
+
+```c
+#include "google/cloud/secretmanager/secret_manager_client.h"
+#include <google/protobuf/field_mask.pb.h>
+
+void UpdateSecret(google::cloud::secretmanager::SecretManagerServiceClient client) {
+  namespace secretmanager = ::google::cloud::secretmanager::v1;
+
+  secretmanager::Secret secret;
+  secret.set_name("projects/my-project/secrets/my-secret");
+  (*secret.mutable_labels())["env"] = "production";
+
+  google::protobuf::FieldMask update_mask;
+  update_mask.add_paths("labels");
+
+  secretmanager::UpdateSecretRequest request;
+  *request.mutable_secret() = secret;
+  *request.mutable_update_mask() = update_mask;
+
+  auto result = client.UpdateSecret(request);
+}
+```
+
+## 6. gRPC Streaming
+
+### Server-Side Streaming
+
+Similar to pagination, Server-Side streaming usually returns a `StreamRange` or a specialized reader object.
+
+```c
+#include "google/cloud/bigquery/storage/bigquery_read_client.h"
+
+void ReadRows(google::cloud::bigquery_storage::BigQueryReadClient client) {
+  google::cloud::bigquery::storage::v1::ReadRowsRequest request;
+  request.set_read_stream("projects/.../streams/...");
+
+  // Returns a StreamRange of ReadRowsResponse
+  auto stream = client.ReadRows(request);
+
+  for (auto const& response : stream) {
+    if (!response) {
+      std::cerr << "Error reading row: " << response.status() << "\n";
+      break;
+    }
+    // Process response->avro_rows()
+  }
+}
+```
+
+### Bidirectional Streaming
+
+Bidirectional streaming uses a `AsyncReaderWriter` pattern (or synchronous `ReaderWriter`).
+
+```c
+#include "google/cloud/speech/speech_client.h"
+
+void StreamingRecognize(google::cloud::speech::SpeechClient client) {
+  // Start the stream
+  auto stream = client.StreamingRecognize();
+
+  // 1. Send Config
+  google::cloud::speech::v1::StreamingRecognizeRequest config_request;
+  // ... configure ...
+  stream->Write(config_request);
+
+  // 2. Send Audio
+  google::cloud::speech::v1::StreamingRecognizeRequest audio_request;
+  // ... load audio data ...
+  stream->Write(audio_request);
+
+  // 3. Close writing to signal we are done sending
+  stream->WritesDone();
+
+  // 4. Read responses
+  google::cloud::speech::v1::StreamingRecognizeResponse response;
+  while (stream->Read(&response)) {
+    for (const auto& result : response.results()) {
+       std::cout << "Transcript: " << result.alternatives(0).transcript() << "\n";
+    }
+  }
+
+  // Check final status
+  auto status = stream->Finish();
+}
+```
+
+

doc/product-neutral-guides/occ.md

@@ -0,0 +1,115 @@
+# Google Cloud Platform C++ Client Libraries: 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.
+
+In Google Cloud C++ libraries, IAM Policy objects contain an `etag` field. When calling `SetIamPolicy`, the client library serializes this `etag`. If the server detects that the `etag` provided does not match the current version on the server, it returns a `kAborted` (or sometimes `kFailedPrecondition`) status.
+
+## Implementing the OCC Loop in C++
+
+The core of the implementation is a `while` loop that checks the `Status` returned by the API call.
+
+### Steps of the Loop
+
+| Step | Action | C++ Implementation |
+| ----- | ----- | ----- |
+| **1\. Read** | Fetch the current IAM Policy. | `client.GetIamPolicy(name)` |
+| **2\. Modify** | Apply changes to the `google::iam::v1::Policy` object. | Modify repeated fields (bindings). |
+| **3\. Write** | Attempt to set the policy. | `client.SetIamPolicy(name, policy)` |
+| **4\. Retry** | Check `Status.code()`. | `if (status.code() == StatusCode::kAborted) continue;` |
+
+## C++ Code Example
+
+The following example demonstrates how to implement the OCC loop using the `google-cloud-cpp` Resource Manager library.
+
+```c
+#include "google/cloud/resourcemanager/v3/projects_client.h"
+#include "google/cloud/common_options.h"
+#include "google/cloud/project.h"
+#include <iostream>
+#include <thread>
+
+namespace resourcemanager = ::google::cloud::resourcemanager::v3;
+namespace iam = ::google::iam::v1;
+
+/**
+ * Executes an Optimistic Concurrency Control (OCC) loop to safely update an IAM policy.
+ *
+ * @param project_id The Google Cloud Project ID.
+ * @param role The IAM role to grant.
+ * @param member The member to add.
+ * @return StatusOr<Policy> The updated policy or the final error.
+ */
+google::cloud::StatusOr<iam::Policy> UpdateIamPolicyWithOCC(
+    std::string const& project_id,
+    std::string const& role,
+    std::string const& member) {
+
+  auto client = resourcemanager::ProjectsClient(
+      resourcemanager::MakeProjectsConnection());
+
+  std::string const resource_name = "projects/" + project_id;
+  int max_retries = 5;
+  int retries = 0;
+
+  // --- START OCC LOOP ---
+  while (retries < max_retries) {
+    // 1. READ: Get the current policy (includes etag)
+    auto policy = client.GetIamPolicy(resource_name);
+    if (!policy) {
+      return policy; // Return error immediately if Read fails (e.g. Permission Denied)
+    }
+
+    // 2. MODIFY: Apply changes to the local Policy object
+    // Note: Protobuf manipulation in C++ is explicit
+    bool role_found = false;
+    for (auto& binding : *policy->mutable_bindings()) {
+      if (binding.role() == role) {
+        binding.add_members(member);
+        role_found = true;
+        break;
+      }
+    }
+    if (!role_found) {
+      auto& new_binding = *policy->add_bindings();
+      new_binding.set_role(role);
+      new_binding.add_members(member);
+    }
+
+    // 3. WRITE: Attempt to set the modified policy
+    // The 'policy' object contains the original 'etag' from Step 1.
+    auto updated_policy = client.SetIamPolicy(resource_name, *policy);
+
+    // 4. CHECK STATUS
+    if (updated_policy) {
+      std::cout << "Successfully updated IAM policy.\n";
+      return updated_policy;
+    }
+
+    // 5. RETRY LOGIC
+    auto status = updated_policy.status();
+    if (status.code() == google::cloud::StatusCode::kAborted ||
+        status.code() == google::cloud::StatusCode::kFailedPrecondition) {
+
+      retries++;
+      std::cout << "Concurrency conflict (etag mismatch). Retrying... (" 
+                << retries << "/" << max_retries << ")\n";
+
+      // Simple exponential backoff
+      std::this_thread::sleep_for(std::chrono::milliseconds(100 * retries));
+      continue; // Restart loop
+    }
+
+    // If it was a different error (e.g., PermissionDenied), return it.
+    return updated_policy;
+  }
+  // --- END OCC LOOP ---
+
+  return google::cloud::Status(
+      google::cloud::StatusCode::kAborted,
+      "Failed to update IAM policy after max retries due to contention.");
+}
+```
+
+