Skip to content

Commit 1cbff5a

Browse files
scotthartscotthart
authored
impl(generator): regenerate most doc files (#15653)
1 parent 66b9132 commit 1cbff5a

File tree

281 files changed

+318
-301
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

281 files changed

+318
-301
lines changed

‎ci/cloudbuild/builds/generate-libraries.sh‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,9 @@ set -euo pipefail
1818

1919
source "$(dirname "$0")/../../lib/init.sh"
2020
source module ci/cloudbuild/builds/lib/bazel.sh
21+
source module ci/cloudbuild/builds/lib/features.sh
2122
source module ci/cloudbuild/builds/lib/git.sh
23+
source module ci/lib/io.sh
2224

2325
bazel_output_base="$(bazel info output_base)"
2426

@@ -115,6 +117,11 @@ else
115117
io::log_yellow "Skipping update of protobuf lists/deps."
116118
fi
117119

120+
io::log_h2 "Running doxygen landing-page updates:"
121+
time {
122+
features::libraries | xargs -P "$(nproc)" -n 1 ci/generate-markdown/update-library-landing-dox.sh
123+
}
124+
118125
io::log_h2 "Highlight generated code differences"
119126
# We use `--compact-summary` because in almost all cases the delta is at
120127
# least hundreds of lines long, and often it is thousands of lines long. The

‎generator/integration_tests/golden/doc/environment-variables.dox‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
/*!
2+
@page golden-env Environment Variables
3+
4+
A number of environment variables can be used to configure the behavior of
5+
the library. There are also functions to configure this behavior in code. The
6+
environment variables are convenient when troubleshooting problems.
7+
8+
@section golden-env-endpoint Endpoint Overrides
9+
10+
<!-- inject-endpoint-env-vars-start -->
11+
<!-- inject-endpoint-env-vars-end -->
12+
13+
@see google::cloud::EndpointOption
14+
15+
@section golden-env-logging Logging
16+
17+
`GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc`: turns on tracing for most gRPC
18+
calls. The library injects an additional Stub decorator that prints each gRPC
19+
request and response. Unless you have configured your own logging backend,
20+
you should also set `GOOGLE_CLOUD_CPP_ENABLE_CLOG` to produce any output on
21+
the program's console.
22+
23+
@see google::cloud::LoggingComponentsOption
24+
25+
`GOOGLE_CLOUD_CPP_TRACING_OPTIONS=...`: modifies the behavior of gRPC tracing,
26+
including whether messages will be output on multiple lines, or whether
27+
string/bytes fields will be truncated.
28+
29+
@see google::cloud::GrpcTracingOptionsOption
30+
31+
`GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes`: turns on logging in the library, basically
32+
the library always "logs" but the logging infrastructure has no backend to
33+
actually print anything until the application sets a backend or they set this
34+
environment variable.
35+
36+
@see google::cloud::LogBackend
37+
@see google::cloud::LogSink
38+
39+
@section golden-env-project Setting the Default Project
40+
41+
`GOOGLE_CLOUD_PROJECT=...`: is used in examples and integration tests to
42+
configure the GCP project. This has no effect in the library.
43+
44+
*/

‎generator/integration_tests/golden/doc/options.dox‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
/*!
2+
@defgroup generator-integration_tests-golden-options Test Deprecated Configuration Options
3+
4+
This library uses the same mechanism (`google::cloud::Options`) and the common
5+
[options](@ref options) as all other C++ client libraries for its configuration.
6+
Some `*Option` classes, which are only used in this library, are documented in
7+
this page.
8+
9+
@see @ref options - for an overview of client library configuration.
10+
*/

‎generator/integration_tests/golden/doc/override-authentication.dox‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
/*!
2+
@page golden-override-authentication How to Override the Authentication Credentials
3+
4+
Unless otherwise configured, the client libraries use
5+
[Application Default Credentials] to authenticate with Google Cloud Services.
6+
While this works for most applications, in some cases you may need to override
7+
this default. You can do so by providing the
8+
[UnifiedCredentialsOption](@ref google::cloud::UnifiedCredentialsOption)
9+
The following example shows how to explicitly load a service account key file:
10+
11+
<!-- inject-service-account-snippet-start -->
12+
<!-- inject-service-account-snippet-end -->
13+
14+
Keep in mind that we chose this as an example because it is relatively easy to
15+
understand. Consult the [Best practices for managing service account keys]
16+
guide for more details.
17+
18+
@see @ref guac - for more information on the factory functions to create
19+
`google::cloud::Credentials` objects.
20+
21+
[Best practices for managing service account keys]: https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys
22+
[Application Default Credentials]: https://cloud.google.com/docs/authentication#adc
23+
24+
*/
25+
26+
// <!-- inject-authentication-pages-start -->
27+
// <!-- inject-authentication-pages-end -->

‎generator/integration_tests/golden/doc/override-endpoint.dox‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
/*!
2+
@page golden-override-endpoint How to Override the Default Endpoint
3+
4+
In some cases, you may need to override the default endpoint used by the client
5+
library. Use the
6+
[EndpointOption](@ref google::cloud::EndpointOption) when initializing the
7+
client library to change this default.
8+
9+
<!-- inject-endpoint-snippet-start -->
10+
<!-- inject-endpoint-snippet-end -->
11+
12+
*/
13+
14+
// <!-- inject-endpoint-pages-start -->
15+
// <!-- inject-endpoint-pages-end -->

‎generator/integration_tests/golden/doc/override-retry-policies.dox‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
/*!
2+
@page golden-override-retry Override Retry, Backoff, and Idempotency Policies
3+
4+
When it is safe to do so, the library automatically retries requests that fail
5+
due to a transient error. The library then uses [exponential backoff] to backoff
6+
before trying again. Which operations are considered safe to retry, which
7+
errors are treated as transient failures, the details of the exponential backoff
8+
algorithm, and for how long the library retries are all configurable via
9+
policies.
10+
11+
This document provides examples showing how to override the default policies.
12+
13+
The policies can be set when the `*Connection` object is created. The library
14+
provides default policies for any policy that is not set. The application can
15+
also override some (or all) policies when the `*Client` object is created. This
16+
can be useful if multiple `*Client` objects share the same `*Connection` object,
17+
but you want different retry behavior in some of the clients. Finally, the
18+
application can override some retry policies when calling a specific member
19+
function.
20+
21+
The library uses three different options to control the retry loop. The options
22+
have per-client names.
23+
24+
@section golden-override-retry-retry-policy Configuring the transient errors and retry duration
25+
26+
The `*RetryPolicyOption` controls:
27+
28+
- Which errors are to be treated as transient errors.
29+
- How long the library will keep retrying transient errors.
30+
31+
You can provide your own class for this option. The library also provides two
32+
built-in policies:
33+
34+
- `*LimitedErrorCountRetryPolicy`: stops retrying after a specified number
35+
of transient errors.
36+
- `*LimitedTimeRetryPolicy`: stops retrying after a specified time.
37+
38+
Note that a library may have more than one version of these classes. Their name
39+
match the `*Client` and `*Connection` object they are intended to be used
40+
with. Some `*Client` objects treat different error codes as transient errors.
41+
In most cases, only [kUnavailable](@ref google::cloud::StatusCode) is treated
42+
as a transient error.
43+
44+
@section golden-override-retry-backoff-policy Controlling the backoff algorithm
45+
46+
The `*BackoffPolicyOption` controls how long the client library will wait
47+
before retrying a request that failed with a transient error. You can provide
48+
your own class for this option.
49+
50+
The only built-in backoff policy is
51+
[`ExponentialBackoffPolicy`](@ref google::cloud::ExponentialBackoffPolicy).
52+
This class implements a truncated exponential backoff algorithm, with jitter.
53+
In summary, it doubles the current backoff time after each failure. The actual
54+
backoff time for an RPC is chosen at random, but never exceeds the current
55+
backoff. The current backoff is doubled after each failure, but never exceeds
56+
(or is "truncated") if it reaches a prescribed maximum.
57+
58+
@section golden-override-retry-idempotency-policy Controlling which operations are retryable
59+
60+
The `*IdempotencyPolicyOption` controls which requests are retryable, as some
61+
requests are never safe to retry.
62+
63+
Only one built-in idempotency policy is provided by the library. The name
64+
matches the name of the client it is intended for. For example, `FooBarClient`
65+
will use `FooBarIdempotencyPolicy`. This policy is very conservative.
66+
67+
@section golden-override-retry-example Example
68+
69+
<!-- inject-retry-snippet-start -->
70+
<!-- inject-retry-snippet-end -->
71+
72+
@section golden-override-retry-more-information More Information
73+
74+
@see google::cloud::Options
75+
@see google::cloud::BackoffPolicy
76+
@see google::cloud::ExponentialBackoffPolicy
77+
78+
[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff
79+
80+
*/
81+
82+
// <!-- inject-retry-pages-start -->
83+
// <!-- inject-retry-pages-end -->

‎generator/integration_tests/test2.yaml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Copyright 2025 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
type: google.api.Service
16+
config_version: 3
17+
name: test.googleapis.com
18+
title: Test2
19+
20+
apis:
21+
- name: google.test.rest.only.v1.GoldenRestOnly

‎generator/integration_tests/test_deprecated.yaml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Copyright 2025 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
type: google.api.Service
16+
config_version: 3
17+
name: test.googleapis.com
18+
title: Test Deprecated
19+
20+
apis:
21+
- name: google.test.deprecated.v1.DeprecatedService

‎generator/internal/scaffold_generator.cc‎

Lines changed: 37 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -326,44 +326,59 @@ void GenerateMetadata(
326326
void GenerateScaffold(
327327
std::map<std::string, std::string> const& vars,
328328
std::string const& scaffold_templates_path, std::string const& output_path,
329-
google::cloud::cpp::generator::ServiceConfiguration const& service) {
329+
google::cloud::cpp::generator::ServiceConfiguration const& service,
330+
ScaffoldFiles scaffold_files) {
330331
using Generator = std::function<void(
331332
std::ostream&, std::map<std::string, std::string> const&)>;
332333
struct Destination {
333334
std::string name;
334335
Generator generator;
335-
} files[] = {
336-
{"README.md", GenerateReadme},
337-
{"BUILD.bazel", GenerateBuild},
338-
{"CMakeLists.txt", GenerateCMakeLists},
339-
{"doc/main.dox", GenerateDoxygenMainPage},
340-
{"doc/environment-variables.dox", GenerateDoxygenEnvironmentPage},
341-
{"doc/override-authentication.dox", GenerateOverrideAuthenticationPage},
342-
{"doc/override-endpoint.dox", GenerateOverrideEndpointPage},
343-
{"doc/override-retry-policies.dox", GenerateOverrideRetryPoliciesPage},
344-
{"doc/options.dox", GenerateDoxygenOptionsPage},
345-
{"quickstart/README.md", GenerateQuickstartReadme},
346-
{"quickstart/quickstart.cc", GenerateQuickstartSkeleton},
347-
{"quickstart/CMakeLists.txt", GenerateQuickstartCMake},
348-
{"quickstart/Makefile", GenerateQuickstartMakefile},
349-
{"quickstart/BUILD.bazel", GenerateQuickstartBuild},
350-
{"quickstart/.bazelrc", GenerateQuickstartBazelrc},
351336
};
352337

353338
MakeDirectory(output_path + "/");
354339
auto const destination =
355340
output_path + "/" + LibraryPath(service.product_path());
356341
MakeDirectory(destination);
357342
MakeDirectory(destination + "doc/");
358-
MakeDirectory(destination + "quickstart/");
343+
344+
std::vector<Destination> files;
345+
if (scaffold_files == ScaffoldFiles::kDocDir) {
346+
files = {
347+
{"doc/environment-variables.dox", GenerateDoxygenEnvironmentPage},
348+
{"doc/override-authentication.dox", GenerateOverrideAuthenticationPage},
349+
{"doc/override-endpoint.dox", GenerateOverrideEndpointPage},
350+
{"doc/override-retry-policies.dox", GenerateOverrideRetryPoliciesPage},
351+
{"doc/options.dox", GenerateDoxygenOptionsPage},
352+
};
353+
} else {
354+
MakeDirectory(destination + "quickstart/");
355+
files = {
356+
{"README.md", GenerateReadme},
357+
{"BUILD.bazel", GenerateBuild},
358+
{"CMakeLists.txt", GenerateCMakeLists},
359+
{"doc/main.dox", GenerateDoxygenMainPage},
360+
{"doc/environment-variables.dox", GenerateDoxygenEnvironmentPage},
361+
{"doc/override-authentication.dox", GenerateOverrideAuthenticationPage},
362+
{"doc/override-endpoint.dox", GenerateOverrideEndpointPage},
363+
{"doc/override-retry-policies.dox", GenerateOverrideRetryPoliciesPage},
364+
{"doc/options.dox", GenerateDoxygenOptionsPage},
365+
{"quickstart/README.md", GenerateQuickstartReadme},
366+
{"quickstart/quickstart.cc", GenerateQuickstartSkeleton},
367+
{"quickstart/CMakeLists.txt", GenerateQuickstartCMake},
368+
{"quickstart/Makefile", GenerateQuickstartMakefile},
369+
{"quickstart/BUILD.bazel", GenerateQuickstartBuild},
370+
{"quickstart/.bazelrc", GenerateQuickstartBazelrc},
371+
};
372+
std::ifstream is(scaffold_templates_path + kWorkspaceTemplate);
373+
auto const contents = std::string{std::istreambuf_iterator<char>(is), {}};
374+
std::ofstream os(destination + "quickstart/WORKSPACE.bazel");
375+
GenerateQuickstartWorkspace(os, vars, contents);
376+
}
377+
359378
for (auto const& f : files) {
360379
std::ofstream os(destination + f.name);
361380
f.generator(os, vars);
362381
}
363-
std::ifstream is(scaffold_templates_path + kWorkspaceTemplate);
364-
auto const contents = std::string{std::istreambuf_iterator<char>(is), {}};
365-
std::ofstream os(destination + "quickstart/WORKSPACE.bazel");
366-
GenerateQuickstartWorkspace(os, vars, contents);
367382
}
368383

369384
void GenerateReadme(std::ostream& os,
@@ -547,7 +562,6 @@ which should give you a taste of the $title$ C++ client library API.
547562
void GenerateDoxygenEnvironmentPage(
548563
std::ostream& os, std::map<std::string, std::string> const& variables) {
549564
auto constexpr kText = R"""(/*!
550-
551565
@page $library$-env Environment Variables
552566
553567
A number of environment variables can be used to configure the behavior of

‎generator/internal/scaffold_generator.h‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,11 +96,17 @@ void GenerateMetadata(
9696
google::cloud::cpp::generator::ServiceConfiguration const& service,
9797
bool allow_placeholders);
9898

99+
enum class ScaffoldFiles {
100+
kAll,
101+
kDocDir, // Does not include main.dox due to all the hand edits.
102+
};
103+
99104
/// Generates the build and documentation scaffold for @p service.
100105
void GenerateScaffold(
101106
std::map<std::string, std::string> const& vars,
102107
std::string const& scaffold_templates_path, std::string const& output_path,
103-
google::cloud::cpp::generator::ServiceConfiguration const& service);
108+
google::cloud::cpp::generator::ServiceConfiguration const& service,
109+
ScaffoldFiles = ScaffoldFiles::kAll);
104110

105111
///@{
106112
/// @name Generators for each scaffold file.

0 commit comments

Comments
 (0)