doc: add endpoint override snippets to generated libs

ci/generate-markdown/update-library-landing-dox.sh

@@ -27,8 +27,9 @@ fi
 cd "${PROJECT_ROOT}"
 readonly LIBRARY=$1
 
-lib="google/cloud/${LIBRARY}"
-if [[ ! -r "${lib}/doc/main.dox" ]]; then
+readonly LIB="google/cloud/${LIBRARY}"
+readonly MAIN_DOX="google/cloud/${LIBRARY}/doc/main.dox"
+if [[ ! -r "${MAIN_DOX}" ]]; then
   exit 0
 fi
 
@@ -37,7 +38,7 @@ inject_end="<!-- inject-endpoint-env-vars-end -->"
 env_vars=("")
 while IFS= read -r -d $'\0' option_defaults_cc; do
   service="$(basename "${option_defaults_cc}" _option_defaults.cc)"
-  connection_h="${lib}/${service}_connection.h"
+  connection_h="${LIB}/${service}_connection.h"
   # Should we generate documentation for GOOGLE_CLOUD_CPP_.*_AUTHORITY too?
   variable_re='GOOGLE_CLOUD_CPP_.*_ENDPOINT'
   variable=$(grep -om1 "${variable_re}" "${option_defaults_cc}")
@@ -52,10 +53,43 @@ while IFS= read -r -d $'\0' option_defaults_cc; do
   env_vars+=("  \`EndpointOption\` (which defaults to ${endpoint})")
   env_vars+=("  used by \`${make_connection}()\`.")
   env_vars+=("")
-done < <(git ls-files -z -- "${lib}/internal/*_option_defaults.cc")
-sed -i -f - "${lib}/doc/main.dox" <<EOT
+done < <(git ls-files -z -- "${LIB}/internal/*_option_defaults.cc")
+
+sed -i -f - "${MAIN_DOX}" <<EOT
 /${inject_start}/,/${inject_end}/c \\
 ${inject_start}\\
 $(printf '%s\\\n' "${env_vars[@]}")
 ${inject_end}
 EOT
