From bd54d22753d8d269452bf1742f00aedf41c2a57b Mon Sep 17 00:00:00 2001 From: Xiaofei Cao <92354331+XiaofeiCao@users.noreply.github.com> Date: Tue, 10 Dec 2024 11:07:58 +0800 Subject: [PATCH] http-client-java, fix client accessor method parameter description (#5313) fix autorest CI: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=4395471&view=logs&j=ca395085-040a-526b-2ce8-bdc85f692774&t=0750e130-1e9a-5b8a-35b2-9986f25ac898 Similar to client method parameter, assign a default parameter description if not exists. --- .../core/template/ClientMethodTemplateBase.java | 12 ++---------- .../core/template/ServiceAsyncClientTemplate.java | 3 ++- .../core/template/ServiceClientTemplate.java | 3 ++- .../client/generator/core/util/MethodUtil.java | 15 +++++++++++++++ .../ClientInitializationAsyncClient.java | 2 +- .../ClientInitializationClient.java | 2 +- .../ClientInitializationClientImpl.java | 2 +- 7 files changed, 24 insertions(+), 15 deletions(-) diff --git a/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ClientMethodTemplateBase.java b/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ClientMethodTemplateBase.java index a64f72c7db..ecd24a326e 100644 --- a/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ClientMethodTemplateBase.java +++ b/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ClientMethodTemplateBase.java @@ -9,7 +9,6 @@ import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClassType; import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientEnumValue; import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientMethod; -import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientMethodParameter; import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientModel; import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientModelProperty; import com.microsoft.typespec.http.client.generator.core.model.clientmodel.EnumType; @@ -25,6 +24,7 @@ import com.microsoft.typespec.http.client.generator.core.model.javamodel.JavaType; import com.microsoft.typespec.http.client.generator.core.util.ClientModelUtil; import com.microsoft.typespec.http.client.generator.core.util.CodeNamer; +import com.microsoft.typespec.http.client.generator.core.util.MethodUtil; import java.util.HashSet; import java.util.LinkedHashMap; import java.util.List; @@ -136,7 +136,7 @@ protected static void generateProtocolMethodJavadoc(ClientMethod clientMethod, J } clientMethod.getParameters() - .forEach(p -> commentBlock.param(p.getName(), methodParameterDescriptionOrDefault(p))); + .forEach(p -> commentBlock.param(p.getName(), MethodUtil.methodParameterDescriptionOrDefault(p))); if (clientMethod.getProxyMethod() != null) { generateJavadocExceptions(clientMethod, commentBlock, false); } @@ -353,14 +353,6 @@ private static String parameterDescriptionOrDefault(ProxyMethodParameter paramet return description; } - private static String methodParameterDescriptionOrDefault(ClientMethodParameter p) { - String doc = p.getDescription(); - if (CoreUtils.isNullOrEmpty(doc)) { - doc = String.format("The %1$s parameter", p.getName()); - } - return doc; - } - private static String appendOptionalOrRequiredAttribute(boolean isRequired, boolean isRequiredForCreate, boolean isRootSchema) { if (isRootSchema) { diff --git a/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ServiceAsyncClientTemplate.java b/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ServiceAsyncClientTemplate.java index f705fba329..ef10d3853f 100644 --- a/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ServiceAsyncClientTemplate.java +++ b/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ServiceAsyncClientTemplate.java @@ -23,6 +23,7 @@ import com.microsoft.typespec.http.client.generator.core.model.javamodel.JavaFile; import com.microsoft.typespec.http.client.generator.core.model.javamodel.JavaVisibility; import com.microsoft.typespec.http.client.generator.core.util.ClientModelUtil; +import com.microsoft.typespec.http.client.generator.core.util.MethodUtil; import com.microsoft.typespec.http.client.generator.core.util.ModelNamer; import com.microsoft.typespec.http.client.generator.core.util.TemplateUtil; import java.util.HashSet; @@ -241,7 +242,7 @@ static void writeSubClientAccessors(ServiceClient serviceClient, JavaClass class classBlock.javadocComment(comment -> { comment.description("Gets an instance of " + subClientClassName + " class."); for (ClientMethodParameter property : methodParameters) { - comment.param(property.getName(), property.getDescription()); + comment.param(property.getName(), MethodUtil.methodParameterDescriptionOrDefault(property)); } comment.methodReturns("an instance of " + subClientClassName + "class"); }); diff --git a/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ServiceClientTemplate.java b/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ServiceClientTemplate.java index 0cfc5529e9..7a2895d282 100644 --- a/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ServiceClientTemplate.java +++ b/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ServiceClientTemplate.java @@ -19,6 +19,7 @@ import com.microsoft.typespec.http.client.generator.core.template.prototype.MethodTemplate; import com.microsoft.typespec.http.client.generator.core.util.ClientModelUtil; import com.microsoft.typespec.http.client.generator.core.util.CodeNamer; +import com.microsoft.typespec.http.client.generator.core.util.MethodUtil; import com.microsoft.typespec.http.client.generator.core.util.ModelNamer; import com.microsoft.typespec.http.client.generator.core.util.TemplateUtil; import java.util.ArrayList; @@ -386,7 +387,7 @@ private static void writeClientAccessorMethods(JavaClass classBlock, classBlock.javadocComment(comment -> { comment.description("Gets an instance of " + subClientName + " class."); for (ClientMethodParameter parameter : methodParameters) { - comment.param(parameter.getName(), parameter.getDescription()); + comment.param(parameter.getName(), MethodUtil.methodParameterDescriptionOrDefault(parameter)); } comment.methodReturns("an instance of " + subClientName + "class"); }); diff --git a/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/util/MethodUtil.java b/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/util/MethodUtil.java index 8a9e82b252..a969e90168 100644 --- a/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/util/MethodUtil.java +++ b/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/util/MethodUtil.java @@ -23,6 +23,7 @@ import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClassType; import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientEnumValue; import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientMethod; +import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientMethodParameter; import com.microsoft.typespec.http.client.generator.core.model.clientmodel.EnumType; import com.microsoft.typespec.http.client.generator.core.model.clientmodel.IType; import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ProxyMethod; @@ -326,6 +327,20 @@ public static Optional serializedNameOfMaxPageSizeParameter(ProxyMethod .findFirst(); } + /** + * Gets method parameter description, or a default description if not exists. + * + * @param p the client method parameter + * @return the method parameter description + */ + public static String methodParameterDescriptionOrDefault(ClientMethodParameter p) { + String doc = p.getDescription(); + if (CoreUtils.isNullOrEmpty(doc)) { + doc = String.format("The %1$s parameter", p.getName()); + } + return doc; + } + /** * * @param request the input request diff --git a/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/ClientInitializationAsyncClient.java b/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/ClientInitializationAsyncClient.java index 051373763a..900212ff45 100644 --- a/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/ClientInitializationAsyncClient.java +++ b/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/ClientInitializationAsyncClient.java @@ -29,7 +29,7 @@ public final class ClientInitializationAsyncClient { /** * Gets an instance of SubAsyncClient class. * - * @param name + * @param name The name parameter. * @return an instance of SubAsyncClientclass. */ public SubAsyncClient getSubAsyncClient(String name) { diff --git a/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/ClientInitializationClient.java b/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/ClientInitializationClient.java index 02ac901b5e..705ea2577b 100644 --- a/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/ClientInitializationClient.java +++ b/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/ClientInitializationClient.java @@ -29,7 +29,7 @@ public final class ClientInitializationClient { /** * Gets an instance of SubClient class. * - * @param name + * @param name The name parameter. * @return an instance of SubClientclass. */ public SubClient getSubClient(String name) { diff --git a/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/implementation/ClientInitializationClientImpl.java b/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/implementation/ClientInitializationClientImpl.java index 3bd2efbe5c..52de55218f 100644 --- a/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/implementation/ClientInitializationClientImpl.java +++ b/packages/http-client-java/generator/http-client-generator-test/src/main/java/tsptest/clientinitialization/implementation/ClientInitializationClientImpl.java @@ -95,7 +95,7 @@ public ClientInitializationClientImpl(HttpPipeline httpPipeline, SerializerAdapt /** * Gets an instance of SubClientImpl class. * - * @param name + * @param name The name parameter. * @return an instance of SubClientImplclass. */ public SubClientImpl getSubClient(String name) {