Skip to content

Commit d93c262

Browse files
scotthartscotthart
committed
add golden file dox templates
1 parent 287ddf4 commit d93c262

File tree

5 files changed

+179
-0
lines changed

5 files changed

+179
-0
lines changed

‎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 -->

0 commit comments

Comments
 (0)