From c257db47df7b6fd76f3f266cd40b35e63a3749d2 Mon Sep 17 00:00:00 2001
From: Carlos O'Ryan <coryan@google.com>
Date: Sat, 28 Jan 2023 16:39:52 +0000
Subject: [PATCH 1/2] feat(generator): link references in service comments

---
 generator/internal/format_class_comments.cc   | 52 +++++++++++-------
 .../internal/format_class_comments_test.cc    | 54 +++++++++++++++++++
 2 files changed, 88 insertions(+), 18 deletions(-)

diff --git a/generator/internal/format_class_comments.cc b/generator/internal/format_class_comments.cc
index 23d196aa5a9d2..cbc9086b74573 100644
--- a/generator/internal/format_class_comments.cc
+++ b/generator/internal/format_class_comments.cc
@@ -13,6 +13,7 @@
 // limitations under the License.
 
 #include "generator/internal/format_class_comments.h"
+#include "generator/internal/resolve_comment_references.h"
 #include "google/cloud/internal/absl_str_cat_quiet.h"
 #include "google/cloud/internal/absl_str_replace_quiet.h"
 #include "google/cloud/log.h"
@@ -21,24 +22,9 @@
 namespace google {
 namespace cloud {
 namespace generator_internal {
+namespace {
 
-std::string FormatClassCommentsFromServiceComments(
-    google::protobuf::ServiceDescriptor const& service) {
-  google::protobuf::SourceLocation service_source_location;
-  std::string formatted_comments;
-  if (!service.GetSourceLocation(&service_source_location) ||
-      service_source_location.leading_comments.empty()) {
-    GCP_LOG(INFO) << __FILE__ << ":" << __LINE__ << ": " << service.full_name()
-                  << " no leading_comments to format";
-    formatted_comments = absl::StrCat(" ", service.name(), "Client");
-  } else {
-    formatted_comments = absl::StrReplaceAll(
-        absl::StripSuffix(service_source_location.leading_comments, "\n"),
-        {{"\n\n", "\n///\n/// "}, {"\n", "\n/// "}});
-  }
-  std::string doxygen_formatted_comments =
-      absl::StrCat("///\n///", formatted_comments,
-                   R"""(
+auto constexpr kFixedClientComment = R"""(
 ///
 /// @par Equality
 ///
@@ -62,7 +48,37 @@ std::string FormatClassCommentsFromServiceComments(
 /// instance of this class is not guaranteed to work. Since copy-construction
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
-///)""");
+///)""";
+
+}  // namespace
+
+std::string FormatClassCommentsFromServiceComments(
+    google::protobuf::ServiceDescriptor const& service) {
+  google::protobuf::SourceLocation service_source_location;
+  std::string formatted_comments;
+  if (!service.GetSourceLocation(&service_source_location) ||
+      service_source_location.leading_comments.empty()) {
+    GCP_LOG(INFO) << __FILE__ << ":" << __LINE__ << ": " << service.full_name()
+                  << " no leading_comments to format";
+    formatted_comments = absl::StrCat(" ", service.name(), "Client");
+  } else {
+    formatted_comments = absl::StrReplaceAll(
+        absl::StripSuffix(service_source_location.leading_comments, "\n"),
+        {{"\n\n", "\n///\n/// "}, {"\n", "\n/// "}});
+  }
+
+  auto const references =
+      ResolveCommentReferences(formatted_comments, *service.file()->pool());
+  auto trailer = std::string{};
+  for (auto const& kv : references) {
+    absl::StrAppend(&trailer, "\n/// [", kv.first,
+                    "]: @googleapis_link_reference{", kv.second.filename, "#L",
+                    kv.second.lineno, "}");
+  }
+  if (!trailer.empty()) trailer += "\n///";
+
+  auto doxygen_formatted_comments = absl::StrCat("///\n///", formatted_comments,
+                                                 kFixedClientComment, trailer);
   return absl::StrReplaceAll(doxygen_formatted_comments, {{"///  ", "/// "}});
 }
 
diff --git a/generator/internal/format_class_comments_test.cc b/generator/internal/format_class_comments_test.cc
index cbaa9b6dbe920..f25a05129a708 100644
--- a/generator/internal/format_class_comments_test.cc
+++ b/generator/internal/format_class_comments_test.cc
@@ -25,7 +25,10 @@ namespace {
 
 using ::testing::AllOf;
 using ::testing::Contains;
+using ::testing::EndsWith;
+using ::testing::HasSubstr;
 using ::testing::NotNull;
+using ::testing::StartsWith;
 
 class FormatClassCommentsTest
     : public generator_testing::DescriptorPoolFixture {};
@@ -50,6 +53,8 @@ service Service {
   ASSERT_THAT(service, NotNull());
 
   auto const actual = FormatClassCommentsFromServiceComments(*service);
+  // Verify it has exactly one trailing `///` comment.
+  EXPECT_THAT(actual, AllOf(EndsWith("\n///"), Not(EndsWith("\n///\n///"))));
   auto const lines = std::vector<std::string>{absl::StrSplit(actual, '\n')};
   EXPECT_THAT(lines, AllOf(Contains("/// A brief description of the service."),
                            Contains("/// A longer description of the service."),
@@ -82,6 +87,55 @@ service Service {
                    Contains("/// @par Thread Safety")));
 }
 
+TEST_F(FormatClassCommentsTest, WithReferences) {
+  auto constexpr kContents = R"""(
+syntax = "proto3";
+import "test/v1/common.proto";
+package test.v1;
+
+// A brief description of the service.
+//
+// This references the [Request][test.v1.Request] message, another service
+// [OtherService][test.v1.OtherService], and even a field
+// [Resource.parent][test.v1.Resource.parent]
+service Service {
+    rpc Method(Request) returns (Response) {}
+}
+
+// Just to test references.
+service OtherService {}
+message Resource {
+    string parent = 1;
+}
+)""";
+
+  ASSERT_THAT(FindFile("test/v1/common.proto"), NotNull());
+  ASSERT_TRUE(AddProtoFile("test/v1/service.proto", kContents));
+  auto const* service = pool().FindServiceByName("test.v1.Service");
+  ASSERT_THAT(service, NotNull());
+
+  auto const actual = FormatClassCommentsFromServiceComments(*service);
+  // Verify the first reference is separated by an empty line and that it ends
+  // with a single `///` comment.
+  EXPECT_THAT(actual, AllOf(HasSubstr("///\n/// [test.v1.OtherService]: "),
+                            EndsWith("\n///"), Not(EndsWith("\n///\n///"))));
+  auto const lines = std::vector<std::string>{absl::StrSplit(actual, '\n')};
+  EXPECT_THAT(
+      lines,
+      AllOf(Contains("/// A brief description of the service."),
+            Contains(StartsWith(
+                "/// [test.v1.Request]: "
+                "@googleapis_link_reference{test/v1/common.proto#L")),
+            Contains(StartsWith(
+                "/// [test.v1.OtherService]: "
+                "@googleapis_link_reference{test/v1/service.proto#L")),
+            Contains(StartsWith(
+                "/// [test.v1.Resource.parent]: "
+                "@googleapis_link_reference{test/v1/service.proto#L")),
+            Contains("/// @par Equality"), Contains("/// @par Performance"),
+            Contains("/// @par Thread Safety")));
+}
+
 }  // namespace
 }  // namespace generator_internal
 }  // namespace cloud

From 3ee403e53524513cf229d49c29a5f33491198eff Mon Sep 17 00:00:00 2001
From: Carlos O'Ryan <coryan@google.com>
Date: Sat, 28 Jan 2023 16:45:34 +0000
Subject: [PATCH 2/2] Updated generated libraries

---
 google/cloud/accessapproval/v1/access_approval_client.h  | 3 +++
 .../binauthz_management_service_v1_client.h              | 5 +++++
 google/cloud/channel/cloud_channel_client.h              | 7 +++++++
 google/cloud/dialogflow_cx/agents_client.h               | 3 +++
 google/cloud/dialogflow_cx/changelogs_client.h           | 3 +++
 google/cloud/dialogflow_cx/deployments_client.h          | 3 +++
 google/cloud/dialogflow_cx/entity_types_client.h         | 3 +++
 google/cloud/dialogflow_cx/environments_client.h         | 3 +++
 google/cloud/dialogflow_cx/experiments_client.h          | 3 +++
 google/cloud/dialogflow_cx/flows_client.h                | 3 +++
 google/cloud/dialogflow_cx/intents_client.h              | 3 +++
 google/cloud/dialogflow_cx/pages_client.h                | 3 +++
 google/cloud/dialogflow_cx/session_entity_types_client.h | 3 +++
 google/cloud/dialogflow_cx/sessions_client.h             | 3 +++
 google/cloud/dialogflow_cx/test_cases_client.h           | 5 +++++
 .../cloud/dialogflow_cx/transition_route_groups_client.h | 3 +++
 google/cloud/dialogflow_cx/versions_client.h             | 3 +++
 google/cloud/dialogflow_cx/webhooks_client.h             | 3 +++
 google/cloud/dialogflow_es/agents_client.h               | 3 +++
 google/cloud/dialogflow_es/answer_records_client.h       | 3 +++
 google/cloud/dialogflow_es/contexts_client.h             | 3 +++
 .../cloud/dialogflow_es/conversation_profiles_client.h   | 3 +++
 google/cloud/dialogflow_es/conversations_client.h        | 3 +++
 google/cloud/dialogflow_es/documents_client.h            | 3 +++
 google/cloud/dialogflow_es/entity_types_client.h         | 3 +++
 google/cloud/dialogflow_es/environments_client.h         | 3 +++
 google/cloud/dialogflow_es/fulfillments_client.h         | 3 +++
 google/cloud/dialogflow_es/intents_client.h              | 3 +++
 google/cloud/dialogflow_es/knowledge_bases_client.h      | 3 +++
 google/cloud/dialogflow_es/participants_client.h         | 3 +++
 google/cloud/dialogflow_es/session_entity_types_client.h | 3 +++
 google/cloud/dialogflow_es/versions_client.h             | 3 +++
 google/cloud/gkehub/gke_hub_client.h                     | 5 +++++
 google/cloud/kms/ekm_client.h                            | 3 +++
 google/cloud/kms/key_management_client.h                 | 9 +++++++++
 google/cloud/privateca/certificate_authority_client.h    | 3 +++
 google/cloud/retail/product_client.h                     | 3 +++
 google/cloud/secretmanager/secret_manager_client.h       | 5 +++++
 google/cloud/servicedirectory/registration_client.h      | 7 +++++++
 google/cloud/vision/product_search_client.h              | 7 +++++++
 40 files changed, 146 insertions(+)

diff --git a/google/cloud/accessapproval/v1/access_approval_client.h b/google/cloud/accessapproval/v1/access_approval_client.h
index f501d8ab4f27b..822e7899b03ae 100644
--- a/google/cloud/accessapproval/v1/access_approval_client.h
+++ b/google/cloud/accessapproval/v1/access_approval_client.h
@@ -90,6 +90,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.accessapproval.v1.ApprovalRequest]:
+/// @googleapis_link_reference{google/cloud/accessapproval/v1/accessapproval.proto#L369}
+///
 class AccessApprovalClient {
  public:
   explicit AccessApprovalClient(
diff --git a/google/cloud/binaryauthorization/binauthz_management_service_v1_client.h b/google/cloud/binaryauthorization/binauthz_management_service_v1_client.h
index 8e6082f2d94ed..cf06f066c70e3 100644
--- a/google/cloud/binaryauthorization/binauthz_management_service_v1_client.h
+++ b/google/cloud/binaryauthorization/binauthz_management_service_v1_client.h
@@ -65,6 +65,11 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.binaryauthorization.v1.Attestor]:
+/// @googleapis_link_reference{google/cloud/binaryauthorization/v1/resources.proto#L168}
+/// [google.cloud.binaryauthorization.v1.Policy]:
+/// @googleapis_link_reference{google/cloud/binaryauthorization/v1/resources.proto#L32}
+///
 class BinauthzManagementServiceV1Client {
  public:
   explicit BinauthzManagementServiceV1Client(
diff --git a/google/cloud/channel/cloud_channel_client.h b/google/cloud/channel/cloud_channel_client.h
index e8421e07eab66..3ca8412f34055 100644
--- a/google/cloud/channel/cloud_channel_client.h
+++ b/google/cloud/channel/cloud_channel_client.h
@@ -78,6 +78,13 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.channel.v1.ChannelPartnerLink]:
+/// @googleapis_link_reference{google/cloud/channel/v1/channel_partner_links.proto#L66}
+/// [google.cloud.channel.v1.Customer]:
+/// @googleapis_link_reference{google/cloud/channel/v1/customers.proto#L31}
+/// [google.cloud.channel.v1.Entitlement]:
+/// @googleapis_link_reference{google/cloud/channel/v1/entitlements.proto#L32}
+///
 class CloudChannelServiceClient {
  public:
   explicit CloudChannelServiceClient(
diff --git a/google/cloud/dialogflow_cx/agents_client.h b/google/cloud/dialogflow_cx/agents_client.h
index 572c73b722480..1ada9da2c05b8 100644
--- a/google/cloud/dialogflow_cx/agents_client.h
+++ b/google/cloud/dialogflow_cx/agents_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.Agent]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/agent.proto#L183}
+///
 class AgentsClient {
  public:
   explicit AgentsClient(std::shared_ptr<AgentsConnection> connection,
diff --git a/google/cloud/dialogflow_cx/changelogs_client.h b/google/cloud/dialogflow_cx/changelogs_client.h
index a15b2dd1890d0..b94e90172d504 100644
--- a/google/cloud/dialogflow_cx/changelogs_client.h
+++ b/google/cloud/dialogflow_cx/changelogs_client.h
@@ -58,6 +58,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.Changelog]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/changelog.proto#L128}
+///
 class ChangelogsClient {
  public:
   explicit ChangelogsClient(std::shared_ptr<ChangelogsConnection> connection,
diff --git a/google/cloud/dialogflow_cx/deployments_client.h b/google/cloud/dialogflow_cx/deployments_client.h
index 3586ec9fba554..bd6ca149f35d4 100644
--- a/google/cloud/dialogflow_cx/deployments_client.h
+++ b/google/cloud/dialogflow_cx/deployments_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.Deployment]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/deployment.proto#L65}
+///
 class DeploymentsClient {
  public:
   explicit DeploymentsClient(std::shared_ptr<DeploymentsConnection> connection,
diff --git a/google/cloud/dialogflow_cx/entity_types_client.h b/google/cloud/dialogflow_cx/entity_types_client.h
index 88834dad2cbb8..396930b276b2d 100644
--- a/google/cloud/dialogflow_cx/entity_types_client.h
+++ b/google/cloud/dialogflow_cx/entity_types_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.EntityType]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/entity_type.proto#L128}
+///
 class EntityTypesClient {
  public:
   explicit EntityTypesClient(std::shared_ptr<EntityTypesConnection> connection,
diff --git a/google/cloud/dialogflow_cx/environments_client.h b/google/cloud/dialogflow_cx/environments_client.h
index 7e85d61cade51..cd42731e0ab43 100644
--- a/google/cloud/dialogflow_cx/environments_client.h
+++ b/google/cloud/dialogflow_cx/environments_client.h
@@ -60,6 +60,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.Environment]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/environment.proto#L195}
+///
 class EnvironmentsClient {
  public:
   explicit EnvironmentsClient(
diff --git a/google/cloud/dialogflow_cx/experiments_client.h b/google/cloud/dialogflow_cx/experiments_client.h
index df706a5a8340d..8417a625f442b 100644
--- a/google/cloud/dialogflow_cx/experiments_client.h
+++ b/google/cloud/dialogflow_cx/experiments_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.Experiment]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/experiment.proto#L116}
+///
 class ExperimentsClient {
  public:
   explicit ExperimentsClient(std::shared_ptr<ExperimentsConnection> connection,
diff --git a/google/cloud/dialogflow_cx/flows_client.h b/google/cloud/dialogflow_cx/flows_client.h
index f7c2e80cf29ca..8685924983395 100644
--- a/google/cloud/dialogflow_cx/flows_client.h
+++ b/google/cloud/dialogflow_cx/flows_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.Flow]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/flow.proto#L250}
+///
 class FlowsClient {
  public:
   explicit FlowsClient(std::shared_ptr<FlowsConnection> connection,
diff --git a/google/cloud/dialogflow_cx/intents_client.h b/google/cloud/dialogflow_cx/intents_client.h
index 7595ac82847bc..6357509cd6499 100644
--- a/google/cloud/dialogflow_cx/intents_client.h
+++ b/google/cloud/dialogflow_cx/intents_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.Intent]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/intent.proto#L102}
+///
 class IntentsClient {
  public:
   explicit IntentsClient(std::shared_ptr<IntentsConnection> connection,
diff --git a/google/cloud/dialogflow_cx/pages_client.h b/google/cloud/dialogflow_cx/pages_client.h
index 73267e45d5bc9..d09aee4613bfc 100644
--- a/google/cloud/dialogflow_cx/pages_client.h
+++ b/google/cloud/dialogflow_cx/pages_client.h
@@ -58,6 +58,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.Page]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/page.proto#L115}
+///
 class PagesClient {
  public:
   explicit PagesClient(std::shared_ptr<PagesConnection> connection,
diff --git a/google/cloud/dialogflow_cx/session_entity_types_client.h b/google/cloud/dialogflow_cx/session_entity_types_client.h
index e38c13675f959..95ff0ae2ce71e 100644
--- a/google/cloud/dialogflow_cx/session_entity_types_client.h
+++ b/google/cloud/dialogflow_cx/session_entity_types_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.SessionEntityType]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/session_entity_type.proto#L122}
+///
 class SessionEntityTypesClient {
  public:
   explicit SessionEntityTypesClient(
diff --git a/google/cloud/dialogflow_cx/sessions_client.h b/google/cloud/dialogflow_cx/sessions_client.h
index bcc442f6b29bb..130cff212b424 100644
--- a/google/cloud/dialogflow_cx/sessions_client.h
+++ b/google/cloud/dialogflow_cx/sessions_client.h
@@ -61,6 +61,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.Sessions.DetectIntent]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/session.proto#L65}
+///
 class SessionsClient {
  public:
   explicit SessionsClient(std::shared_ptr<SessionsConnection> connection,
diff --git a/google/cloud/dialogflow_cx/test_cases_client.h b/google/cloud/dialogflow_cx/test_cases_client.h
index 657e44aef29ce..38c174bb1e3ad 100644
--- a/google/cloud/dialogflow_cx/test_cases_client.h
+++ b/google/cloud/dialogflow_cx/test_cases_client.h
@@ -60,6 +60,11 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.TestCase]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/test_case.proto#L214}
+/// [google.cloud.dialogflow.cx.v3.TestCaseResult]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/test_case.proto#L256}
+///
 class TestCasesClient {
  public:
   explicit TestCasesClient(std::shared_ptr<TestCasesConnection> connection,
diff --git a/google/cloud/dialogflow_cx/transition_route_groups_client.h b/google/cloud/dialogflow_cx/transition_route_groups_client.h
index fc2a217f1b6fb..13ffbf8149ead 100644
--- a/google/cloud/dialogflow_cx/transition_route_groups_client.h
+++ b/google/cloud/dialogflow_cx/transition_route_groups_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.TransitionRouteGroup]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/transition_route_group.proto#L112}
+///
 class TransitionRouteGroupsClient {
  public:
   explicit TransitionRouteGroupsClient(
diff --git a/google/cloud/dialogflow_cx/versions_client.h b/google/cloud/dialogflow_cx/versions_client.h
index 0277dae2a812a..03a9e677231b4 100644
--- a/google/cloud/dialogflow_cx/versions_client.h
+++ b/google/cloud/dialogflow_cx/versions_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.Version]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/version.proto#L147}
+///
 class VersionsClient {
  public:
   explicit VersionsClient(std::shared_ptr<VersionsConnection> connection,
diff --git a/google/cloud/dialogflow_cx/webhooks_client.h b/google/cloud/dialogflow_cx/webhooks_client.h
index 8db2c891037ce..5bed96802bda5 100644
--- a/google/cloud/dialogflow_cx/webhooks_client.h
+++ b/google/cloud/dialogflow_cx/webhooks_client.h
@@ -58,6 +58,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.cx.v3.Webhook]:
+/// @googleapis_link_reference{google/cloud/dialogflow/cx/v3/webhook.proto#L96}
+///
 class WebhooksClient {
  public:
   explicit WebhooksClient(std::shared_ptr<WebhooksConnection> connection,
diff --git a/google/cloud/dialogflow_es/agents_client.h b/google/cloud/dialogflow_es/agents_client.h
index fc79ec0bbfb4c..abd83f97729ee 100644
--- a/google/cloud/dialogflow_es/agents_client.h
+++ b/google/cloud/dialogflow_es/agents_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.Agent]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/agent.proto#L258}
+///
 class AgentsClient {
  public:
   explicit AgentsClient(std::shared_ptr<AgentsConnection> connection,
diff --git a/google/cloud/dialogflow_es/answer_records_client.h b/google/cloud/dialogflow_es/answer_records_client.h
index 0cb3df3677e0c..123f2b0133d1d 100644
--- a/google/cloud/dialogflow_es/answer_records_client.h
+++ b/google/cloud/dialogflow_es/answer_records_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.AnswerRecord]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/answer_record.proto#L98}
+///
 class AnswerRecordsClient {
  public:
   explicit AnswerRecordsClient(
diff --git a/google/cloud/dialogflow_es/contexts_client.h b/google/cloud/dialogflow_es/contexts_client.h
index b1bf74c3a9c19..6fbb0ad8b16e2 100644
--- a/google/cloud/dialogflow_es/contexts_client.h
+++ b/google/cloud/dialogflow_es/contexts_client.h
@@ -58,6 +58,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.Context]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/context.proto#L171}
+///
 class ContextsClient {
  public:
   explicit ContextsClient(std::shared_ptr<ContextsConnection> connection,
diff --git a/google/cloud/dialogflow_es/conversation_profiles_client.h b/google/cloud/dialogflow_es/conversation_profiles_client.h
index 7473722e298e4..7c9ff764bd40f 100644
--- a/google/cloud/dialogflow_es/conversation_profiles_client.h
+++ b/google/cloud/dialogflow_es/conversation_profiles_client.h
@@ -60,6 +60,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.ConversationProfile]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/conversation_profile.proto#L189}
+///
 class ConversationProfilesClient {
  public:
   explicit ConversationProfilesClient(
diff --git a/google/cloud/dialogflow_es/conversations_client.h b/google/cloud/dialogflow_es/conversations_client.h
index b6d8a6106a795..bbf8f34961688 100644
--- a/google/cloud/dialogflow_es/conversations_client.h
+++ b/google/cloud/dialogflow_es/conversations_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.Conversation]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/conversation.proto#L148}
+///
 class ConversationsClient {
  public:
   explicit ConversationsClient(
diff --git a/google/cloud/dialogflow_es/documents_client.h b/google/cloud/dialogflow_es/documents_client.h
index 757431fe8074d..cc15b96409a1e 100644
--- a/google/cloud/dialogflow_es/documents_client.h
+++ b/google/cloud/dialogflow_es/documents_client.h
@@ -61,6 +61,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.Document]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/document.proto#L260}
+///
 class DocumentsClient {
  public:
   explicit DocumentsClient(std::shared_ptr<DocumentsConnection> connection,
diff --git a/google/cloud/dialogflow_es/entity_types_client.h b/google/cloud/dialogflow_es/entity_types_client.h
index dec27a0918382..784e2bd7c7fd8 100644
--- a/google/cloud/dialogflow_es/entity_types_client.h
+++ b/google/cloud/dialogflow_es/entity_types_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.EntityType]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/entity_type.proto#L292}
+///
 class EntityTypesClient {
  public:
   explicit EntityTypesClient(std::shared_ptr<EntityTypesConnection> connection,
diff --git a/google/cloud/dialogflow_es/environments_client.h b/google/cloud/dialogflow_es/environments_client.h
index a8744c3d09496..3f870b5fdf757 100644
--- a/google/cloud/dialogflow_es/environments_client.h
+++ b/google/cloud/dialogflow_es/environments_client.h
@@ -58,6 +58,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.Environment]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/environment.proto#L142}
+///
 class EnvironmentsClient {
  public:
   explicit EnvironmentsClient(
diff --git a/google/cloud/dialogflow_es/fulfillments_client.h b/google/cloud/dialogflow_es/fulfillments_client.h
index 1d5d58cfba1d6..d470b89f74f0c 100644
--- a/google/cloud/dialogflow_es/fulfillments_client.h
+++ b/google/cloud/dialogflow_es/fulfillments_client.h
@@ -58,6 +58,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.Fulfillment]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/fulfillment.proto#L75}
+///
 class FulfillmentsClient {
  public:
   explicit FulfillmentsClient(
diff --git a/google/cloud/dialogflow_es/intents_client.h b/google/cloud/dialogflow_es/intents_client.h
index 9179f2e66a7aa..b2ea7c6a12e9d 100644
--- a/google/cloud/dialogflow_es/intents_client.h
+++ b/google/cloud/dialogflow_es/intents_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.Intent]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/intent.proto#L198}
+///
 class IntentsClient {
  public:
   explicit IntentsClient(std::shared_ptr<IntentsConnection> connection,
diff --git a/google/cloud/dialogflow_es/knowledge_bases_client.h b/google/cloud/dialogflow_es/knowledge_bases_client.h
index 40cadb6b790a5..c95a92bf7ad30 100644
--- a/google/cloud/dialogflow_es/knowledge_bases_client.h
+++ b/google/cloud/dialogflow_es/knowledge_bases_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.KnowledgeBase]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/knowledge_base.proto#L131}
+///
 class KnowledgeBasesClient {
  public:
   explicit KnowledgeBasesClient(
diff --git a/google/cloud/dialogflow_es/participants_client.h b/google/cloud/dialogflow_es/participants_client.h
index b4626bc7c41af..7efada5dd34d2 100644
--- a/google/cloud/dialogflow_es/participants_client.h
+++ b/google/cloud/dialogflow_es/participants_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.Participant]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/participant.proto#L178}
+///
 class ParticipantsClient {
  public:
   explicit ParticipantsClient(
diff --git a/google/cloud/dialogflow_es/session_entity_types_client.h b/google/cloud/dialogflow_es/session_entity_types_client.h
index 5a23b6854d691..859190a034012 100644
--- a/google/cloud/dialogflow_es/session_entity_types_client.h
+++ b/google/cloud/dialogflow_es/session_entity_types_client.h
@@ -59,6 +59,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.SessionEntityType]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/session_entity_type.proto#L174}
+///
 class SessionEntityTypesClient {
  public:
   explicit SessionEntityTypesClient(
diff --git a/google/cloud/dialogflow_es/versions_client.h b/google/cloud/dialogflow_es/versions_client.h
index d018763e4d3fe..f5fc94ce439f5 100644
--- a/google/cloud/dialogflow_es/versions_client.h
+++ b/google/cloud/dialogflow_es/versions_client.h
@@ -58,6 +58,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.dialogflow.v2.Version]:
+/// @googleapis_link_reference{google/cloud/dialogflow/v2/version.proto#L126}
+///
 class VersionsClient {
  public:
   explicit VersionsClient(std::shared_ptr<VersionsConnection> connection,
diff --git a/google/cloud/gkehub/gke_hub_client.h b/google/cloud/gkehub/gke_hub_client.h
index 7df7012759dc2..01504e141c686 100644
--- a/google/cloud/gkehub/gke_hub_client.h
+++ b/google/cloud/gkehub/gke_hub_client.h
@@ -73,6 +73,11 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.gkehub.v1.Feature]:
+/// @googleapis_link_reference{google/cloud/gkehub/v1/feature.proto#L34}
+/// [google.cloud.gkehub.v1.Membership]:
+/// @googleapis_link_reference{google/cloud/gkehub/v1/membership.proto#L32}
+///
 class GkeHubClient {
  public:
   explicit GkeHubClient(std::shared_ptr<GkeHubConnection> connection,
diff --git a/google/cloud/kms/ekm_client.h b/google/cloud/kms/ekm_client.h
index 38613154e1b98..3dc4662f06b6a 100644
--- a/google/cloud/kms/ekm_client.h
+++ b/google/cloud/kms/ekm_client.h
@@ -62,6 +62,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.kms.v1.EkmConnection]:
+/// @googleapis_link_reference{google/cloud/kms/v1/ekm_service.proto#L239}
+///
 class EkmServiceClient {
  public:
   explicit EkmServiceClient(std::shared_ptr<EkmServiceConnection> connection,
diff --git a/google/cloud/kms/key_management_client.h b/google/cloud/kms/key_management_client.h
index fe0bb57fb36e4..3060df83cc3c2 100644
--- a/google/cloud/kms/key_management_client.h
+++ b/google/cloud/kms/key_management_client.h
@@ -70,6 +70,15 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.kms.v1.CryptoKey]:
+/// @googleapis_link_reference{google/cloud/kms/v1/resources.proto#L58}
+/// [google.cloud.kms.v1.CryptoKeyVersion]:
+/// @googleapis_link_reference{google/cloud/kms/v1/resources.proto#L284}
+/// [google.cloud.kms.v1.ImportJob]:
+/// @googleapis_link_reference{google/cloud/kms/v1/resources.proto#L666}
+/// [google.cloud.kms.v1.KeyRing]:
+/// @googleapis_link_reference{google/cloud/kms/v1/resources.proto#L35}
+///
 class KeyManagementServiceClient {
  public:
   explicit KeyManagementServiceClient(
diff --git a/google/cloud/privateca/certificate_authority_client.h b/google/cloud/privateca/certificate_authority_client.h
index 47c79ae0b8401..b12b7b386a03d 100644
--- a/google/cloud/privateca/certificate_authority_client.h
+++ b/google/cloud/privateca/certificate_authority_client.h
@@ -62,6 +62,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.security.privateca.v1.CertificateAuthorityService]:
+/// @googleapis_link_reference{google/cloud/security/privateca/v1/service.proto#L39}
+///
 class CertificateAuthorityServiceClient {
  public:
   explicit CertificateAuthorityServiceClient(
diff --git a/google/cloud/retail/product_client.h b/google/cloud/retail/product_client.h
index 58f4b91e328e1..38182ff292cb9 100644
--- a/google/cloud/retail/product_client.h
+++ b/google/cloud/retail/product_client.h
@@ -61,6 +61,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.retail.v2.Product]:
+/// @googleapis_link_reference{google/cloud/retail/v2/product.proto#L43}
+///
 class ProductServiceClient {
  public:
   explicit ProductServiceClient(
diff --git a/google/cloud/secretmanager/secret_manager_client.h b/google/cloud/secretmanager/secret_manager_client.h
index 9c58c1e2a39da..ebd9c5eb760d7 100644
--- a/google/cloud/secretmanager/secret_manager_client.h
+++ b/google/cloud/secretmanager/secret_manager_client.h
@@ -65,6 +65,11 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.secretmanager.v1.Secret]:
+/// @googleapis_link_reference{google/cloud/secretmanager/v1/resources.proto#L40}
+/// [google.cloud.secretmanager.v1.SecretVersion]:
+/// @googleapis_link_reference{google/cloud/secretmanager/v1/resources.proto#L144}
+///
 class SecretManagerServiceClient {
  public:
   explicit SecretManagerServiceClient(
diff --git a/google/cloud/servicedirectory/registration_client.h b/google/cloud/servicedirectory/registration_client.h
index 5561e01b27d5d..3ab715db7900d 100644
--- a/google/cloud/servicedirectory/registration_client.h
+++ b/google/cloud/servicedirectory/registration_client.h
@@ -73,6 +73,13 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.servicedirectory.v1.Endpoint]:
+/// @googleapis_link_reference{google/cloud/servicedirectory/v1/endpoint.proto#L33}
+/// [google.cloud.servicedirectory.v1.Namespace]:
+/// @googleapis_link_reference{google/cloud/servicedirectory/v1/namespace.proto#L34}
+/// [google.cloud.servicedirectory.v1.Service]:
+/// @googleapis_link_reference{google/cloud/servicedirectory/v1/service.proto#L36}
+///
 class RegistrationServiceClient {
  public:
   explicit RegistrationServiceClient(
diff --git a/google/cloud/vision/product_search_client.h b/google/cloud/vision/product_search_client.h
index eff1cdf6e91b0..3ea96c9d65601 100644
--- a/google/cloud/vision/product_search_client.h
+++ b/google/cloud/vision/product_search_client.h
@@ -75,6 +75,13 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// and move-construction is a relatively efficient operation, consider using
 /// such a copy when using this class from multiple threads.
 ///
+/// [google.cloud.vision.v1.Product]:
+/// @googleapis_link_reference{google/cloud/vision/v1/product_search_service.proto#L365}
+/// [google.cloud.vision.v1.ProductSet]:
+/// @googleapis_link_reference{google/cloud/vision/v1/product_search_service.proto#L423}
+/// [google.cloud.vision.v1.ReferenceImage]:
+/// @googleapis_link_reference{google/cloud/vision/v1/product_search_service.proto#L458}
+///
 class ProductSearchClient {
  public:
   explicit ProductSearchClient(