From fd4cfca585d38504e0fbad9403a300c8f76661db Mon Sep 17 00:00:00 2001
From: Noah Dietz <ndietz@google.com>
Date: Thu, 11 Dec 2025 19:26:15 +0000
Subject: [PATCH 1/7] fix: add api_version breadcrumb to client docs

---
 .../comment/ServiceClientCommentComposer.java       | 13 +++++++++++--
 .../gapic/composer/grpc/goldens/EchoClient.golden   |  2 ++
 .../com/google/showcase/v1beta1/EchoClient.java     |  2 ++
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
index 16d21ef0f9..f2358612be 100644
--- a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
+++ b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
@@ -108,9 +108,18 @@ public static List<CommentStatement> createClassHeaderComments(
       String secondaryTransport) {
     JavaDocComment.Builder classHeaderJavadocBuilder = JavaDocComment.builder();
     if (service.hasDescription()) {
+      String description = service.description();
+
+      // Include google.api.api_version breadcrumb comment.
+      if (service.hasApiVersion()) {
+        description =
+            String.format(
+                "%s\n\nThis client uses %s version %s.",
+                description, service.apiShortName(), service.apiVersion());
+      }
+
       String descriptionComment =
-          CommentFormatter.formatAsJavaDocComment(
-              service.description(), SERVICE_DESCRIPTION_SUMMARY_PATTERN);
+          CommentFormatter.formatAsJavaDocComment(description, SERVICE_DESCRIPTION_SUMMARY_PATTERN);
       classHeaderJavadocBuilder = classHeaderJavadocBuilder.addUnescapedComment(descriptionComment);
     }
 
diff --git a/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoClient.golden b/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoClient.golden
index 612111aea0..3ba91a4c98 100644
--- a/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoClient.golden
+++ b/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoClient.golden
@@ -35,6 +35,8 @@ import javax.annotation.Generated;
  * methods that explicitly implement server delay, and paginated calls. Set the 'showcase-trailer'
  * metadata key on any method to have the values echoed in the response trailers.
  *
+ * This client uses Echo version v1_20240408.
+ *
  * <p>This class provides the ability to make remote calls to the backing service through method
  * calls that map to API methods. Sample code to get started:
  *
diff --git a/java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/EchoClient.java b/java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/EchoClient.java
index 5f0a0b0a3d..5da527c020 100644
--- a/java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/EchoClient.java
+++ b/java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/EchoClient.java
@@ -59,6 +59,8 @@
  * 'x-goog-request-params' metadata key on any method to have the values echoed in the response
  * headers.
  *
+ * This client uses Echo version v1_20240408.
+ *
  * <p>This class provides the ability to make remote calls to the backing service through method
  * calls that map to API methods. Sample code to get started:
  *

From 8f134cf0df308fe4281cdf942d706da6a93ef63c Mon Sep 17 00:00:00 2001
From: Noah Dietz <ndietz@google.com>
Date: Thu, 11 Dec 2025 20:05:13 +0000
Subject: [PATCH 2/7] move api_version breadcrumb out of description condition

---
 .../comment/ServiceClientCommentComposer.java | 20 +++++++++----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
index f2358612be..61964a451d 100644
--- a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
+++ b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
@@ -108,21 +108,19 @@ public static List<CommentStatement> createClassHeaderComments(
       String secondaryTransport) {
     JavaDocComment.Builder classHeaderJavadocBuilder = JavaDocComment.builder();
     if (service.hasDescription()) {
-      String description = service.description();
-
-      // Include google.api.api_version breadcrumb comment.
-      if (service.hasApiVersion()) {
-        description =
-            String.format(
-                "%s\n\nThis client uses %s version %s.",
-                description, service.apiShortName(), service.apiVersion());
-      }
-
       String descriptionComment =
-          CommentFormatter.formatAsJavaDocComment(description, SERVICE_DESCRIPTION_SUMMARY_PATTERN);
+          CommentFormatter.formatAsJavaDocComment(
+              service.description(), SERVICE_DESCRIPTION_SUMMARY_PATTERN);
       classHeaderJavadocBuilder = classHeaderJavadocBuilder.addUnescapedComment(descriptionComment);
     }
 
+    // Include google.api.api_version breadcrumb comment.
+    if (service.hasApiVersion()) {
+      classHeaderJavadocBuilder.addUnescapedComment(
+          String.format(
+              "This client uses %s version %s.", service.apiShortName(), service.apiVersion()));
+    }
+
     // Service introduction.
     classHeaderJavadocBuilder.addParagraph(SERVICE_DESCRIPTION_INTRO_STRING);
     classHeaderJavadocBuilder.addSampleCode(classMethodSampleCode);

From e4de1935b81619de186fe4942f1e4b7457a139da Mon Sep 17 00:00:00 2001
From: Noah Dietz <ndietz@google.com>
Date: Thu, 11 Dec 2025 20:07:44 +0000
Subject: [PATCH 3/7] use name() access

---
 .../gapic/composer/comment/ServiceClientCommentComposer.java    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
index 61964a451d..f66b7b30a4 100644
--- a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
+++ b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
@@ -118,7 +118,7 @@ public static List<CommentStatement> createClassHeaderComments(
     if (service.hasApiVersion()) {
       classHeaderJavadocBuilder.addUnescapedComment(
           String.format(
-              "This client uses %s version %s.", service.apiShortName(), service.apiVersion()));
+              "This client uses %s version %s.", service.name(), service.apiVersion()));
     }
 
     // Service introduction.

From 5f6f92ce6f0bf040b9e73c61ef65f51ef64e0d92 Mon Sep 17 00:00:00 2001
From: Noah Dietz <ndietz@google.com>
Date: Thu, 11 Dec 2025 20:48:50 +0000
Subject: [PATCH 4/7] fix format

---
 .../gapic/composer/comment/ServiceClientCommentComposer.java   | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
index f66b7b30a4..b9fb51674a 100644
--- a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
+++ b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
@@ -117,8 +117,7 @@ public static List<CommentStatement> createClassHeaderComments(
     // Include google.api.api_version breadcrumb comment.
     if (service.hasApiVersion()) {
       classHeaderJavadocBuilder.addUnescapedComment(
-          String.format(
-              "This client uses %s version %s.", service.name(), service.apiVersion()));
+          String.format("This client uses %s version %s.", service.name(), service.apiVersion()));
     }
 
     // Service introduction.

From 486ef817c61f6b9ac5edfa38db8ee54b1eb5219c Mon Sep 17 00:00:00 2001
From: Noah Dietz <ndietz@google.com>
Date: Thu, 11 Dec 2025 21:04:55 +0000
Subject: [PATCH 5/7] swich to addComment, adjust goldens

---
 .../gapic/composer/comment/ServiceClientCommentComposer.java    | 2 +-
 .../api/generator/gapic/composer/grpc/goldens/EchoClient.golden | 2 --
 .../generator/gapic/composer/grpcrest/goldens/EchoClient.golden | 2 ++
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
index b9fb51674a..1e1ff21406 100644
--- a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
+++ b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
@@ -116,7 +116,7 @@ public static List<CommentStatement> createClassHeaderComments(
 
     // Include google.api.api_version breadcrumb comment.
     if (service.hasApiVersion()) {
-      classHeaderJavadocBuilder.addUnescapedComment(
+      classHeaderJavadocBuilder.addComment(
           String.format("This client uses %s version %s.", service.name(), service.apiVersion()));
     }
 
diff --git a/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoClient.golden b/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoClient.golden
index 3ba91a4c98..612111aea0 100644
--- a/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoClient.golden
+++ b/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoClient.golden
@@ -35,8 +35,6 @@ import javax.annotation.Generated;
  * methods that explicitly implement server delay, and paginated calls. Set the 'showcase-trailer'
  * metadata key on any method to have the values echoed in the response trailers.
  *
- * This client uses Echo version v1_20240408.
- *
  * <p>This class provides the ability to make remote calls to the backing service through method
  * calls that map to API methods. Sample code to get started:
  *
diff --git a/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden b/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden
index bf68adf425..76c0826d03 100644
--- a/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden
+++ b/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden
@@ -30,6 +30,8 @@ import javax.annotation.Generated;
 
 // AUTO-GENERATED DOCUMENTATION AND CLASS.
 /**
+ * This client uses Echo version foo_version_for_tests.
+ *
  * This class provides the ability to make remote calls to the backing service through method calls
  * that map to API methods. Sample code to get started:
  *

From 98acc7a3eb39ea7080047d2d983f1d2ffd07cc50 Mon Sep 17 00:00:00 2001
From: Noah Dietz <ndietz@google.com>
Date: Thu, 11 Dec 2025 21:12:29 +0000
Subject: [PATCH 6/7] switch to addParagraph, update goldens

---
 .../gapic/composer/comment/ServiceClientCommentComposer.java    | 2 +-
 .../generator/gapic/composer/grpcrest/goldens/EchoClient.golden | 2 +-
 .../src/main/java/com/google/showcase/v1beta1/EchoClient.java   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
index 1e1ff21406..64ea4adf7c 100644
--- a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
+++ b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
@@ -116,7 +116,7 @@ public static List<CommentStatement> createClassHeaderComments(
 
     // Include google.api.api_version breadcrumb comment.
     if (service.hasApiVersion()) {
-      classHeaderJavadocBuilder.addComment(
+      classHeaderJavadocBuilder.addParagraph(
           String.format("This client uses %s version %s.", service.name(), service.apiVersion()));
     }
 
diff --git a/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden b/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden
index 76c0826d03..78cdfb6062 100644
--- a/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden
+++ b/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden
@@ -32,7 +32,7 @@ import javax.annotation.Generated;
 /**
  * This client uses Echo version foo_version_for_tests.
  *
- * This class provides the ability to make remote calls to the backing service through method calls
+ * <p>This class provides the ability to make remote calls to the backing service through method calls
  * that map to API methods. Sample code to get started:
  *
  * <pre>{@code
diff --git a/java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/EchoClient.java b/java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/EchoClient.java
index 5da527c020..1a2b9d3fa5 100644
--- a/java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/EchoClient.java
+++ b/java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/EchoClient.java
@@ -59,7 +59,7 @@
  * 'x-goog-request-params' metadata key on any method to have the values echoed in the response
  * headers.
  *
- * This client uses Echo version v1_20240408.
+ * <p>This client uses Echo version v1_20240408.
  *
  * <p>This class provides the ability to make remote calls to the backing service through method
  * calls that map to API methods. Sample code to get started:

From 05f24a24ee672d80f4ff1cd9417feba90b260124 Mon Sep 17 00:00:00 2001
From: Noah Dietz <ndietz@google.com>
Date: Thu, 11 Dec 2025 21:30:32 +0000
Subject: [PATCH 7/7] fix golden line wrapping

---
 .../gapic/composer/grpcrest/goldens/EchoClient.golden         | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden b/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden
index 78cdfb6062..91e167d4e1 100644
--- a/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden
+++ b/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden
@@ -32,8 +32,8 @@ import javax.annotation.Generated;
 /**
  * This client uses Echo version foo_version_for_tests.
  *
- * <p>This class provides the ability to make remote calls to the backing service through method calls
- * that map to API methods. Sample code to get started:
+ * <p>This class provides the ability to make remote calls to the backing service through method
+ * calls that map to API methods. Sample code to get started:
  *
  * <pre>{@code
  * // This snippet has been automatically generated and should be regarded as a code template only.