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,107 @@
+# 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
+
+```c
+#include "google/cloud/pubsub/publisher_connection.h"
+#include "google/cloud/pubsub/publisher.h"
+#include "google/cloud/common_options.h"
+
+void CreateRegionalClient() {
+  namespace pubsub = ::google::cloud::pubsub;
+  namespace gc = ::google::cloud;
+
+  // Configure options
+  auto options = gc::Options{}
+      .set<gc::EndpointOption>("us-east1-pubsub.googleapis.com");
+
+  // Create the connection with options
+  auto connection = pubsub::MakePublisherConnection(options);
+
+  // Create the client
+  auto client = pubsub::Publisher(connection);
+}
+```
+
+## 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`.
+
+```c
+#include "google/cloud/secretmanager/secret_manager_client.h"
+#include "google/cloud/options.h"
+#include <chrono>
+
+void ConfigureRetries() {
+  namespace secretmanager = ::google::cloud::secretmanager;
+  using namespace std::chrono_literals;
+
+  // Define a limited retry policy (e.g., max 3 retries or 10 minutes)
+  auto retry_policy = secretmanager::SecretManagerServiceLimitedTimeRetryPolicy(10min);
+
+  // Define backoff (exponential: starts at 1s, max 30s, scaling 2.0)
+  auto backoff_policy = google::cloud::ExponentialBackoffPolicy(1s, 30s, 2.0);
+
+  auto options = google::cloud::Options{}
+      .set<secretmanager::SecretManagerServiceRetryPolicyOption>(
+          retry_policy.clone())
+      .set<secretmanager::SecretManagerServiceBackoffPolicyOption>(
+          backoff_policy.clone());
+
+  auto connection = secretmanager::MakeSecretManagerServiceConnection(options);
+  auto client = secretmanager::SecretManagerServiceClient(connection);
+}
+```
+
+### 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();
+}
+```
+
+