From b3d61128af53175cf1fe85b39305cd33c20d4300 Mon Sep 17 00:00:00 2001 From: Pierre Millot Date: Mon, 29 Jan 2024 18:10:53 +0100 Subject: [PATCH] docs(clients): add ACL section to code doc (#2576) --- .../algoliasearch/build.gradle | 4 +++ templates/csharp/api.mustache | 15 ++++++----- templates/dart/api.mustache | 11 +++++--- templates/go/api.mustache | 12 +++++++-- templates/java/api.mustache | 8 +++--- templates/java/api_javadoc.mustache | 5 +--- templates/java/oneof_interface.mustache | 8 +++--- .../client/api/operation/jsdoc.mustache | 12 ++++----- templates/kotlin/api.mustache | 9 +++++-- templates/php/api.mustache | 17 +++++++----- templates/python/api.mustache | 26 ++++++++++++------- templates/ruby/api.mustache | 22 +++++++++++----- templates/scala/api.mustache | 8 ++++++ templates/swift/api.mustache | 21 +++++++++------ 14 files changed, 117 insertions(+), 61 deletions(-) diff --git a/clients/algoliasearch-client-java/algoliasearch/build.gradle b/clients/algoliasearch-client-java/algoliasearch/build.gradle index a8a8395822..bbfdc98a60 100644 --- 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 index e69d943a18..0cdafedd6f 100644 --- a/templates/csharp/api.mustache +++ b/templates/csharp/api.mustache @@ -25,11 +25,8 @@ namespace Algolia.Search.Clients; { {{#operation}} /// - /// {{{summary}}} - /// - /// /// {{{notes}}} - /// + /// {{#allParams}} /// {{{description}}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}{{#isDeprecated}} (deprecated){{/isDeprecated}} {{/allParams}} @@ -106,8 +103,14 @@ namespace Algolia.Search.Clients; {{#supportsAsync}} /// - /// {{{summary}}} {{notes}} - /// + /// {{{notes}}} + /// {{#vendorExtensions}}{{#x-acl.0}} + /// + /// Required API Key ACLs:{{/x-acl.0}} + {{#x-acl}} + /// - {{.}} + {{/x-acl}} + {{/vendorExtensions}} {{#allParams}} /// {{description}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}{{#isDeprecated}} (deprecated){{/isDeprecated}} {{/allParams}} diff --git a/templates/dart/api.mustache b/templates/dart/api.mustache index 585e6d907f..f25e8af529 100644 --- 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}} \ No newline at end of file +{{/operations}} diff --git a/templates/go/api.mustache b/templates/go/api.mustache index 060b652241..34ed194070 100644 --- 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 index c85a0b884a..d9a64b61c8 100644 --- 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 index 2c4ce908e1..29b6263f85 100644 --- a/templates/java/api_javadoc.mustache +++ b/templates/java/api_javadoc.mustache @@ -2,10 +2,7 @@ {{#isDeprecated}} * @deprecated {{/isDeprecated}} - {{#externalDocs}} - * @see {{{summary}}} Documentation ({{{description}}}) - {{/externalDocs}} */ {{#isDeprecated}} @Deprecated - {{/isDeprecated}} + {{/isDeprecated}} \ No newline at end of file diff --git a/templates/java/oneof_interface.mustache b/templates/java/oneof_interface.mustache index 48401ddadf..66fc658067 100644 --- a/templates/java/oneof_interface.mustache +++ b/templates/java/oneof_interface.mustache @@ -24,7 +24,7 @@ public interface {{classname}}{{#vendorExtensions.x-has-child-generic}}{{/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}}{{/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}}{{/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}}{{/ven {{/isNullable}} } } -} \ No newline at end of file +} diff --git a/templates/javascript/clients/client/api/operation/jsdoc.mustache b/templates/javascript/clients/client/api/operation/jsdoc.mustache index deae5aa3c7..f54b90130f 100644 --- 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 index 36df1b1b9a..74df37cb50 100644 --- 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 index ecfba7b432..3909f6251f 100644 --- 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 index d06fcddc3d..c9932375d7 100644 --- 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}} \ No newline at end of file +{{/operations}} diff --git a/templates/ruby/api.mustache b/templates/ruby/api.mustache index 7630e194ea..9439629a40 100644 --- 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 index 0606406c78..e21ecc5577 100644 --- 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 index 446624defb..647a2e2fdb 100644 --- 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}}