Change internalApi javadoc comment to be additional descriptive text.

Author: cindy-peng

gapic-generator-java/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java

@@ -149,7 +149,11 @@ public boolean emptyComments() {
     }
 
     public JavaDocComment build() {
-      // @param, @throws, @return, @deprecated and @internalApi should always get printed at the
+      // Add additional descriptive text before block tags.
+      if (!Strings.isNullOrEmpty(internalOnly)) {
+        componentsList.add(String.format("<p> <b>Warning: </b>%s", HtmlEscaper.process(internalOnly)));
+      }
+      // @param, @throws, @return and @deprecated should always get printed at the
       // end.
       componentsList.addAll(paramsList);
       if (!Strings.isNullOrEmpty(throwsType)) {
@@ -159,9 +163,6 @@ public JavaDocComment build() {
       if (!Strings.isNullOrEmpty(deprecated)) {
         componentsList.add(String.format("@deprecated %s", deprecated));
       }
-      if (!Strings.isNullOrEmpty(internalOnly)) {
-        componentsList.add(String.format("@internalApi %s", internalOnly));
-      }
       if (!Strings.isNullOrEmpty(returnDescription)) {
         componentsList.add(String.format("@return %s", returnDescription));
       }

gapic-generator-java/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java

@@ -217,9 +217,9 @@ void createJavaDocComment_throwsAndDeprecatedAndInternalAndReturn() {
             .build();
     String expected =
         LineFormatter.lines(
+            "<p> <b>Warning: </b>This method is internal used only. Please do not use directly.\n",
             "@throws java.lang.RuntimeException if the remote call fails.\n",
             "@deprecated Use the {@link ShelfBookName} class instead.\n",
-            "@internalApi This method is internal used only. Please do not use directly.\n",
             "@return This is the correct method return text.");
     assertEquals(expected, javaDocComment.comment());
   }
@@ -228,7 +228,7 @@ void createJavaDocComment_throwsAndDeprecatedAndInternalAndReturn() {
   void createJavaDocComment_allComponents() {
     // No matter what order `setThrows`, `setDeprecated`, and `setReturn` are called,
     // They will be printed at the end. And `@param` should be grouped,
-    // they should always be printed right before `@throws`, `@deprecated`, `@InternalApi` and
+    // they should always be printed right before `@throws`, `@deprecated` and
     // `@return`.
     // All other add methods should keep the order of how they are added.
     String content = "this is a test comment";
@@ -274,11 +274,11 @@ void createJavaDocComment_allComponents() {
             "<li> A request object method.\n",
             "<li> A callable method.\n",
             "</ol>\n",
+            "<p> <b>Warning: </b>This method is internal used only. Please do not use directly.\n",
             "@param shelfName The name of the shelf where books are published to.\n",
             "@param shelf The shelf to create.\n",
             "@throws com.google.api.gax.rpc.ApiException if the remote call fails.\n",
             "@deprecated Use the {@link ArchivedBookName} class instead.\n",
-            "@internalApi This method is internal used only. Please do not use directly.\n",
             "@return This is the method return text.");
     assertEquals(expected, javaDocComment.comment());
   }

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoServiceSelectiveGapicClient.golden

@@ -437,9 +437,10 @@ public class EchoServiceShouldGeneratePartialUsualClient implements BackgroundRe
    * }
    * }</pre>
    *
+   * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
+   *
    * @param request The request object containing all of the parameters for the API call.
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
-   * @internalApi This method is internal used only. Please do not use directly.
    */
   @InternalApi("Internal API. This API is not intended for public consumption.")
   public final EchoResponse chatShouldGenerateAsInternal() {
@@ -465,9 +466,10 @@ public class EchoServiceShouldGeneratePartialUsualClient implements BackgroundRe
    * }
    * }</pre>
    *
+   * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
+   *
    * @param name
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
-   * @internalApi This method is internal used only. Please do not use directly.
    */
   @InternalApi("Internal API. This API is not intended for public consumption.")
   public final EchoResponse chatShouldGenerateAsInternal(FoobarName name) {
@@ -494,9 +496,10 @@ public class EchoServiceShouldGeneratePartialUsualClient implements BackgroundRe
    * }
    * }</pre>
    *
+   * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
+   *
    * @param name
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
-   * @internalApi This method is internal used only. Please do not use directly.
    */
   @InternalApi("Internal API. This API is not intended for public consumption.")
   public final EchoResponse chatShouldGenerateAsInternal(String name) {
@@ -527,9 +530,10 @@ public class EchoServiceShouldGeneratePartialUsualClient implements BackgroundRe
    * }
    * }</pre>
    *
