Merge pull request #49 from classmethod/add-jsdoc

Author: yamatatsu

README.md

@@ -26,7 +26,7 @@ yarn add @classmethod/athena-query @aws-sdk/client-athena
 
 ### Basic Usage
 
-Athena-Query provide [async generator function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function*).
+Athena-Query provide `query()` method as [async generator function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function*).
 So we can use it with `for await () {}`,
 
 ```ts
@@ -43,6 +43,8 @@ for await (const item of athenaQuery.query("SELECT * FROM waf_logs;")) {
 
 And if you break loop out, Athena-Query don't call unnecessary pages of `get-query-result` api.
 
+If you want to reduce the size of the queried data rather than the retrieved data, you can use the [LIMIT clause](https://docs.aws.amazon.com/athena/latest/ug/select.html#select-parameters).
+
 ### Options
 
 When you initialize AthenaQuery class, you can pass options to specify the query target.
@@ -65,7 +67,6 @@ const resultGen = athenaQuery.query(
   `,
   {
     executionParameters: ["test", 123, 456n],
-    maxResults: 100,
   }
 );
 ```

lib/athena-query.ts

@@ -2,8 +2,20 @@ import * as helpers from "./helper";
 import type { Athena } from "@aws-sdk/client-athena";
 
 type Options = {
-  db?: string;
+  /**
+   * The name of the workgroup in which the query is being started.
+   */
   workgroup?: string;
+
+  /**
+   * The name of the database used in the query execution.
+   * The database must exist in the catalog.
+   */
+  db?: string;
+
+  /**
+   * The name of the data catalog used in the query execution.
+   */
   catalog?: string;
 };
 
@@ -13,10 +25,29 @@ export class AthenaQuery {
     private readonly options?: Options
   ) {}
 
+  /**
+   * @see https://github.com/classmethod/athena-query#usage
+   *
+   * @param sql
+   * @param options
+   */
   async *query(
     sql: string,
     options?: {
+      /**
+       * A list of values for the parameters in a query.
+       * The values are applied sequentially to the parameters in the query in the order in which the parameters occur.
+       */
       executionParameters?: (string | number | BigInt)[];
+
+      /**
+       * The maximum number of results (rows) to return in this request.
+       *
+       * @deprecated We recommend you to use LIMIT clause in SQL.
+       * Because even if you set it, athena-query will continue to retrieve results unless you break your for-loop.
+       *
+       * @see https://docs.aws.amazon.com/athena/latest/ug/select.html#select-parameters
+       */
       maxResults?: number;
     }
   ): AsyncGenerator<helpers.AtheneRecordData, void, undefined> {