docs(clients): add ACL section to code doc (#2576)

algolia · Jan 29, 2024 · b3d6112 · b3d6112
1 parent 7a60a98
commit b3d6112
Show file tree

Hide file tree

Showing 14 changed files with 117 additions and 61 deletions.
diff --git a/clients/algoliasearch-client-java/algoliasearch/build.gradle b/clients/algoliasearch-client-java/algoliasearch/build.gradle
@@ -27,3 +27,7 @@ tasks.withType(JavaCompile) {
     options.encoding = 'UTF-8'
     options.compilerArgs += ['-Xlint:deprecation', '-Xlint:unchecked', '-Xlint:cast', '-Xlint:rawtypes']
 }
+
+javadoc {
+  options.encoding = 'UTF-8'
+}
diff --git a/templates/csharp/api.mustache b/templates/csharp/api.mustache
@@ -25,11 +25,8 @@ namespace Algolia.Search.Clients;
   {
       {{#operation}}
       /// <summary>
-      /// {{{summary}}}
-      /// </summary>
-      /// <remarks>
       /// {{{notes}}}
-      /// </remarks>
+      /// </summary>
       {{#allParams}}
       /// <param name="{{paramName}}">{{{description}}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}{{#isDeprecated}} (deprecated){{/isDeprecated}}</param>
       {{/allParams}}
@@ -106,8 +103,14 @@ namespace Algolia.Search.Clients;
       {{#supportsAsync}}
 
       /// <summary>
-      /// {{{summary}}} {{notes}}
-      /// </summary>
+      /// {{{notes}}}
+      /// </summary>{{#vendorExtensions}}{{#x-acl.0}}
+      ///
+      /// Required API Key ACLs:{{/x-acl.0}}
+      {{#x-acl}}
+      ///   - {{.}}
+      {{/x-acl}}
+      {{/vendorExtensions}}
       {{#allParams}}
       /// <param name="{{paramName}}">{{description}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}{{#isDeprecated}} (deprecated){{/isDeprecated}}</param>
       {{/allParams}}

diff --git a/templates/dart/api.mustache b/templates/dart/api.mustache
@@ -75,8 +75,13 @@ final class {{classname}} implements ApiClient {
   }
   {{#operation}}
 
-  /// {{{summary}}}{{^summary}}{{{nickname}}}{{/summary}}
-  /// {{{notes}}}
+  /// {{{notes}}}{{#vendorExtensions}}{{#x-acl.0}}
+  ///
+  /// Required API Key ACLs:{{/x-acl.0}}
+  {{#x-acl}}
+  ///   - {{.}}
+  {{/x-acl}}
+  {{/vendorExtensions}}
   ///
   /// Parameters:
   {{#allParams}}
@@ -203,4 +208,4 @@ final class {{classname}} implements ApiClient {
   @override
   void dispose() => _retryStrategy.dispose(); 
 }
-{{/operations}}
+{{/operations}}
diff --git a/templates/go/api.mustache b/templates/go/api.mustache
@@ -104,11 +104,19 @@ func (r {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/s
 {{/allParams}}
 {{/hasParams}}
 /*
-{{operationId}} {{{summary}}} Wraps {{nickname}}WithContext using context.Background.{{^summary}}Method for {{operationId}}{{/summary}}
+{{operationId}} Wraps {{nickname}}WithContext using context.Background.
 {{#notes}}
 
 {{{unescapedNotes}}}
 {{/notes}}
+{{#vendorExtensions}}
+{{#x-acl.0}}
+
+Required API Key ACLs:{{/x-acl.0}}
+{{#x-acl}}
+  - {{.}}
+{{/x-acl}}
+{{/vendorExtensions}}
 
 Request can be constructed by NewApi{{operationId}}Request with parameters below.
  {{#allParams}}
@@ -128,7 +136,7 @@ func (c *APIClient) {{nickname}}({{#hasParams}}r {{#structPrefix}}{{&classname}}
 }
 
 /*
-{{operationId}} {{{summary}}}{{^summary}}Method for {{operationId}}{{/summary}}
+{{operationId}}
 {{#notes}}
 
 {{{unescapedNotes}}}

diff --git a/templates/java/api.mustache b/templates/java/api.mustache
@@ -162,7 +162,7 @@ public class {{classname}} extends ApiClient {
 
   /**
   * (asynchronously)
-  * {{notes}}{{#allParams}}
+  * {{{notes}}}{{#allParams}}
   * @param {{paramName}} {{{description}}}{{#required}} (required){{/required}}{{^required}} (optional{{^isContainer}}{{#defaultValue}}, default to {{.}}{{/defaultValue}}{{/isContainer}}){{/required}}{{/allParams}}{{#vendorExtensions}}{{#x-is-generic}}
   * @param innerType The class held by the index, could be your custom class or {@link Object}.{{/x-is-generic}}{{/vendorExtensions}}
   * @param requestOptions The requestOptions to send along with the query, they will be merged with the transporter requestOptions.
@@ -186,7 +186,7 @@ public class {{classname}} extends ApiClient {
   {{! This case only sets `requestOptions` as optional }}
   /**
   * (asynchronously)
-  * {{notes}}{{#allParams}}
+  * {{{notes}}}{{#allParams}}
   * @param {{paramName}} {{{description}}}{{#required}} (required){{/required}}{{^required}} (optional{{^isContainer}}{{#defaultValue}}, default to {{.}}{{/defaultValue}}{{/isContainer}}){{/required}}{{/allParams}}{{#vendorExtensions}}{{#x-is-generic}}
   * @param innerType The class held by the index, could be your custom class or {@link Object}.{{/x-is-generic}}{{/vendorExtensions}}
   {{> api_javadoc}}
@@ -198,7 +198,7 @@ public class {{classname}} extends ApiClient {
   {{#optionalParams.0}}
   /**
   * (asynchronously)
-  * {{notes}}{{#requiredParams}}
+  * {{{notes}}}{{#requiredParams}}
   * @param {{paramName}} {{{description}}} (required){{/requiredParams}}{{#vendorExtensions}}{{#x-is-generic}}
   * @param innerType The class held by the index, could be your custom class or {@link Object}.{{/x-is-generic}}{{/vendorExtensions}}
   * @param requestOptions The requestOptions to send along with the query, they will be merged with the transporter requestOptions.
@@ -212,7 +212,7 @@ public class {{classname}} extends ApiClient {
   {{#optionalParams.0}}
   /**
   * (asynchronously)
-  * {{notes}}{{#requiredParams}}
+  * {{{notes}}}{{#requiredParams}}
   * @param {{paramName}} {{{description}}} (required){{/requiredParams}}{{#vendorExtensions}}{{#x-is-generic}}
   * @param innerType The class held by the index, could be your custom class or {@link Object}.{{/x-is-generic}}{{/vendorExtensions}}
   {{> api_javadoc}}

diff --git a/templates/java/api_javadoc.mustache b/templates/java/api_javadoc.mustache
@@ -2,10 +2,7 @@
   {{#isDeprecated}}
   * @deprecated
   {{/isDeprecated}}
-  {{#externalDocs}}
-  * @see <a href="{{url}}">{{{summary}}} Documentation</a> ({{{description}}})
-  {{/externalDocs}}
   */
   {{#isDeprecated}}
   @Deprecated
-  {{/isDeprecated}}
+  {{/isDeprecated}}
diff --git a/templates/java/oneof_interface.mustache b/templates/java/oneof_interface.mustache
@@ -24,7 +24,7 @@ public interface {{classname}}{{#vendorExtensions.x-has-child-generic}}<T>{{/ven
     {{#composedSchemas.oneOf}}
     {{^isModel}}
     {{^isEnumRef}}
-    /** {{classname}} as {{{datatypeWithEnum}}} wrapper. */
+    // {{classname}} as {{{datatypeWithEnum}}} wrapper.
     static {{classname}} of{{#isArray}}{{#lambda.type-to-name}}{{{datatypeWithEnum}}}{{/lambda.type-to-name}}{{/isArray}}({{{datatypeWithEnum}}} value) {
         return new {{#lambda.type-to-name}}{{{datatypeWithEnum}}}{{/lambda.type-to-name}}Wrapper(value);
     }
@@ -37,7 +37,7 @@ public interface {{classname}}{{#vendorExtensions.x-has-child-generic}}<T>{{/ven
     {{#composedSchemas.oneOf}}
     {{^isModel}}
     {{^isEnumRef}}
-    /** {{classname}} as {{{datatypeWithEnum}}} wrapper. */
+    // {{classname}} as {{{datatypeWithEnum}}} wrapper.
     static {{classname}} of({{{datatypeWithEnum}}} value) {
         return new {{#lambda.type-to-name}}{{{datatypeWithEnum}}}{{/lambda.type-to-name}}Wrapper(value);
     }
@@ -49,7 +49,7 @@ public interface {{classname}}{{#vendorExtensions.x-has-child-generic}}<T>{{/ven
     {{#composedSchemas.oneOf}}
     {{^isModel}}
     {{^isEnumRef}}
-    /** {{classname}} as {{{datatypeWithEnum}}} wrapper. */
+    // {{classname}} as {{{datatypeWithEnum}}} wrapper.
     @JsonSerialize(using = {{#lambda.type-to-name}}{{{datatypeWithEnum}}}{{/lambda.type-to-name}}Wrapper.Serializer.class)
     class {{#lambda.type-to-name}}{{{datatypeWithEnum}}}{{/lambda.type-to-name}}Wrapper implements {{classname}}{
         private final {{{datatypeWithEnum}}} value;
@@ -125,4 +125,4 @@ public interface {{classname}}{{#vendorExtensions.x-has-child-generic}}<T>{{/ven
         {{/isNullable}}
         }
     }
-}
+}
diff --git a/templates/javascript/clients/client/api/operation/jsdoc.mustache b/templates/javascript/clients/client/api/operation/jsdoc.mustache
@@ -1,11 +1,11 @@
 /**
 {{#notes}}
- * {{{notes}}}
-{{/notes}}
-{{#summary}}
- * @summary {{{summary}}}
-{{/summary}}
-{{#vendorExtensions}}
+  * {{{.}}}{{/notes}}{{#vendorExtensions}}{{#x-acl.0}}
+  *
+  * Required API Key ACLs:{{/x-acl.0}}
+  {{#x-acl}}
+  *  - {{.}}
+  {{/x-acl}}
   {{#x-create-wrapping-object}}
     * @param {{nickname}} - The {{nickname}} object.
     {{#allParams}}

diff --git a/templates/kotlin/api.mustache b/templates/kotlin/api.mustache
@@ -54,8 +54,13 @@ public class {{classname}}(
   {{#operation}}
 
   /**
-   * {{{summary}}}
-   * {{{notes}}}
+   * {{{notes}}}{{#vendorExtensions}}{{#x-acl.0}}
+   *
+   * Required API Key ACLs:{{/x-acl.0}}
+   {{#x-acl}}
+   *   - {{.}}
+   {{/x-acl}}
+   {{/vendorExtensions}}
    {{#allParams}}
    * @param {{{paramName}}} {{{description}}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}}
    {{/allParams}}

diff --git a/templates/php/api.mustache b/templates/php/api.mustache
@@ -161,14 +161,17 @@ use {{invokerPackage}}\Support\Helpers;
 
 {{#operation}}
     /**
-{{#summary}}
-     * {{.}}
-{{/summary}}
+{{#notes}}
+     * {{{.}}}
      *
-{{#description}}
-     * {{.}}
-     *
-{{/description}}
+{{/notes}}
+{{#vendorExtensions}}
+{{#x-acl.0}}
+     * Required API Key ACLs:{{/x-acl.0}}
+     {{#x-acl}}
+     *  - {{.}}
+{{/x-acl}}
+{{/vendorExtensions}}
 {{#allParams}}
      * @param {{#isString}}string{{/isString}}{{#isLong}}int{{/isLong}}{{#isInteger}}int{{/isInteger}}{{#isBoolean}}bool{{/isBoolean}}{{^isString}}{{^isLong}}{{^isInteger}}{{^isBoolean}}array{{/isBoolean}}{{/isInteger}}{{/isLong}}{{/isString}} ${{paramName}}{{#description}} {{.}}{{/description}}{{^description}} {{paramName}}{{/description}} {{#required}}(required){{/required}}{{^required}}(optional{{#defaultValue}}, default to {{{.}}}{{/defaultValue}}){{/required}}{{#isDeprecated}} (deprecated){{/isDeprecated}}
 {{#isModel}}

diff --git a/templates/python/api.mustache b/templates/python/api.mustache
@@ -80,12 +80,16 @@ class {{classname}}:
 
     async def {{operationId}}_with_http_info{{>partial_api_args}} -> ApiResponse[str]:
         """
-        {{#isDeprecated}}(Deprecated) {{/isDeprecated}}{{{summary}}}{{^summary}}{{operationId}}{{/summary}}
-
+        {{#isDeprecated}}
+        (Deprecated) {{operationId}}
+        {{/isDeprecated}}
         {{#notes}}
         {{{.}}}
-        {{/notes}}
-
+        {{/notes}}{{#vendorExtensions}}{{#x-acl.0}}
+        Required API Key ACLs:{{/x-acl.0}}
+        {{#x-acl}}
+          - {{.}}
+        {{/x-acl}}{{/vendorExtensions}}
         {{#allParams}}
         :param {{paramName}}:{{#description}} {{{.}}}{{/description}}{{#required}} (required){{/required}}{{#optional}}(optional){{/optional}}
         :type {{paramName}}: {{dataType}}{{#optional}}, optional{{/optional}}
@@ -151,12 +155,16 @@ class {{classname}}:
 
     async def {{operationId}}{{>partial_api_args}} -> {{{returnType}}}{{^returnType}}None{{/returnType}}:
         """
-        {{#isDeprecated}}(Deprecated) {{/isDeprecated}}{{{summary}}}{{^summary}}{{operationId}}{{/summary}}
-
+        {{#isDeprecated}}
+        (Deprecated) {{operationId}}
+        {{/isDeprecated}}
         {{#notes}}
         {{{.}}}
-        {{/notes}}
-
+        {{/notes}}{{#vendorExtensions}}{{#x-acl.0}}
+        Required API Key ACLs:{{/x-acl.0}}
+        {{#x-acl}}
+          - {{.}}
+        {{/x-acl}}{{/vendorExtensions}}
         {{#allParams}}
         :param {{paramName}}:{{#description}} {{{.}}}{{/description}}{{#required}} (required){{/required}}{{#optional}}(optional){{/optional}}
         :type {{paramName}}: {{dataType}}{{#optional}}, optional{{/optional}}
@@ -169,4 +177,4 @@ class {{classname}}:
         return (await self.{{operationId}}_with_http_info({{#allParams}}{{paramName}},{{/allParams}}request_options)).deserialize({{{returnType}}})
 
 {{/operation}}
-{{/operations}}
+{{/operations}}
diff --git a/templates/ruby/api.mustache b/templates/ruby/api.mustache
@@ -53,12 +53,17 @@ module {{moduleName}}
     end
 
 {{#operation}}
-    {{#summary}}
-    # {{.}}
-    {{/summary}}
     {{#notes}}
     # {{.}}
     {{/notes}}
+    {{#vendorExtensions}}
+    {{#x-acl.0}}
+    #
+    # Required API Key ACLs:{{/x-acl.0}}
+    {{#x-acl}}
+    #   - {{.}}
+    {{/x-acl}}
+    {{/vendorExtensions}}
 {{#allParams}}
 {{#required}}
     # @param {{paramName}} [{{{dataType}}}] {{description}} (required)
@@ -182,12 +187,17 @@ module {{moduleName}}
       @api_client.call_api(:{{httpMethod}}, path, new_options)
     end
 
-    {{#summary}}
-    # {{{.}}}
-    {{/summary}}
     {{#notes}}
     # {{{.}}}
     {{/notes}}
+    {{#vendorExtensions}}
+    {{#x-acl.0}}
+    #
+    # Required API Key ACLs:{{/x-acl.0}}
+    {{#x-acl}}
+    #   - {{.}}
+    {{/x-acl}}
+    {{/vendorExtensions}}
 {{#allParams}}
 {{#required}}
     # @param {{paramName}} [{{{dataType}}}] {{description}} (required)

diff --git a/templates/scala/api.mustache b/templates/scala/api.mustache
@@ -98,6 +98,14 @@ class {{classname}}(
   
 {{#operation}}
 /** {{{notes}}}
+{{#vendorExtensions}}
+{{#x-acl.0}}
+*
+* Required API Key ACLs:{{/x-acl.0}}
+{{#x-acl}}
+*   - {{.}}
+{{/x-acl}}
+{{/vendorExtensions}}
 *
 {{#allParams}}
 {{#description}}

diff --git a/templates/swift/api.mustache b/templates/swift/api.mustache
@@ -61,10 +61,9 @@ typealias Client = {{classname}}
     {{/allParams}}
 
     /**
-     {{#summary}}
-     {{{.}}}
-     {{/summary}}{{#allParams}}
-     - parameter {{paramName}}: ({{#isFormParam}}form{{/isFormParam}}{{#isQueryParam}}query{{/isQueryParam}}{{#isPathParam}}path{{/isPathParam}}{{#isHeaderParam}}header{{/isHeaderParam}}{{#isBodyParam}}body{{/isBodyParam}}) {{description}} {{^required}}(optional{{#defaultValue}}, default to {{{.}}}{{/defaultValue}}){{/required}}{{/allParams}}
+     {{#allParams}}
+     - parameter {{paramName}}: ({{#isFormParam}}form{{/isFormParam}}{{#isQueryParam}}query{{/isQueryParam}}{{#isPathParam}}path{{/isPathParam}}{{#isHeaderParam}}header{{/isHeaderParam}}{{#isBodyParam}}body{{/isBodyParam}}) {{description}} {{^required}}(optional{{#defaultValue}}, default to {{{.}}}{{/defaultValue}}){{/required}}
+     {{/allParams}}
      - returns: {{{returnType}}}{{#returnType}}{{#isResponseOptional}}?{{/isResponseOptional}}{{/returnType}}{{^returnType}}Void{{/returnType}}
      */
     {{#isDeprecated}}
@@ -83,10 +82,16 @@ typealias Client = {{classname}}
     }
 
     /**
-     {{#summary}}
-     {{{.}}}
-     {{/summary}}{{#notes}}
-     {{{.}}}{{/notes}}{{#subresourceOperation}}
+     {{#notes}}{{{.}}}{{/notes}}
+     {{#vendorExtensions}}
+     {{#x-acl.0}}
+
+     Required API Key ACLs:{{/x-acl.0}}
+     {{#x-acl}}
+       - {{.}}
+     {{/x-acl}}
+     {{/vendorExtensions}}
+     {{#subresourceOperation}}
      subresourceOperation: {{.}}{{/subresourceOperation}}{{#defaultResponse}}
      defaultResponse: {{.}}{{/defaultResponse}}
      {{#hasResponseHeaders}}