Implement JSDOC

Signed-off-by: Theo Truong <[email protected]>

.ci/license/check-license-headers.sh

@@ -37,13 +37,13 @@ function check_license_header {
 cd "$TOP"
 nErrors=0
 
-for f in $(git ls-files --directory ../ | grep '\.ts$'); do
+for f in $(git ls-files --directory ../ | grep '\.ts$' | grep -v '^docs/'); do
     if ! check_license_header $f; then
         nErrors=$((nErrors+1))
     fi
 done
 
-for f in $(git ls-files --directory ../ | grep '\.js$'); do
+for f in $(git ls-files --directory ../ | grep '\.js$' | grep -v '^docs/'); do
     if ! check_license_header $f; then
         nErrors=$((nErrors+1))
     fi
@@ -53,4 +53,4 @@ if [[ $nErrors -eq 0 ]]; then
     exit 0
 else
     exit 1
-fi
+fi

.github/workflows/gh_pages.yml

@@ -0,0 +1,37 @@
+name: Publish Docs to Github Pages
+on:
+  workflow_dispatch:
+  push:
+    branches: [main, jsdoc]
+jobs:
+  update-docs:
+    runs-on: ubuntu-latest
+    name: Update gh-pages with docs
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v1
+        with:
+          ruby-version: 16.x
+      - name: Install Tools
+        run: |
+          sudo apt install -y jq
+          npm install -g jsdoc
+      - name: Generate Docs
+        run: |
+          export PACKAGE_VERSION=$(jq .version package.json -r | awk -F. '{print $1"."$2}')
+          export DOC_FOLDER=docs/$PACKAGE_VERSION 
+          jsdoc api lib -d $DOC_FOLDER -r --readme README.md
+          cp *.md $DOC_FOLDER
+          cp *.txt $DOC_FOLDER
+      - name: Commit Docs Change
+        uses: EndBug/add-and-commit@v9
+        with:
+          default_author: github_actions
+          add: 'docs/* -f'
+      - name: Deploy Docs to gh-pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          keep_files: true
+          enable_jekyll: true

.gitignore

@@ -53,6 +53,9 @@ opensearch*
 !opensearch_dashboards*
 !opensearchDashboards*
 
+# documentation
+docs/
+
 test/benchmarks/macro/fixtures/*
 
 *-junit.xml

CHANGELOG.md

@@ -4,6 +4,9 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 ### Added
 - Add release details to releasing.md ([319](https://github.com/opensearch-project/opensearch-js/pull/319))
+- jsdoc for documentation generation ([#335](https://github.com/opensearch-project/opensearch-js/issues/335))
+- Documentation for Transport#request ([#335](https://github.com/opensearch-project/opensearch-js/issues/335))
+- Documentation for api/bulk ([#335](https://github.com/opensearch-project/opensearch-js/issues/335))
 ### Dependencies
 ### Changed
 ### Deprecated

api/api/bulk.js

@@ -32,6 +32,8 @@
 /* eslint camelcase: 0 */
 /* eslint no-unused-vars: 0 */
 
+/** @namespace API-bulk */
+
 const { handleError, snakeCaseKeys, normalizeArguments, kConfigurationError } = require('../utils');
 const acceptedQuerystring = [
   'wait_for_active_shards',
@@ -63,6 +65,24 @@ const snakeCase = {
   filterPath: 'filter_path',
 };
 
+/**
+ * The bulk operation lets you add, update, or delete many documents in a single request.
+ * Compared to individual OpenSearch indexing requests, the bulk operation has significant performance benefits.
+ * Whenever practical, we recommend batching indexing operations into bulk requests.
+ * <br/> See Also: {@link https://opensearch.org/docs/latest/api-reference/document-apis/bulk/|OpenSearch - Bulk}
+ *
+ * @memberOf API-bulk
+ *
+ * @param {Object} params
+ * @param {Object[]} params.body - {@link https://opensearch.org/docs/latest/api-reference/document-apis/bulk/#request-body|Request Body}
+ * @param {string} [params.index] - Specifying the index means you don’t need to include it in the request body.
+ * @param {} [params....] {@link https://opensearch.org/docs/latest/api-reference/document-apis/bulk/#url-parameters|URL parameters}
+ *
+ * @param {Object} options - Options for {@link Transport#request}
+ * @param {function} callback - Callback that handles errors and response
+ *
+ * @returns {{abort: function(), then: function(), catch: function()}|Promise<never>|*} {@link https://opensearch.org/docs/latest/api-reference/document-apis/bulk/#response|Bulk Response}
+ */
 function bulkApi(params, options, callback) {
   [params, options, callback] = normalizeArguments(params, options, callback);
 

lib/Serializer.js

@@ -90,7 +90,7 @@ class Serializer {
     const keys = Object.keys(object);
     for (let i = 0, len = keys.length; i < len; i++) {
       const key = keys[i];
-      // OpenSearch will complain for keys without a value
+      // OpenSearch will complain about keys without a value
       if (object[key] === undefined) {
         delete object[key];
       } else if (Array.isArray(object[key]) === true) {

lib/Transport.js

@@ -56,6 +56,7 @@ const HEAP_SIZE_LIMIT = require('v8').getHeapStatistics().heap_size_limit;
 const kCompatibleCheck = Symbol('compatible check');
 const kApiVersioning = Symbol('api versioning');
 
+/** Default Transport Layer */
 class Transport {
   constructor(opts) {
     if (typeof opts.compression === 'string' && opts.compression !== 'gzip') {
@@ -110,6 +111,27 @@ class Transport {
     }
   }
 
+  /**
+   * @param {Object} params
+   * @param {string} params.method - HTTP Method (e.g. HEAD, GET, POST...)
+   * @param {string} params.path - Relative URL path
+   * @param {Object | string} [params.body] - Body of a standard request.
+   * @param {Object[] | string} [params.bulkBody] - Body of a bulk request.
+   * @param {Object[] | string} [params.querystring] - Querystring params.
+   *
+   * @param {Object} options
+   * @param {number} [options.id] - Request ID
+   * @param {Object} [options.context] - Object used for observability
+   * @param {number} [options.maxRetries] - Max number of retries
+   * @param {false | 'gzip'} [options.compression] - Request body compression, if any
+   * @param {boolean} [options.asStream] - Whether to emit the response as stream
+   * @param {number[]} [options.ignore] - Response's Error Status Codes to ignore
+   * @param {Object} [options.headers] - Request headers
+   * @param {Object | string} [options.querystring] - Request's query string
+   * @param {number} [options.requestTimeout] - Max request timeout in milliseconds
+   *
+   * @param {function} callback - Callback that handles errors and response
+   */
   request(params, options, callback) {
     options = options || {};
     if (typeof options === 'function') {
@@ -386,7 +408,7 @@ class Transport {
         // if the statusCode is 502/3/4 we should run our retry strategy
         // and mark the connection as dead
         this.connectionPool.markDead(meta.connection);
-        // retry logic (we shoukd not retry on "429 - Too Many Requests")
+        // retry logic (we should not retry on "429 - Too Many Requests")
         if (meta.attempts < maxRetries && result.statusCode !== 429) {
           meta.attempts++;
           debug(`Retrying request, there are still ${maxRetries - meta.attempts} attempts`, params);

package.json

@@ -71,6 +71,7 @@
     "fast-deep-equal": "^3.1.3",
     "into-stream": "^6.0.0",
     "js-yaml": "^4.1.0",
+    "jsdoc": "^4.0.0",
     "license-checker": "^25.0.1",
     "minimist": "^1.2.5",
     "node-fetch": "^3.2.10",