fix(java): add javadoc to all methods APIC-538 (#704)

algolia · Jun 16, 2022 · 90e531a · 90e531a
1 parent 05fd13f
commit 90e531a
Show file tree

Hide file tree

Showing 7 changed files with 59 additions and 24 deletions.
diff --git a/templates/java/api_javadoc.mustache b/templates/java/api_javadoc.mustache
@@ -0,0 +1,11 @@
+  * @throws AlgoliaRuntimeException If it fails to process the API call
+  {{#isDeprecated}}
+  * @deprecated
+  {{/isDeprecated}}
+  {{#externalDocs}}
+  * @see <a href="{{url}}">{{{summary}}} Documentation</a> ({{{description}}})
+  {{/externalDocs}}
+  */
+  {{#isDeprecated}}
+  @Deprecated
+  {{/isDeprecated}}
diff --git a/templates/java/libraries/okhttp-gson/api.mustache b/templates/java/libraries/okhttp-gson/api.mustache
@@ -134,17 +134,17 @@ public class {{classname}} extends ApiClient {
 
     {{#operation}}
     /**
-     * {{&notes}}{{#allParams}}
-     * @param {{paramName}} {{&description}}{{#required}} (required){{/required}}{{^required}} (optional{{^isContainer}}{{#defaultValue}}, default to {{.}}{{/defaultValue}}{{/isContainer}}){{/required}}{{/allParams}}{{#returnType}}
+     * {{{notes}}}{{#allParams}}
+     * @param {{paramName}} {{{description}}}{{#required}} (required){{/required}}{{^required}} (optional{{^isContainer}}{{#defaultValue}}, default to {{.}}{{/defaultValue}}{{/isContainer}}){{/required}}{{/allParams}}{{#returnType}}
      * @param requestOptions The requestOptions to send along with the query, they will be merged with the transporter requestOptions.
      * @return {{.}}{{/returnType}}
      * @throws AlgoliaRuntimeException If fail to call the API, e.g. server error or cannot deserialize the response body
      {{#isDeprecated}}
      * @deprecated
      {{/isDeprecated}}
         {{#externalDocs}}
-     * {{&description}}
-     * @see <a href="{{url}}">{{&summary}} Documentation</a>
+     * {{{description}}}
+     * @see <a href="{{url}}">{{{summary}}} Documentation</a>
         {{/externalDocs}}
      */
     {{#isDeprecated}}
@@ -155,19 +155,35 @@ public class {{classname}} extends ApiClient {
     }
 
   {{! This case only sets `requestOptions` as optional }}
+  /**
+    * {{{notes}}}{{#allParams}}
+    * @param {{paramName}} {{{description}}}{{#required}} (required){{/required}}{{^required}} (optional{{^isContainer}}{{#defaultValue}}, default to {{.}}{{/defaultValue}}{{/isContainer}}){{/required}}{{/allParams}}{{#returnType}}
+    * @return {{.}}{{/returnType}}
+    {{> api_javadoc}}
   public {{#returnType}}{{{.}}} {{/returnType}}{{^returnType}}void {{/returnType}}{{operationId}}({{#allParams}}{{{dataType}}} {{paramName}}{{^-last}}, {{/-last}}{{/allParams}}) throws AlgoliaRuntimeException {
     {{#returnType}}return {{/returnType}}this.{{operationId}}({{#allParams}}{{paramName}}, {{/allParams}}null);
   }
 
   {{! This case sets `requiredParams` + `requestOptions` }}
   {{#optionalParams.0}}
+  /**
+    * {{{notes}}}{{#requiredParams}}
+    * @param {{paramName}} {{{description}}} (required){{/requiredParams}}{{#returnType}}
+    * @param requestOptions The requestOptions to send along with the query, they will be merged with the transporter requestOptions.
+    * @return {{.}}{{/returnType}}
+   {{> api_javadoc}}
   public {{#returnType}}{{{.}}} {{/returnType}}{{^returnType}}void {{/returnType}}{{operationId}}({{#requiredParams}}{{{dataType}}} {{paramName}}, {{/requiredParams}}RequestOptions requestOptions) throws AlgoliaRuntimeException {
     {{#returnType}}return {{/returnType}}this.{{operationId}}({{#requiredParams}}{{paramName}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#requiredParams.0}},{{/requiredParams.0}}{{#optionalParams}}null{{^-last}},{{/-last}}{{/optionalParams}}, requestOptions);
   }
   {{/optionalParams.0}}
 
   {{! This case only sets `requiredParams` }}
   {{#optionalParams.0}}
+  /**
+    * {{{notes}}}{{#requiredParams}}
+    * @param {{paramName}} {{{description}}} (required){{/requiredParams}}{{#returnType}}
+    * @return {{.}}{{/returnType}}
+   {{> api_javadoc}}
   public {{#returnType}}{{{.}}} {{/returnType}}{{^returnType}}void {{/returnType}}{{operationId}}({{#requiredParams}}{{{dataType}}} {{paramName}}{{^-last}}, {{/-last}}{{/requiredParams}}) throws AlgoliaRuntimeException {
     {{#returnType}}return {{/returnType}}this.{{operationId}}({{#requiredParams}}{{paramName}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#requiredParams.0}},{{/requiredParams.0}}{{#optionalParams}}null{{^-last}},{{/-last}}{{/optionalParams}}, null);
   }
@@ -178,19 +194,8 @@ public class {{classname}} extends ApiClient {
   * {{notes}}{{#allParams}}
   * @param {{paramName}} {{{description}}}{{#required}} (required){{/required}}{{^required}} (optional{{^isContainer}}{{#defaultValue}}, default to {{.}}{{/defaultValue}}{{/isContainer}}){{/required}}{{/allParams}}
   * @param requestOptions The requestOptions to send along with the query, they will be merged with the transporter requestOptions.
-  * @return The awaitable future
-  * @throws AlgoliaRuntimeException If fail to process the API call, e.g. serializing the request body object
-  {{#isDeprecated}}
-  * @deprecated
-  {{/isDeprecated}}
-  {{#externalDocs}}
-  * {{&description}}
-  * @see <a href="{{url}}">{{&summary}} Documentation</a>
-  {{/externalDocs}}
-  */
-  {{#isDeprecated}}
-  @Deprecated
-  {{/isDeprecated}}
+  * @return CompletableFuture<{{{returnType}}}> The awaitable future
+  {{> api_javadoc}}
   public CompletableFuture<{{{returnType}}}> {{operationId}}Async({{#allParams}}{{{dataType}}} {{paramName}}, {{/allParams}}RequestOptions requestOptions) throws AlgoliaRuntimeException {
     {{#allParams}}{{#required}}
     if ({{paramName}} == null) {
@@ -234,19 +239,38 @@ public class {{classname}} extends ApiClient {
   }
 
   {{! This case only sets `requestOptions` as optional }}
+  /**
+  * (asynchronously)
+  * {{notes}}{{#allParams}}
+  * @param {{paramName}} {{{description}}}{{#required}} (required){{/required}}{{^required}} (optional{{^isContainer}}{{#defaultValue}}, default to {{.}}{{/defaultValue}}{{/isContainer}}){{/required}}{{/allParams}}
+  * @return CompletableFuture<{{{returnType}}}> The awaitable future
+  {{> api_javadoc}}
   public CompletableFuture<{{{returnType}}}> {{operationId}}Async({{#allParams}}{{{dataType}}} {{paramName}}{{^-last}}, {{/-last}}{{/allParams}}) throws AlgoliaRuntimeException {
     {{#returnType}}return {{/returnType}}this.{{operationId}}Async({{#allParams}}{{paramName}}, {{/allParams}}null);
   }
 
   {{! This case sets `requiredParams` + `requestOptions` }}
   {{#optionalParams.0}}
+  /**
+  * (asynchronously)
+  * {{notes}}{{#requiredParams}}
+  * @param {{paramName}} {{{description}}} (required){{/requiredParams}}
+  * @param requestOptions The requestOptions to send along with the query, they will be merged with the transporter requestOptions.
+  * @return CompletableFuture<{{{returnType}}}> The awaitable future
+  {{> api_javadoc}}
   public CompletableFuture<{{{returnType}}}> {{operationId}}Async({{#requiredParams}}{{{dataType}}} {{paramName}}, {{/requiredParams}}RequestOptions requestOptions) throws AlgoliaRuntimeException {
     {{#returnType}}return {{/returnType}}this.{{operationId}}Async({{#requiredParams}}{{paramName}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#requiredParams.0}},{{/requiredParams.0}}{{#optionalParams}}null{{^-last}},{{/-last}}{{/optionalParams}}, requestOptions);
   }
   {{/optionalParams.0}}
 
   {{! This case only sets `requiredParams` }}
   {{#optionalParams.0}}
+  /**
+  * (asynchronously)
+  * {{notes}}{{#requiredParams}}
+  * @param {{paramName}} {{{description}}} (required){{/requiredParams}}
+  * @return CompletableFuture<{{{returnType}}}> The awaitable future
+  {{> api_javadoc}}
   public CompletableFuture<{{{returnType}}}> {{operationId}}Async({{#requiredParams}}{{{dataType}}} {{paramName}}{{^-last}}, {{/-last}}{{/requiredParams}}) throws AlgoliaRuntimeException {
     {{#returnType}}return {{/returnType}}this.{{operationId}}Async({{#requiredParams}}{{paramName}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#requiredParams.0}},{{/requiredParams.0}}{{#optionalParams}}null{{^-last}},{{/-last}}{{/optionalParams}}, null);
   }

diff --git a/templates/java/modelEnum.mustache b/templates/java/modelEnum.mustache
@@ -7,7 +7,7 @@ import com.google.gson.stream.JsonWriter;
 {{/gson}}
 
 /**
- * {{&description}}{{^description}}Gets or Sets {{{name}}}{{/description}}
+ * {{{description}}}{{^description}}Gets or Sets {{{name}}}{{/description}}
  */
 {{#gson}}
 @JsonAdapter({{{datatypeWithEnum}}}{{^datatypeWithEnum}}{{{classname}}}{{/datatypeWithEnum}}.Adapter.class)

diff --git a/templates/java/modelInnerEnum.mustache b/templates/java/modelInnerEnum.mustache
@@ -1,5 +1,5 @@
   /**
-   * {{&description}}{{^description}}Gets or Sets {{{name}}}{{/description}}
+   * {{{description}}}{{^description}}Gets or Sets {{{name}}}{{/description}}
    */
 {{#gson}}
   @JsonAdapter({{{datatypeWithEnum}}}{{^datatypeWithEnum}}{{classname}}{{/datatypeWithEnum}}.Adapter.class)

diff --git a/templates/java/pojo.mustache b/templates/java/pojo.mustache
@@ -1,5 +1,5 @@
 /**
- * {{&description}}{{^description}}{{classname}}{{/description}}{{#isDeprecated}}
+ * {{{description}}}{{^description}}{{classname}}{{/description}}{{#isDeprecated}}
  * @deprecated{{/isDeprecated}}
  */{{#isDeprecated}}
 @Deprecated{{/isDeprecated}}

diff --git a/templates/javascript/api/operation/jsdoc.mustache b/templates/javascript/api/operation/jsdoc.mustache
@@ -1,9 +1,9 @@
 /**
 {{#notes}}
- * {{&notes}}
+ * {{{notes}}}
 {{/notes}}
 {{#summary}}
- * @summary {{&summary}}
+ * @summary {{{summary}}}
 {{/summary}}
 {{#vendorExtensions}}
   {{#x-create-wrapping-object}}

diff --git a/templates/php/ObjectSerializer.mustache b/templates/php/ObjectSerializer.mustache
@@ -58,7 +58,7 @@ class ObjectSerializer
                 foreach ($data::openAPITypes() as $property => $openAPIType) {
                     $getter = $data::getters()[$property];
                     $value = $data->$getter();
-                    if ($value !== null && !in_array($openAPIType, [{{&primitives}}], true)) {
+                    if ($value !== null && !in_array($openAPIType, [{{{primitives}}}], true)) {
                         $callable = [$openAPIType, 'getAllowableEnumValues'];
                         if (is_callable($callable)) {
                             /** array $callable */
@@ -305,7 +305,7 @@ class ObjectSerializer
         }
 
         /** @psalm-suppress ParadoxicalCondition */
-        if (in_array($class, [{{&primitives}}], true)) {
+        if (in_array($class, [{{{primitives}}}], true)) {
             settype($data, $class);
             return $data;
         }