+
+IFS= mapfile -d $'\0' -t samples_cc < <(git ls-files -z -- "${LIB}/samples/*_client_samples.cc")
+
+(
+  sed '/<!-- inject-endpoint-snippet-start -->/q' "${MAIN_DOX}"
+  if [[ ${#samples_cc[@]} -gt 0 ]]; then
+    sample_cc="${samples_cc[0]}"
+    client_name="$(sed -n '/main-dox-marker: / s;// main-dox-marker: \(.*\);\1;p' "${sample_cc}")"
+    echo 'For example, this will override the default endpoint for `'"${client_name}"'`:'
+    echo
+    echo "@snippet $(basename "${sample_cc}") set-client-endpoint"
+    if [[ ${#samples_cc[@]} -gt 1 ]]; then
+      echo
+      echo "Follow these links to find examples for other \\c *Client classes:"
+      for sample_cc in "${samples_cc[@]}"; do
+        sed -n "/main-dox-marker: / s;// main-dox-marker: \(.*\); [\1](@ref \1-endpoint-snippet);p" "${sample_cc}"
+      done
+    fi
+  fi
+  echo
+  sed -n '/<!-- inject-endpoint-snippet-end -->/,$p' "${MAIN_DOX}"
+) | sponge "${MAIN_DOX}"
+
+(
+  sed '/<!-- inject-endpoint-pages-start -->/q' "${MAIN_DOX}"
+  for sample_cc in "${samples_cc[@]}"; do
+    client_name=$(sed -n "/main-dox-marker: / s;// main-dox-marker: \(.*\);\1;p" "${sample_cc}")
+    printf '\n/*! @page %s-endpoint-snippet Override %s Endpoint Configuration\n\n@snippet %s set-client-endpoint\n\n*/\n' \
+      "${client_name}" "${client_name}" "${sample_cc}"
+  done
+  sed -n '/<!-- inject-endpoint-pages-end -->/,$p' "${MAIN_DOX}"
+) | sponge "${MAIN_DOX}"

google/cloud/accessapproval/doc/main.dox

@@ -94,6 +94,10 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `AccessApprovalClient`:
+
+@snippet access_approval_client_samples.cc set-client-endpoint
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -117,4 +121,10 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page AccessApprovalClient-endpoint-snippet Override AccessApprovalClient Endpoint Configuration
+
+@snippet google/cloud/accessapproval/samples/access_approval_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->

google/cloud/accesscontextmanager/doc/main.dox

@@ -93,6 +93,10 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `AccessContextManagerClient`:
+
+@snippet access_context_manager_client_samples.cc set-client-endpoint
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -111,4 +115,10 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page AccessContextManagerClient-endpoint-snippet Override AccessContextManagerClient Endpoint Configuration
+
+@snippet google/cloud/accesscontextmanager/samples/access_context_manager_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->

google/cloud/apigateway/doc/main.dox

@@ -92,6 +92,10 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `ApiGatewayServiceClient`:
+
+@snippet api_gateway_client_samples.cc set-client-endpoint
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -110,4 +114,10 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page ApiGatewayServiceClient-endpoint-snippet Override ApiGatewayServiceClient Endpoint Configuration
+
+@snippet google/cloud/apigateway/samples/api_gateway_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->

google/cloud/apigeeconnect/doc/main.dox

@@ -96,6 +96,10 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `ConnectionServiceClient`:
+
+@snippet connection_client_samples.cc set-client-endpoint
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -114,4 +118,10 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page ConnectionServiceClient-endpoint-snippet Override ConnectionServiceClient Endpoint Configuration
+
+@snippet google/cloud/apigeeconnect/samples/connection_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->

google/cloud/apikeys/doc/main.dox

@@ -92,6 +92,10 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `ApiKeysClient`:
+
+@snippet api_keys_client_samples.cc set-client-endpoint
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -110,4 +114,10 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page ApiKeysClient-endpoint-snippet Override ApiKeysClient Endpoint Configuration
+
+@snippet google/cloud/apikeys/samples/api_keys_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->

google/cloud/appengine/doc/main.dox

@@ -120,6 +120,20 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `ApplicationsClient`:
+
+@snippet applications_client_samples.cc set-client-endpoint
+
+Follow these links to find examples for other \c *Client classes:
+ [ApplicationsClient](@ref ApplicationsClient-endpoint-snippet)
+ [AuthorizedCertificatesClient](@ref AuthorizedCertificatesClient-endpoint-snippet)
+ [AuthorizedDomainsClient](@ref AuthorizedDomainsClient-endpoint-snippet)
+ [DomainMappingsClient](@ref DomainMappingsClient-endpoint-snippet)
+ [FirewallClient](@ref FirewallClient-endpoint-snippet)
+ [InstancesClient](@ref InstancesClient-endpoint-snippet)
+ [ServicesClient](@ref ServicesClient-endpoint-snippet)
+ [VersionsClient](@ref VersionsClient-endpoint-snippet)
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -138,4 +152,52 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page ApplicationsClient-endpoint-snippet Override ApplicationsClient Endpoint Configuration
+
+@snippet google/cloud/appengine/samples/applications_client_samples.cc set-client-endpoint
+
+*/
+
+/*! @page AuthorizedCertificatesClient-endpoint-snippet Override AuthorizedCertificatesClient Endpoint Configuration
+
+@snippet google/cloud/appengine/samples/authorized_certificates_client_samples.cc set-client-endpoint
+
+*/
+
+/*! @page AuthorizedDomainsClient-endpoint-snippet Override AuthorizedDomainsClient Endpoint Configuration
+
+@snippet google/cloud/appengine/samples/authorized_domains_client_samples.cc set-client-endpoint
+
+*/
+
+/*! @page DomainMappingsClient-endpoint-snippet Override DomainMappingsClient Endpoint Configuration
+
+@snippet google/cloud/appengine/samples/domain_mappings_client_samples.cc set-client-endpoint
+
+*/
+
+/*! @page FirewallClient-endpoint-snippet Override FirewallClient Endpoint Configuration
+
+@snippet google/cloud/appengine/samples/firewall_client_samples.cc set-client-endpoint
+
+*/
+
+/*! @page InstancesClient-endpoint-snippet Override InstancesClient Endpoint Configuration
+
+@snippet google/cloud/appengine/samples/instances_client_samples.cc set-client-endpoint
+
+*/
+
+/*! @page ServicesClient-endpoint-snippet Override ServicesClient Endpoint Configuration
+
+@snippet google/cloud/appengine/samples/services_client_samples.cc set-client-endpoint
+
+*/
+
+/*! @page VersionsClient-endpoint-snippet Override VersionsClient Endpoint Configuration
+
+@snippet google/cloud/appengine/samples/versions_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->

google/cloud/artifactregistry/doc/main.dox

@@ -93,6 +93,10 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `ArtifactRegistryClient`:
+
+@snippet artifact_registry_client_samples.cc set-client-endpoint
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -111,4 +115,10 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page ArtifactRegistryClient-endpoint-snippet Override ArtifactRegistryClient Endpoint Configuration
+
+@snippet google/cloud/artifactregistry/samples/artifact_registry_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->

google/cloud/asset/doc/main.dox

@@ -93,6 +93,10 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `AssetServiceClient`:
+
+@snippet asset_client_samples.cc set-client-endpoint
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -111,4 +115,10 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page AssetServiceClient-endpoint-snippet Override AssetServiceClient Endpoint Configuration
+
+@snippet google/cloud/asset/samples/asset_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->

google/cloud/assuredworkloads/doc/main.dox

@@ -95,6 +95,10 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `AssuredWorkloadsServiceClient`:
+
+@snippet assured_workloads_client_samples.cc set-client-endpoint
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -112,4 +116,10 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page AssuredWorkloadsServiceClient-endpoint-snippet Override AssuredWorkloadsServiceClient Endpoint Configuration
+
+@snippet google/cloud/assuredworkloads/samples/assured_workloads_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->

google/cloud/automl/doc/main.dox

@@ -97,6 +97,14 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `AutoMlClient`:
+
+@snippet auto_ml_client_samples.cc set-client-endpoint
+
+Follow these links to find examples for other \c *Client classes:
+ [AutoMlClient](@ref AutoMlClient-endpoint-snippet)
+ [PredictionServiceClient](@ref PredictionServiceClient-endpoint-snippet)
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -115,4 +123,16 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page AutoMlClient-endpoint-snippet Override AutoMlClient Endpoint Configuration
+
+@snippet google/cloud/automl/samples/auto_ml_client_samples.cc set-client-endpoint
+
+*/
+
+/*! @page PredictionServiceClient-endpoint-snippet Override PredictionServiceClient Endpoint Configuration
+
+@snippet google/cloud/automl/samples/prediction_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->

google/cloud/baremetalsolution/doc/main.dox

@@ -94,6 +94,10 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `BareMetalSolutionClient`:
+
+@snippet bare_metal_solution_client_samples.cc set-client-endpoint
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -112,4 +116,10 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page BareMetalSolutionClient-endpoint-snippet Override BareMetalSolutionClient Endpoint Configuration
+
+@snippet google/cloud/baremetalsolution/samples/bare_metal_solution_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->

google/cloud/batch/doc/main.dox

@@ -91,6 +91,10 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
 library to change this default.
 
 <!-- inject-endpoint-snippet-start -->
+For example, this will override the default endpoint for `BatchServiceClient`:
+
+@snippet batch_client_samples.cc set-client-endpoint
+
 <!-- inject-endpoint-snippet-end -->
 
 ## Retry, Backoff, and Idempotency Policies.
@@ -109,4 +113,10 @@ can override the default policies.
 */
 
 // <!-- inject-endpoint-pages-start -->
+
+/*! @page BatchServiceClient-endpoint-snippet Override BatchServiceClient Endpoint Configuration
+
+@snippet google/cloud/batch/samples/batch_client_samples.cc set-client-endpoint
+
+*/
 // <!-- inject-endpoint-pages-end -->