Implement JSDOC (opensearch-project#337)

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

Signed-off-by: Theo Truong <[email protected]>
Co-authored-by: Daniel (dB.) Doubrovkine <[email protected]>
Signed-off-by: Ajay Gupta <[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

@@ -6,6 +6,10 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Add release details to releasing.md ([319](https://github.com/opensearch-project/opensearch-js/pull/319))
 - Allow overriding the aws service identifier in AwsSigv4Signer ([333](https://github.com/opensearch-project/opensearch-js/pull/333))
 - Added skip-changelog label ([339](https://github.com/opensearch-project/opensearch-js/pull/339))
+- Added jsdoc for documentation generation ([#335](https://github.com/opensearch-project/opensearch-js/issues/335))
+- Documented Transport#request ([#335](https://github.com/opensearch-project/opensearch-js/issues/335))
+- Documented all API methods ([#335](https://github.com/opensearch-project/opensearch-js/issues/335))
+
 ### Dependencies
 ### Changed
 ### Deprecated

api/api/bulk.js

@@ -63,6 +63,29 @@ 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-Document
+ *
+ * @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 {string} [params.pipeline] - The pipeline ID for preprocessing documents.
+ * @param {string} [params.routing] - Routes the request to the specified shard.
+ * @param {string} [params.refresh=false] - If true, OpenSearch refreshes shards to make the operation visible to searching. Valid options are 'true', 'false', and 'wait_for', which tells OpenSearch to wait for a refresh before executing the operation.
+ * @param {string} [params.timeout=1m] - How long to wait for a response from the cluster.
+ * @param {string} [params.wait_for_active_shards] - The number of active shards that must be available before OpenSearch processes the request. Default is 1 (only the primary shard). Set to all or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the operation to succeed.
+ * @param {boolean} [params.require_alias=false] - Specifies whether the target index must be an index alias.
+ *
+ * @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);