From 537e33c2cdaf5e79d29f12fe12d372e1f75a525d Mon Sep 17 00:00:00 2001 From: Min Zhu Date: Fri, 6 Jan 2023 14:22:59 -0500 Subject: [PATCH 1/4] fix(ast): update JavaDocComment to support @return. --- .../generator/engine/ast/JavaDocComment.java | 12 ++++++++- .../engine/ast/JavaDocCommentTest.java | 27 +++++++++++++++++++ 2 files changed, 38 insertions(+), 1 deletion(-) diff --git a/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java b/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java index 12300b862c..0e0b904e6d 100644 --- a/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java +++ b/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java @@ -52,6 +52,7 @@ public abstract static class Builder { String throwsDescription = null; String deprecated = null; List paramsList = new ArrayList<>(); + String returnText = null; List componentsList = new ArrayList<>(); // Private accessor, set complete and consolidated comment. abstract Builder setComment(String comment); @@ -69,6 +70,11 @@ public Builder setDeprecated(String deprecatedText) { return this; } + public Builder setReturn(String returnDescription) { + returnText = returnDescription; + return this; + } + public Builder addParam(String name, String description) { paramsList.add(String.format("@param %s %s", name, processParamComment(description))); return this; @@ -130,12 +136,16 @@ public boolean emptyComments() { && Strings.isNullOrEmpty(throwsDescription) && Strings.isNullOrEmpty(deprecated) && paramsList.isEmpty() + && Strings.isNullOrEmpty(returnText) && componentsList.isEmpty(); } public JavaDocComment build() { - // @param, @throws and @deprecated should always get printed at the end. + // @param, @return, @throws and @deprecated should always get printed at the end. componentsList.addAll(paramsList); + if (!Strings.isNullOrEmpty(returnText)) { + componentsList.add(String.format("@return %s", returnText)); + } if (!Strings.isNullOrEmpty(throwsType)) { componentsList.add( String.format("@throws %s %s", throwsType, HtmlEscaper.process(throwsDescription))); diff --git a/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java b/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java index 0d3550971d..1b531804b4 100644 --- a/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java +++ b/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java @@ -178,6 +178,30 @@ public void createJavaDocComment_throwsAndDeprecated() { assertEquals(expected, javaDocComment.comment()); } + @Test + public void createJavaDocComment_paramsAndReturn() { + // No matter how many times or order `setThrows` and `setDeprecated` are called, + // only one @throws and @deprecated will be printed. + String paramName1 = "shelfName"; + String paramDescription1 = "The name of the shelf where books are published to."; + String paramName2 = "shelf"; + String paramDescription2 = "The shelf to create."; + String returnText = "This is the method return text."; + + JavaDocComment javaDocComment = + JavaDocComment.builder() + .addParam(paramName1, paramDescription1) + .addParam(paramName2, paramDescription2) + .setReturn(returnText) + .build(); + String expected = + LineFormatter.lines( + "@param shelfName The name of the shelf where books are published to.\n", + "@param shelf The shelf to create.\n", + "@return This is the method return text."); + assertEquals(expected, javaDocComment.comment()); + } + @Test public void createJavaDocComment_allComponents() { // No matter what order `setThrows`, `setDeprecated` are called, @@ -190,6 +214,7 @@ public void createJavaDocComment_allComponents() { String paramDescription1 = "The name of the shelf where books are published to."; String paramName2 = "shelf"; String paramDescription2 = "The shelf to create."; + String returnText = "This is the method return text."; String paragraph1 = "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:"; @@ -210,6 +235,7 @@ public void createJavaDocComment_allComponents() { .addParagraph(paragraph2) .addOrderedList(orderedList) .addParam(paramName2, paramDescription2) + .setReturn(returnText) .build(); String expected = LineFormatter.lines( @@ -225,6 +251,7 @@ public void createJavaDocComment_allComponents() { "\n", "@param shelfName The name of the shelf where books are published to.\n", "@param shelf The shelf to create.\n", + "@return This is the method return text.\n", "@throws com.google.api.gax.rpc.ApiException if the remote call fails.\n", "@deprecated Use the {@link ArchivedBookName} class instead."); assertEquals(expected, javaDocComment.comment()); From d2b954392e29ff46da02c6a8e2aeee5984831b6a Mon Sep 17 00:00:00 2001 From: Min Zhu Date: Fri, 6 Jan 2023 14:50:40 -0500 Subject: [PATCH 2/4] add @param and @return to method javadoc in generated autoconfig classes. --- .../SpringAutoconfigCommentComposer.java | 18 +++++++++++++++++- .../EchoSpringAutoConfigurationFull.golden | 14 ++++++++++++-- .../EchoSpringAutoConfigurationGrpc.golden | 14 ++++++++++++-- .../EchoSpringAutoConfigurationGrpcRest.golden | 14 ++++++++++++-- 4 files changed, 53 insertions(+), 7 deletions(-) diff --git a/src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java b/src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java index de6ae828b7..17591b7c6b 100644 --- a/src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java +++ b/src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java @@ -41,8 +41,10 @@ public class SpringAutoconfigCommentComposer { + "configuration data files."; public static final String TRANSPORT_CHANNEL_PROVIDER_GENERAL_DESCRIPTION = - "Returns the default channel provider. The default is gRPC and will default to it unless the " + "Provides a default channel provider bean. The default is gRPC and will default to it unless the " + "useRest option is provided to use HTTP transport instead"; + public static final String TRANSPORT_CHANNEL_PROVIDER_RETURN = + "Returns the default channel provider."; public static final String CLIENT_SETTINGS_BEAN_GENERAL_DESCRIPTION = "Provides a %sSettings bean configured to " + "use the default credentials provider (obtained with %sCredentials()) and its default " @@ -54,9 +56,13 @@ public class SpringAutoconfigCommentComposer { "Retry settings are also configured from service-level and method-level properties specified in %s. " + "Method-level properties will take precedence over service-level properties if available, " + "and client library defaults will be used if neither are specified."; + public static final String CLIENT_SETTINGS_BEAN_RETURN_STATEMENT = + "a {@link %sSettings} bean configured with {@link TransportChannelProvider} bean."; public static final String CLIENT_BEAN_GENERAL_DESCRIPTION = "Provides a %sClient bean configured with %sSettings."; + public static final String CLIENT_BEAN_RETURN_STATEMENT = + "a {@link %sClient} bean configured with {@link %sSettings}"; public SpringAutoconfigCommentComposer() {} @@ -88,6 +94,7 @@ public static CommentStatement createTransportChannelProviderComment() { return CommentStatement.withComment( JavaDocComment.builder() .addParagraph(TRANSPORT_CHANNEL_PROVIDER_GENERAL_DESCRIPTION) + .setReturn(TRANSPORT_CHANNEL_PROVIDER_RETURN) .build()); } @@ -104,13 +111,22 @@ public static CommentStatement createSettingsBeanComment( channelProviderName)) .addParagraph( String.format(CLIENT_SETTINGS_BEAN_RETRY_SETTINGS_DESCRIPTION, propertiesClazzName)) + .addParam( + "defaultTransportChannelProvider", + "TransportChannelProvider to use in the settings.") + .setReturn(String.format(CLIENT_SETTINGS_BEAN_RETURN_STATEMENT, serviceName)) .build()); } public static CommentStatement createClientBeanComment(String serviceName) { + String lowerServiceName = CaseFormat.UPPER_CAMEL.to(CaseFormat.LOWER_CAMEL, serviceName); return CommentStatement.withComment( JavaDocComment.builder() .addParagraph(String.format(CLIENT_BEAN_GENERAL_DESCRIPTION, serviceName, serviceName)) + .addParam( + String.format("%sSettings", lowerServiceName), + "settings to configure an instance of client bean.") + .setReturn(String.format(CLIENT_BEAN_RETURN_STATEMENT, serviceName, serviceName)) .build()); } } diff --git a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden index 191f70c066..8f8bacae67 100644 --- a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden +++ b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden @@ -85,8 +85,10 @@ public class EchoSpringAutoConfiguration { } /** - * Returns the default channel provider. The default is gRPC and will default to it unless the + * Provides a default channel provider bean. The default is gRPC and will default to it unless the * useRest option is provided to use HTTP transport instead + * + * @return Returns the default channel provider. */ @Bean @ConditionalOnMissingBean(name = "defaultEchoTransportChannelProvider") @@ -104,6 +106,9 @@ public class EchoSpringAutoConfiguration { *

Retry settings are also configured from service-level and method-level properties specified * in EchoSpringProperties. Method-level properties will take precedence over service-level * properties if available, and client library defaults will be used if neither are specified. + * + * @param defaultTransportChannelProvider TransportChannelProvider to use in the settings. + * @return a {@link EchoSettings} bean configured with {@link TransportChannelProvider} bean. */ @Bean @ConditionalOnMissingBean @@ -302,7 +307,12 @@ public class EchoSpringAutoConfiguration { return clientSettingsBuilder.build(); } - /** Provides a EchoClient bean configured with EchoSettings. */ + /** + * Provides a EchoClient bean configured with EchoSettings. + * + * @param echoSettings settings to configure an instance of client bean. + * @return a {@link EchoClient} bean configured with {@link EchoSettings} + */ @Bean @ConditionalOnMissingBean public EchoClient echoClient(EchoSettings echoSettings) throws IOException { diff --git a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpc.golden b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpc.golden index dd0b27782a..a2e6ad4746 100644 --- a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpc.golden +++ b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpc.golden @@ -65,8 +65,10 @@ public class EchoSpringAutoConfiguration { } /** - * Returns the default channel provider. The default is gRPC and will default to it unless the + * Provides a default channel provider bean. The default is gRPC and will default to it unless the * useRest option is provided to use HTTP transport instead + * + * @return Returns the default channel provider. */ @Bean @ConditionalOnMissingBean(name = "defaultEchoTransportChannelProvider") @@ -84,6 +86,9 @@ public class EchoSpringAutoConfiguration { *

Retry settings are also configured from service-level and method-level properties specified * in EchoSpringProperties. Method-level properties will take precedence over service-level * properties if available, and client library defaults will be used if neither are specified. + * + * @param defaultTransportChannelProvider TransportChannelProvider to use in the settings. + * @return a {@link EchoSettings} bean configured with {@link TransportChannelProvider} bean. */ @Bean @ConditionalOnMissingBean @@ -282,7 +287,12 @@ public class EchoSpringAutoConfiguration { return clientSettingsBuilder.build(); } - /** Provides a EchoClient bean configured with EchoSettings. */ + /** + * Provides a EchoClient bean configured with EchoSettings. + * + * @param echoSettings settings to configure an instance of client bean. + * @return a {@link EchoClient} bean configured with {@link EchoSettings} + */ @Bean @ConditionalOnMissingBean public EchoClient echoClient(EchoSettings echoSettings) throws IOException { diff --git a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpcRest.golden b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpcRest.golden index ab456647a1..166b04a106 100644 --- a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpcRest.golden +++ b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpcRest.golden @@ -66,8 +66,10 @@ public class EchoSpringAutoConfiguration { } /** - * Returns the default channel provider. The default is gRPC and will default to it unless the + * Provides a default channel provider bean. The default is gRPC and will default to it unless the * useRest option is provided to use HTTP transport instead + * + * @return Returns the default channel provider. */ @Bean @ConditionalOnMissingBean(name = "defaultEchoTransportChannelProvider") @@ -85,6 +87,9 @@ public class EchoSpringAutoConfiguration { *

Retry settings are also configured from service-level and method-level properties specified * in EchoSpringProperties. Method-level properties will take precedence over service-level * properties if available, and client library defaults will be used if neither are specified. + * + * @param defaultTransportChannelProvider TransportChannelProvider to use in the settings. + * @return a {@link EchoSettings} bean configured with {@link TransportChannelProvider} bean. */ @Bean @ConditionalOnMissingBean @@ -290,7 +295,12 @@ public class EchoSpringAutoConfiguration { return clientSettingsBuilder.build(); } - /** Provides a EchoClient bean configured with EchoSettings. */ + /** + * Provides a EchoClient bean configured with EchoSettings. + * + * @param echoSettings settings to configure an instance of client bean. + * @return a {@link EchoClient} bean configured with {@link EchoSettings} + */ @Bean @ConditionalOnMissingBean public EchoClient echoClient(EchoSettings echoSettings) throws IOException { From de04996739ade37b8a0bd370f4fb24d41a843c4e Mon Sep 17 00:00:00 2001 From: Min Zhu Date: Fri, 6 Jan 2023 15:11:22 -0500 Subject: [PATCH 3/4] minor changes in comment. --- .../composer/comment/SpringAutoconfigCommentComposer.java | 4 ++-- .../composer/goldens/EchoSpringAutoConfigurationFull.golden | 6 +++--- .../composer/goldens/EchoSpringAutoConfigurationGrpc.golden | 6 +++--- .../goldens/EchoSpringAutoConfigurationGrpcRest.golden | 6 +++--- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java b/src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java index 17591b7c6b..1c1cc40ac6 100644 --- a/src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java +++ b/src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java @@ -41,10 +41,10 @@ public class SpringAutoconfigCommentComposer { + "configuration data files."; public static final String TRANSPORT_CHANNEL_PROVIDER_GENERAL_DESCRIPTION = - "Provides a default channel provider bean. The default is gRPC and will default to it unless the " + "Provides a default transport channel provider bean. The default is gRPC and will default to it unless the " + "useRest option is provided to use HTTP transport instead"; public static final String TRANSPORT_CHANNEL_PROVIDER_RETURN = - "Returns the default channel provider."; + "a default transport channel provider."; public static final String CLIENT_SETTINGS_BEAN_GENERAL_DESCRIPTION = "Provides a %sSettings bean configured to " + "use the default credentials provider (obtained with %sCredentials()) and its default " diff --git a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden index 8f8bacae67..3b3a177243 100644 --- a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden +++ b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden @@ -85,10 +85,10 @@ public class EchoSpringAutoConfiguration { } /** - * Provides a default channel provider bean. The default is gRPC and will default to it unless the - * useRest option is provided to use HTTP transport instead + * Provides a default transport channel provider bean. The default is gRPC and will default to it + * unless the useRest option is provided to use HTTP transport instead * - * @return Returns the default channel provider. + * @return a default transport channel provider. */ @Bean @ConditionalOnMissingBean(name = "defaultEchoTransportChannelProvider") diff --git a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpc.golden b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpc.golden index a2e6ad4746..bc3ab4007a 100644 --- a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpc.golden +++ b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpc.golden @@ -65,10 +65,10 @@ public class EchoSpringAutoConfiguration { } /** - * Provides a default channel provider bean. The default is gRPC and will default to it unless the - * useRest option is provided to use HTTP transport instead + * Provides a default transport channel provider bean. The default is gRPC and will default to it + * unless the useRest option is provided to use HTTP transport instead * - * @return Returns the default channel provider. + * @return a default transport channel provider. */ @Bean @ConditionalOnMissingBean(name = "defaultEchoTransportChannelProvider") diff --git a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpcRest.golden b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpcRest.golden index 166b04a106..3c67d172c0 100644 --- a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpcRest.golden +++ b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationGrpcRest.golden @@ -66,10 +66,10 @@ public class EchoSpringAutoConfiguration { } /** - * Provides a default channel provider bean. The default is gRPC and will default to it unless the - * useRest option is provided to use HTTP transport instead + * Provides a default transport channel provider bean. The default is gRPC and will default to it + * unless the useRest option is provided to use HTTP transport instead * - * @return Returns the default channel provider. + * @return a default transport channel provider. */ @Bean @ConditionalOnMissingBean(name = "defaultEchoTransportChannelProvider") From 3cc6b0df13d205f1940c969f299911948f74249a Mon Sep 17 00:00:00 2001 From: Min Zhu Date: Mon, 9 Jan 2023 09:22:04 -0500 Subject: [PATCH 4/4] remove irrelevant comments. Co-authored-by: Emily Wang --- .../com/google/api/generator/engine/ast/JavaDocCommentTest.java | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java b/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java index 1b531804b4..1fef68649f 100644 --- a/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java +++ b/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java @@ -180,8 +180,6 @@ public void createJavaDocComment_throwsAndDeprecated() { @Test public void createJavaDocComment_paramsAndReturn() { - // No matter how many times or order `setThrows` and `setDeprecated` are called, - // only one @throws and @deprecated will be printed. String paramName1 = "shelfName"; String paramDescription1 = "The name of the shelf where books are published to."; String paramName2 = "shelf";