Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(spanner): some documentation tweaks #11641

Merged
merged 2 commits into from
May 17, 2023
Merged

docs(spanner): some documentation tweaks #11641

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0035da2
docs(spanner): some documentation tweaks
coryan May 17, 2023
0b169ca
Address review comments
coryan May 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 18 additions & 14 deletions google/cloud/spanner/doc/spanner-main.dox
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
@mainpage Cloud Spanner C++ Client Library

The Cloud Spanner C++ Client library offers types and functions to use Cloud
Spanner from C++11 applications.
Spanner from C++ applications.

@tableofcontents{HTML:2}

Expand All @@ -22,12 +22,12 @@ into your project.
to execute SQL queries in Cloud Spanner.
- [Client::Commit()](@ref google::cloud::spanner::Client::Commit())
to execute read-write transactions in Cloud Spanner.
- [Client::Read()](@ref google::cloud::spanner::Client::Read()) - to read the
- [Client::Read()](@ref google::cloud::spanner::Client::Read()) to read the
rows in a table.
- @ref spanner-error-handling to learn how the library reports run-time errors.
- @ref spanner-env-logging enable logging. THis can be an effective approach to
diagnose many problems.
- @ref spanner-env for environment variables affecting the library.
- @ref spanner-env for environment variables affecting the library. Some of
these environment variables enable logging to the console. This can be an
effective approach to diagnose runtime problems.
- @ref spanner-endpoint-example
- @ref spanner-auth-example
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This leads to a page where two links are not separated by any space.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. I used the same structure as the generated documents, if you want we can make it nicer as this is a hand-crafted library.

- @ref spanner-retry-example
Expand All @@ -52,9 +52,11 @@ endpoint for `google::cloud::spanner::Client`:

@snippet client_samples.cc set-client-endpoint

Follow these links for additional examples
[DatabaseAdminClient](@ref DatabaseAdminClient-set-endpoint-snippet)
[InstanceAdminClient](@ref InstanceAdminClient-set-endpoint-snippet)
Follow these links to find examples for other `*Client` classes:

- [`DatabaseAdminClient`](@ref DatabaseAdminClient-set-endpoint-snippet)
- [`InstanceAdminClient`](@ref InstanceAdminClient-set-endpoint-snippet)

*/

/**
Expand All @@ -71,9 +73,11 @@ Keep in mind that we chose this as an example because it is relatively easy to
understand. Consult the [Best practices for managing service account keys]
guide for more details.

Follow these links for additional examples
[DatabaseAdminClient](@ref DatabaseAdminClient-with-service-account-snippet)
[InstanceAdminClient](@ref InstanceAdminClient-with-service-account-snippet)
Follow these links to find examples for other `*Client` classes:

- [`DatabaseAdminClient`](@ref DatabaseAdminClient-with-service-account-snippet)
- [`InstanceAdminClient`](@ref InstanceAdminClient-with-service-account-snippet)

*/

/**
Expand All @@ -91,11 +95,11 @@ period between retries.

@snippet samples.cc custom-retry-policy

@see [LimitedTimeRetryPolicy](@ref google::cloud::spanner::LimitedTimeRetryPolicy)
and [LimitedErrorCountRetryPolicy](@ref google::cloud::spanner::LimitedErrorCountRetryPolicy)
@see [`LimitedTimeRetryPolicy`](@ref google::cloud::spanner::LimitedTimeRetryPolicy)
and [`LimitedErrorCountRetryPolicy`](@ref google::cloud::spanner::LimitedErrorCountRetryPolicy)
for alternative retry policies.

@see [ExponentialBackoffPolicy](@ref google::cloud::spanner::ExponentialBackoffPolicy)
@see [`ExponentialBackoffPolicy`](@ref google::cloud::spanner::ExponentialBackoffPolicy)
to configure different parameters for the exponential backoff policy.
*/

Expand Down