Add more inline comments (#1668)

This change adds more detailed comments, and example usage to make
things easier for developers.
The documentation coverage is now closer to that of line-bot-sdk-ruby.
(some comments in pebble template are imported)

The change seems big, but it's ok to review only
`generator/src/main/resources/line-bot-sdk-nodejs-generator/*.pebble` (3
files)

Author: Yang-33

generator/src/main/resources/line-bot-sdk-nodejs-generator/api-single.pebble

@@ -18,10 +18,21 @@ import HTTPFetchClient, { convertResponseToReadable, mergeHeaders } from "../../
 // ===============================================
 
 interface httpClientConfig {
+    /**
+     * Base URL for requests.
+     * Defaults to '{{endpoint(operations.classname)}}'.
+     * You can override this for testing or to use a mock server.
+     */
     baseURL?: string;
     {% if authMethods != null -%}
+    /**
+     * Channel access token used for authorization.
+     */
     channelAccessToken: string;
     {% endif -%}
+    /**
+     * Extra headers merged into every request.
+     */
     defaultHeaders?: Record<string, string>;
 }
 
@@ -34,6 +45,23 @@ interface httpClientConfig {
 export class {{operations.classname}} {
     private httpClient: HTTPFetchClient;
 
+    /**
+     * Initializes a new `{{operations.classname}}`.
+     *
+     * @param config Configuration for this API client.
+     * @param config.baseURL The base URL for requests. Defaults to `{{endpoint(operations.classname)}}`.
+{% if authMethods != null -%}
+     * @param config.channelAccessToken The channel access token used for authorization.
+{% endif -%}
+     * @param config.defaultHeaders Extra headers merged into every request.
+     *
+     * @example
+     * const client = new {{operations.classname}}({
+{% if authMethods != null -%}
+     *   channelAccessToken: process.env.LINE_CHANNEL_ACCESS_TOKEN!,
+{% endif -%}
+     * });
+     */
     constructor(config: httpClientConfig) {
         const baseURL = config.baseURL || '{{endpoint(operations.classname)}}';
         const defaultHeaders = mergeHeaders(
@@ -53,45 +81,58 @@ export class {{operations.classname}} {
 {% for op in operations.operation -%}
     /**
      * {{op.notes}}
+     * Calls `{{op.httpMethod}} {{endpoint(operations.classname)}}{{op.path}}`.
+     * To inspect the HTTP status code or response headers, use {@link {{op.nickname}}WithHttpInfo}.
     {% if op.summary -%}
      * @summary {{op.summary}}
     {% endif -%}
     {% for param in op.allParams -%}
      * @param {{param.paramName}} {{param.description}}
     {% endfor -%}
+     * @returns A promise resolving to the response body.
     {% if op.isDeprecated -%}
      * @deprecated
     {% endif -%}
     {% if op.operationId == "issueStatelessChannelToken" -%}
      * @deprecated Use {@link issueStatelessChannelTokenByJWTAssertion} or {@link issueStatelessChannelTokenByClientSecret} instead.
     {% endif -%}
     {% if op.externalDocs != null -%}
+      {% if op.externalDocs.description != null -%}
      * {{op.externalDocs.description}}
-     * @see <a href="{{op.externalDocs.url}}">{{op.summary}} Documentation</a>
+      {% endif -%}
+      {% if op.externalDocs.url != null -%}
+     * @see <a href="{{op.externalDocs.url}}">LINE Developers documentation</a>
+      {% endif -%}
     {% endif -%}
      */
     public async {{op.nickname}}({% for param in op.allParams %}{{param.paramName}}{% if not param.required %}?{% endif %}: {{param.dataType}}, {% endfor %}) : Promise<{% if op.returnType %}{{ op.returnType }}{% else %}Types.MessageAPIResponseBase{% endif %}> {
         return (await this.{{op.nickname}}WithHttpInfo({% for param in op.allParams %}{{param.paramName}}, {% endfor %})).body;
     }
 
     /**
-     * {{op.notes}}.
-     * This method includes HttpInfo object to return additional information.
+     * {{op.notes}}
+     * Calls `{{op.httpMethod}} {{endpoint(operations.classname)}}{{op.path}}`.
+     * This method returns the response body together with the underlying `httpResponse`.
     {% if op.summary -%}
      * @summary {{op.summary}}
     {% endif -%}
     {% for param in op.allParams -%}
      * @param {{param.paramName}} {{param.description}}
     {% endfor -%}
+     * @returns A promise resolving to the response body together with the underlying `httpResponse`.
     {% if op.isDeprecated -%}
      * @deprecated
     {% endif -%}
     {% if op.operationId == "issueStatelessChannelToken" -%}
      * @deprecated Use {@link issueStatelessChannelTokenByJWTAssertionWithHttpInfo} or {@link issueStatelessChannelTokenByClientSecretWithHttpInfo} instead.
     {% endif -%}
     {% if op.externalDocs != null -%}
+      {% if op.externalDocs.description != null -%}
      * {{op.externalDocs.description}}
-     * @see <a href="{{op.externalDocs.url}}">{{op.summary}} Documentation</a>
+      {% endif -%}
+      {% if op.externalDocs.url != null -%}
+     * @see <a href="{{op.externalDocs.url}}">LINE Developers documentation</a>
+      {% endif -%}
     {% endif -%}
      */
     public async {{op.nickname}}WithHttpInfo({% for param in op.allParams %}{{param.paramName}}{% if not param.required %}?{% endif %}: {{param.dataType}}, {% endfor %}) : Promise<Types.ApiResponseType<{% if op.returnType %}{{ op.returnType }}{% else %}Types.MessageAPIResponseBase{% endif %}>> {

generator/src/main/resources/line-bot-sdk-nodejs-generator/body/api/ChannelAccessTokenClient.ts

@@ -1,9 +1,11 @@
     /**
      * Issues a new stateless channel access token by JWT assertion.
      * The newly issued token is only valid for 15 minutes but can not be revoked until it naturally expires.
+     * Calls `POST https://api.line.me/oauth2/v3/token`.
+     * To inspect the HTTP status code or response headers, use {@link issueStatelessChannelTokenByJWTAssertionWithHttpInfo}.
      * @param clientAssertion A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.
-     * @returns A promise containing the {@link IssueStatelessChannelAccessTokenResponse}.
-     * @see <a href="https://developers.line.biz/en/reference/messaging-api/#issue-stateless-channel-access-token">Documentation</a>
+     * @returns A promise resolving to the response body.
+     * @see <a href="https://developers.line.biz/en/reference/messaging-api/#issue-stateless-channel-access-token">LINE Developers documentation</a>
      */
     public async issueStatelessChannelTokenByJWTAssertion(
         clientAssertion: string,
@@ -18,10 +20,12 @@
     /**
      * Issues a new stateless channel access token by client secret.
      * The newly issued token is only valid for 15 minutes but can not be revoked until it naturally expires.
+     * Calls `POST https://api.line.me/oauth2/v3/token`.
+     * To inspect the HTTP status code or response headers, use {@link issueStatelessChannelTokenByClientSecretWithHttpInfo}.
      * @param clientId Channel ID.
      * @param clientSecret Channel secret.
-     * @returns A promise containing the {@link IssueStatelessChannelAccessTokenResponse}.
-     * @see <a href="https://developers.line.biz/en/reference/messaging-api/#issue-stateless-channel-access-token">Documentation</a>
+     * @returns A promise resolving to the response body.
+     * @see <a href="https://developers.line.biz/en/reference/messaging-api/#issue-stateless-channel-access-token">LINE Developers documentation</a>
      */
     public async issueStatelessChannelTokenByClientSecret(
         clientId: string,
@@ -39,10 +43,11 @@
     /**
      * Issues a new stateless channel access token by JWT assertion.
      * The newly issued token is only valid for 15 minutes but can not be revoked until it naturally expires.
-     * This method includes HttpInfo object to return additional information.
+     * Calls `POST https://api.line.me/oauth2/v3/token`.
+     * This method returns the response body together with the underlying `httpResponse`.
      * @param clientAssertion A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.
-     * @returns A promise containing the {@link IssueStatelessChannelAccessTokenResponse} with HTTP info.
-     * @see <a href="https://developers.line.biz/en/reference/messaging-api/#issue-stateless-channel-access-token">Documentation</a>
+     * @returns A promise resolving to the response body together with the underlying `httpResponse`.
+     * @see <a href="https://developers.line.biz/en/reference/messaging-api/#issue-stateless-channel-access-token">LINE Developers documentation</a>
      */
     public async issueStatelessChannelTokenByJWTAssertionWithHttpInfo(
         clientAssertion: string,
@@ -57,11 +62,12 @@
     /**
      * Issues a new stateless channel access token by client secret.
      * The newly issued token is only valid for 15 minutes but can not be revoked until it naturally expires.
-     * This method includes HttpInfo object to return additional information.
+     * Calls `POST https://api.line.me/oauth2/v3/token`.
+     * This method returns the response body together with the underlying `httpResponse`.
      * @param clientId Channel ID.
      * @param clientSecret Channel secret.
-     * @returns A promise containing the {@link IssueStatelessChannelAccessTokenResponse} with HTTP info.
-     * @see <a href="https://developers.line.biz/en/reference/messaging-api/#issue-stateless-channel-access-token">Documentation</a>
+     * @returns A promise resolving to the response body together with the underlying `httpResponse`.
+     * @see <a href="https://developers.line.biz/en/reference/messaging-api/#issue-stateless-channel-access-token">LINE Developers documentation</a>
      */
     public async issueStatelessChannelTokenByClientSecretWithHttpInfo(
         clientId: string,

generator/src/main/resources/line-bot-sdk-nodejs-generator/model.pebble

@@ -40,28 +40,28 @@ export type {{classname}}{% if model.model.discriminator != null %}Base{% endif
      * {{ var.description }}
 {%- endif %}
 {%- if var.minimum != null %}
-     * @minimum {{ var.minimum }}
+     * Minimum: {{ var.minimum }}
 {%- endif %}
 {%- if var.maximum != null %}
-     * @maximum {{ var.maximum }}
+     * Maximum: {{ var.maximum }}
 {%- endif %}
 {%- if var.minLength != null %}
-     * @minLength {{ var.minLength }}
+     * Minimum length: {{ var.minLength }}
 {%- endif %}
 {%- if var.maxLength != null %}
-     * @maxLength {{ var.maxLength }}
+     * Maximum length: {{ var.maxLength }}
 {%- endif %}
 {%- if var.minItems != null %}
-     * @minItems {{ var.minItems }}
+     * Minimum items: {{ var.minItems }}
 {%- endif %}
 {%- if var.maxItems != null %}
-     * @maxItems {{ var.maxItems }}
+     * Maximum items: {{ var.maxItems }}
 {%- endif %}
 {%- if var.pattern != null %}
-     * @pattern {{ var.pattern }}
+     * Pattern: {{ var.pattern }}
 {%- endif %}
 {%- if var.defaultValue != null %}
-     * @default {{ var.defaultValue }}
+     * Default: {{ var.defaultValue }}
 {%- endif %}
      */
 {%- endif %}