+   * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
+   *
    * @param request The request object containing all of the parameters for the API call.
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
-   * @internalApi This method is internal used only. Please do not use directly.
    */
   @InternalApi("Internal API. This API is not intended for public consumption.")
   public final EchoResponse chatShouldGenerateAsInternal(EchoRequest request) {
@@ -563,7 +567,7 @@ public class EchoServiceShouldGeneratePartialUsualClient implements BackgroundRe
    * }
    * }</pre>
    *
-   * @internalApi This method is internal used only. Please do not use directly.
+   * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
    */
   @InternalApi("Internal API. This API is not intended for public consumption.")
   public final UnaryCallable<EchoRequest, EchoResponse> chatShouldGenerateAsInternalCallable() {
@@ -597,7 +601,7 @@ public class EchoServiceShouldGeneratePartialUsualClient implements BackgroundRe
    * }
    * }</pre>
    *
-   * @internalApi This method is internal used only. Please do not use directly.
+   * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
    */
   @InternalApi("Internal API. This API is not intended for public consumption.")
   public final BidiStreamingCallable<EchoRequest, EchoResponse>

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoServiceSelectiveGapicServiceSettings.golden

@@ -96,7 +96,7 @@ public class EchoServiceShouldGeneratePartialUsualSettings
   /**
    * Returns the object with the settings used for calls to chatShouldGenerateAsInternal.
    *
-   * @internalApi This method is internal used only. Please do not use directly.
+   * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
    */
   @InternalApi("Internal API. This API is not intended for public consumption.")
   public UnaryCallSettings<EchoRequest, EchoResponse> chatShouldGenerateAsInternalSettings() {
@@ -107,7 +107,7 @@ public class EchoServiceShouldGeneratePartialUsualSettings
   /**
    * Returns the object with the settings used for calls to echoShouldGenerateAsInternal.
    *
-   * @internalApi This method is internal used only. Please do not use directly.
+   * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
    */
   @InternalApi("Internal API. This API is not intended for public consumption.")
   public StreamingCallSettings<EchoRequest, EchoResponse> echoShouldGenerateAsInternalSettings() {
@@ -235,7 +235,7 @@ public class EchoServiceShouldGeneratePartialUsualSettings
     /**
      * Returns the builder for the settings used for calls to chatShouldGenerateAsInternal.
      *
-     * @internalApi This method is internal used only. Please do not use directly.
+     * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
      */
     @InternalApi("Internal API. This API is not intended for public consumption.")
     public UnaryCallSettings.Builder<EchoRequest, EchoResponse>
@@ -246,7 +246,7 @@ public class EchoServiceShouldGeneratePartialUsualSettings
     /**
      * Returns the builder for the settings used for calls to echoShouldGenerateAsInternal.
      *
-     * @internalApi This method is internal used only. Please do not use directly.
+     * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
      */
     @InternalApi("Internal API. This API is not intended for public consumption.")
     public StreamingCallSettings.Builder<EchoRequest, EchoResponse>

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoServiceSelectiveGapicStubSettings.golden

@@ -115,7 +115,7 @@ public class EchoServiceShouldGeneratePartialUsualStubSettings
   /**
    * Returns the object with the settings used for calls to chatShouldGenerateAsInternal.
    *
-   * @internalApi This method is internal used only. Please do not use directly.
+   * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
    */
   @InternalApi("Internal API. This API is not intended for public consumption.")
   public UnaryCallSettings<EchoRequest, EchoResponse> chatShouldGenerateAsInternalSettings() {
@@ -125,7 +125,7 @@ public class EchoServiceShouldGeneratePartialUsualStubSettings
   /**
    * Returns the object with the settings used for calls to echoShouldGenerateAsInternal.
    *
-   * @internalApi This method is internal used only. Please do not use directly.
+   * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
    */
   @InternalApi("Internal API. This API is not intended for public consumption.")
   public StreamingCallSettings<EchoRequest, EchoResponse> echoShouldGenerateAsInternalSettings() {
@@ -352,7 +352,7 @@ public class EchoServiceShouldGeneratePartialUsualStubSettings
     /**
      * Returns the builder for the settings used for calls to chatShouldGenerateAsInternal.
      *
-     * @internalApi This method is internal used only. Please do not use directly.
+     * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
      */
     @InternalApi("Internal API. This API is not intended for public consumption.")
     public UnaryCallSettings.Builder<EchoRequest, EchoResponse>
@@ -363,7 +363,7 @@ public class EchoServiceShouldGeneratePartialUsualStubSettings
     /**
      * Returns the builder for the settings used for calls to echoShouldGenerateAsInternal.
      *
-     * @internalApi This method is internal used only. Please do not use directly.
+     * <p><b>Warning: </b>This method is internal used only. Please do not use directly.
      */
     @InternalApi("Internal API. This API is not intended for public consumption.")
     public StreamingCallSettings.Builder<EchoRequest, EchoResponse>