feat(generator): link references in service comments

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, {{"///  ", "/// "}});
 }
 

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

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(

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(

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(

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,

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,

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,

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,

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(

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,

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,

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,

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,

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(

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,

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,

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(

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,

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,

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,

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(

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,

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(

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(

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,