Documentation & apidoc refactor 5.0 (#1062)

srknzl · web-flow · commit 8642985aea10 · 2021-09-29T16:24:47.000+03:00
* Apidoc and documentation fixes for 5.0

* Review comments
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -51,12 +51,16 @@ All PRs follow the same process:
 That includes descriptive commit messages.
 5. Please keep your PRs as small as possible, _i.e._ if you plan to perform a huge change,
 do not submit a single and large PR for it. For an enhancement or larger feature, you can create a GitHub issue first to discuss.
-6. Before you push, run these commands in your terminal to check if there are any errors:
+6. Before you push, you can run these commands in your terminal to check if there are any errors:
     * `npm install`: Installs dependencies
     * `npm run compile`: Compiles TypeScript into JavaScript, checking for any errors along the way
-    * `npm run lint`: Runs linting to find stylistic/structural errors in the code
+    * `npm run lint`: Runs linting to find stylistic/structural errors in the code and markdown files
     * `npm run validate-user-code`: Checks the validity of generated TypeScript type declaration files
-    * `npm run test`: Runs unit and integration tests against the generated JavaScript code(the generated code is in `lib/` folder)
+    * `npm run check-markdown-links <FILE>`: Checks for broken links in a markdown.
+    Example usage: `npm run check-markdown-links DOCUMENTATION.md`
+    * `npm run test:unit`: Runs unit tests against the generated JavaScript code (the generated code is in `lib/` folder)
+    * `npm run test:integration`(SLOW): Runs integration tests against the generated JavaScript code
+    (the generated code is in `lib/` folder)
 Push your PR once it is free of errors.
 7. If you submit a PR as the solution to a specific issue, please mention the issue number either in the PR description
 or commit message.
diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
diff --git a/README.md b/README.md
@@ -23,20 +23,20 @@
 [Hazelcast](https://hazelcast.com/) is an open-source distributed in-memory data store and computation platform that
 provides a wide variety of distributed data structures and concurrency primitives.
 
-Hazelcast Node.js client is a way to communicate to Hazelcast IMDG clusters and access the cluster data.
+Hazelcast Node.js client is a way to communicate to Hazelcast clusters and access the cluster data.
 The client provides a Promise-based API with a builtin support for native JavaScript objects.
 
 ## Installation
 
 ### Hazelcast
 
-Hazelcast Node.js client requires a working Hazelcast IMDG cluster to run. This cluster handles the storage and
+Hazelcast Node.js client requires a working Hazelcast cluster to run. This cluster handles the storage and
 manipulation of the user data.
 
-A Hazelcast IMDG cluster consists of one or more cluster members. These members generally run on multiple virtual or
+A Hazelcast cluster consists of one or more cluster members. These members generally run on multiple virtual or
 physical machines and are connected to each other via the network. Any data put on the cluster is partitioned to
 multiple members transparent to the user. It is therefore very easy to scale the system by adding new members as
-the data grows. Hazelcast IMDG cluster also offers resilience. Should any hardware or software problem causes a crash
+the data grows. Hazelcast cluster also offers resilience. Should any hardware or software problem causes a crash
 to any member, the data on that member is recovered from backups and the cluster continues to operate without any
 downtime.
 
@@ -48,7 +48,7 @@ docker run -p 5701:5701 hazelcast/hazelcast:4.1.1
 ```
 
 You can also use our ZIP or TAR [distributions](https://hazelcast.com/open-source-projects/downloads/)
-as described [here](DOCUMENTATION.md#121-setting-up-a-hazelcast-imdg-cluster).
+as described [here](DOCUMENTATION.md#121-setting-up-a-hazelcast-cluster).
 
 ### Client
 
@@ -84,7 +84,7 @@ await client.shutdown();
 > Refer to the [Code Samples section](https://github.com/hazelcast/hazelcast-nodejs-client/tree/master/code_samples)
 > to see samples with the complete code.**
 
-If you are using Hazelcast IMDG and the Node.js client on the same machine, the default configuration should work
+If you are using Hazelcast and the Node.js client on the same machine, the default configuration should work
 out-of-the-box. However, you may need to configure the client to connect to cluster nodes that are running on
 different machines or to customize client properties.
 
@@ -147,7 +147,7 @@ We encourage any type of contribution in the form of issue reports or pull reque
 
 For issue reports, please share the following information with us to quickly resolve the problems.
 
-* Hazelcast IMDG and the client version that you use
+* Hazelcast and the client version that you use
 * General information about the environment and the architecture you use like Node.js version, cluster size,
 number of clients, Java version, JVM parameters, operating system etc.
 * Logs and stack traces, if any.
@@ -180,7 +180,7 @@ Following command starts the tests:
 npm test
 ```
 
-Test script automatically downloads `hazelcast-remote-controller` and Hazelcast IMDG. The script uses Maven to download those.
+Test script automatically downloads `hazelcast-remote-controller` and Hazelcast. The script uses Maven to download those.
 
 In order to run specific tests, you can give a pattern to the test command like the following:
 
diff --git a/benchmark/README.md b/benchmark/README.md
@@ -1,4 +1,4 @@
-# Simple benchmark for Hazelcast IMDG Node.js Client
+# Simple benchmark for Hazelcast Node.js Client
 
 A simple benchmark that runs operations on `Map` concurrently, measures the execution time and calculates the throughput:
 * `set` - runs `map.set(key, value)` operations.
@@ -17,7 +17,7 @@ Then, build the client (compile TypeScript):
 npm run compile
 ```
 
-Next, run at least one instance of IMDG. The most simple way to do it would be to use the
+Next, run at least one instance of Hazelcast. The most simple way to do it would be to use the
 [official Docker image](https://hub.docker.com/r/hazelcast/hazelcast/):
 ```bash
 docker run --net=host hazelcast/hazelcast:4.1.1
diff --git a/code_samples/jaas_sample/README.md b/code_samples/jaas_sample/README.md
@@ -2,7 +2,7 @@
 
 This code sample demonstrates how to assign different permission policies for different user groups with the
 Hazelcast's JAAS based security features.
-Security features used in this code sample requires **Hazelcast IMDG Enterprise** edition.
+Security features used in this code sample requires **Hazelcast Enterprise** edition.
 
 ---
 
diff --git a/code_samples/jaas_sample/hazelcast-member/README.md b/code_samples/jaas_sample/hazelcast-member/README.md
@@ -1,8 +1,8 @@
 Make sure you have
 * [Java 8+](https://www.java.com/en/download/) installed on your system.
-* [Hazelcast IMDG Enterprise JAR](https://hazelcast.com/download/) available in your system.
+* [Hazelcast Enterprise JAR](https://hazelcast.com/download/) available in your system.
 
-Then, put your Hazelcast IMDG Enterprise license key into the [hazelcast.xml](src/main/resources/hazelcast.xml).
+Then, put your Hazelcast Enterprise license key into the [hazelcast.xml](src/main/resources/hazelcast.xml).
 
 Compile the Java files with the following command:
 
diff --git a/package.json b/package.json
@@ -22,6 +22,7 @@
         "eslint-plugin-mocha": "~8.1.0",
         "husky": "^6.0.0",
         "jsonschema": "~1.4.0",
+        "markdown-link-check": "^3.8.7",
         "markdownlint-cli": "^0.28.1",
         "mocha": "~8.4.0",
         "mocha-jenkins-reporter": "^0.4.6",
@@ -59,6 +60,7 @@
         "lint-markdown:fix": "markdownlint -f --ignore node_modules '**/*.md'",
         "startrc": "node scripts/test-runner.js startrc",
         "check-code-samples": "node scripts/test-runner.js check-code-samples",
+        "check-markdown-links": "markdown-link-check -q",
         "prepare": "husky install"
     },
     "repository": {
diff --git a/src/core/RestValue.ts b/src/core/RestValue.ts
@@ -23,7 +23,7 @@ export const REST_VALUE_FACTORY_ID = -25;
 export const REST_VALUE_CLASS_ID = 1;
 
 /**
- * Wrapper for values stored via IMDG REST API.
+ * Wrapper for values stored via Hazelcast REST API.
  */
 export class RestValue implements IdentifiedDataSerializable {
 
diff --git a/src/core/SimpleEntryView.ts b/src/core/SimpleEntryView.ts
@@ -57,7 +57,7 @@ export class SimpleEntryView<K, V> {
     lastAccessTime: Long;
 
     /**
-     * Last time the value was flushed to mapstore.
+     * Last time the value was flushed to map store.
      */
     lastStoredTime: Long;
 
diff --git a/src/proxy/FencedLock.ts b/src/proxy/FencedLock.ts
@@ -25,8 +25,8 @@ import {DistributedObject} from '../core';
  * failures and network partitions. If a network partition occurs, it remains
  * available on at most one side of the partition.
  *
- * FencedLock works on top of CP sessions. Please refer to CP Session
- * IMDG documentation section for more information.
+ * FencedLock works on top of CP sessions. Please refer to Hazelcast CP Session
+ * documentation section for more information.
  *
  * Important note: FencedLock is non-reentrant. Once a caller acquires
  * the lock, it can not acquire the lock reentrantly. So, the next acquire
diff --git a/src/proxy/IList.ts b/src/proxy/IList.ts
@@ -42,7 +42,7 @@ export interface IList<E> extends DistributedObject {
     addAt(index: number, element: E): Promise<void>;
 
     /**
-     * Appends all elements in the specified array to the end of this list,
+     * Appends all elements in the specified array to the end of this list, keeping the order of the array.
      * @param elements array to be appended
      * @return `true` if this list has changed as a result of this operation, `false` otherwise.
      */
@@ -67,35 +67,34 @@ export interface IList<E> extends DistributedObject {
     addItemListener(listener: ItemListener<E>, includeValue: boolean): Promise<string>;
 
     /**
-     * Clears this list.
+     * Removes all of the elements from this list.
      */
     clear(): Promise<void>;
 
     /**
      * Checks if the list contains the given element.
      * @param element
-     * @return `true` if this list contains an element that is equal the to given element, `false` otherwise.
+     * @return `true` if this list contains the specified element, `false` otherwise.
      */
     contains(element: E): Promise<boolean>;
 
     /**
-     * Checks if the list contains all of the given elements.
+     * Checks if the list contains all of the elements of the specified array.
      * @param elements - elements to be checked for presence in this list.
-     * @return `true` if this list contains all of the given elements, `false` otherwise.
+     * @return `true` if this list contains all of the elements of the specified array, `false` otherwise.
      */
     containsAll(elements: E[]): Promise<boolean>;
 
     /**
-     * Retrieves the element at given location.
+     * Returns the element at the specified position in this list.
      * @param index index of the element to return.
-     * @return the element at that position.
      */
     get(index: number): Promise<E>;
 
     /**
-     * Returns the position of first occurrence of the given element in this list.
+     * Returns the index of the first occurrence of the specified element in this list, or `-1` if this list does not contain
+     * the element.
      * @param element element to search for
-     * @return the index of first occurrence of given element or `-1` if the list does not contain given element.
      */
     indexOf(element: E): Promise<number>;
 
@@ -106,27 +105,28 @@ export interface IList<E> extends DistributedObject {
     isEmpty(): Promise<boolean>;
 
     /**
-     * Returns position of the last occurrence of the given element in this list.
+     * Returns the index of the last occurrence of the specified element in this list,
+     * or -1 if this list does not contain the element.
      * @param element
      */
     lastIndexOf(element: E): Promise<number>;
 
     /**
-     * Removes the given element from this list.
+     * Removes the first occurrence of the specified element from this list, if it is present.
      * @param element element to be removed
      * @return `true` if this list has changed as a result of this operation, `false` otherwise.
      */
     remove(element: E): Promise<boolean>;
 
     /**
-     * Removes the element at the given index.
+     * Removes the element at the specified position in this list.
      * @param index index of the element to be removed.
      * @return the removed element.
      */
     removeAt(index: number): Promise<E>;
 
     /**
-     * Removes given elements from the list.
+     * Removes from this list all of its elements that are contained in the specified array.
      * @param elements elements to be removed
      * @return `true` if this list has changed as a result of this operation, `false` otherwise.
      */
@@ -140,7 +140,7 @@ export interface IList<E> extends DistributedObject {
     removeItemListener(listenerId: string): Promise<boolean>;
 
     /**
-     * Removes all elements from this list except the ones contained in the given array.
+     * Retains only the elements in this list that are contained in the specified array.
      * @param elements elements to retain
      * @return `true` if this list has changed as a result of this operation, `false` otherwise.
      */
@@ -170,7 +170,7 @@ export interface IList<E> extends DistributedObject {
     subList(start: number, end: number): Promise<ReadOnlyLazyList<E>>;
 
     /**
-     * Returns an array that contains all elements of this list in proper sequence.
+     * Returns an array that contains all elements of this list in proper sequence (from first to last element).
      */
     toArray(): Promise<E[]>;
 }
diff --git a/src/proxy/IMap.ts b/src/proxy/IMap.ts
@@ -229,8 +229,9 @@ export interface IMap<K, V> extends DistributedObject {
      * turned off, this call may be rejected with `ReachedMaxSizeError`
      * if the write-behind queue has reached its per-node maximum capacity.
      *
+     * Works with Hazelcast versions 4.1 and above.
+     *
      * @param pairs entries to be put
-     * @requires Hazelcast IMDG 4.1
      */
     setAll(pairs: Array<[K, V]>): Promise<void>;
 
@@ -436,7 +437,7 @@ export interface IMap<K, V> extends DistributedObject {
      * Replaces value of the key if only it was associated to `oldValue`.
      *
      * @param key the key of the map entry
-     * @param value new value
+     * @param newValue new value
      * @param oldValue expected old value
      * @throws RangeError if key, oldValue or newValue is `null` or `undefined`
      * @returns `true` if the value was replaced
diff --git a/src/proxy/IQueue.ts b/src/proxy/IQueue.ts
@@ -58,7 +58,7 @@ export interface IQueue<E> extends DistributedObject {
     /**
      * Returns `true` if this queue contains the given item.
      * @param item
-     * @return `true` if this queue containse the item, `false` otherwise.
+     * @return `true` if this queue contains the item, `false` otherwise.
      */
     contains(item: E): Promise<boolean>;
 
@@ -108,7 +108,7 @@ export interface IQueue<E> extends DistributedObject {
 
     /**
      * Inserts the item at the end of this queue. It waits to return until
-     * space becomes available if neccessary.
+     * space becomes available if necessary.
      * @param item
      */
     put(item: E): Promise<void>;
@@ -156,7 +156,6 @@ export interface IQueue<E> extends DistributedObject {
     /**
      * Retrieves and removes the head of this queue, waiting if necessary
      * until an element becomes available.
-     * @param item
      * @return head of the queue.
      */
     take(): Promise<E>;
diff --git a/src/proxy/ISet.ts b/src/proxy/ISet.ts
@@ -64,7 +64,7 @@ export interface ISet<E> extends DistributedObject {
      * Checks whether this set contains all elements of given array.
      * @param items
      * @throws {Error} if collection or one of its elements is null or undefined.
-     * @return `tru`e if this set contains all elments of given collection, `false` otherwise.
+     * @return `tru`e if this set contains all elements of given collection, `false` otherwise.
      */
     containsAll(items: E[]): Promise<boolean>;
 
diff --git a/src/proxy/ItemListener.ts b/src/proxy/ItemListener.ts
@@ -34,7 +34,7 @@ export interface ItemListener<E> {
 }
 
 /**
- * Item event hander function.
+ * Item event handler function.
  */
 export type ItemEventListener<E> = (itemEvent: ItemEvent<E>) => void;
 
diff --git a/src/proxy/PNCounter.ts b/src/proxy/PNCounter.ts
@@ -170,7 +170,7 @@ export interface PNCounter extends DistributedObject {
      * @throws `UnsupportedOperationError`  if the cluster version is less
      *                                        than 3.10
      * @throws `ConsistencyLostError`       if the session guarantees have
-     *                                        beenlost
+     *                                        been lost
      */
     getAndIncrement(): Promise<Long>;
 
diff --git a/src/util/IndexUtil.ts b/src/util/IndexUtil.ts
@@ -110,7 +110,7 @@ export class IndexUtil {
     /**
      * Validate attribute name.
      *
-     * @param config Index config.
+     * @param indexName Index name.
      * @param attributeName Attribute name.
      */
     static validateAttribute(indexName: string, attributeName: string): void {
diff --git a/test/integration/backward_compatible/sql/ExecuteTest.js b/test/integration/backward_compatible/sql/ExecuteTest.js
@@ -504,8 +504,8 @@ describe('SqlExecuteTest', function () {
             serviceSpy.callCount.should.be.greaterThanOrEqual(4);
             sinon.restore();
         });
-        // TODO: add update count result type test once it's supported in imdg
-        // TODO: add schema test once it's supported in imdg
+        // TODO: add update count result type test once it's supported in Hazelcast
+        // TODO: add schema test once it's supported in Hazelcast
         it('should return rows when expected result type is rows', async function () {
             const entryCount = 1;
             await populateMap(entryCount);
diff --git a/test/unit/statistics/README.md b/test/unit/statistics/README.md
@@ -1,5 +1,4 @@
-The metrics binary compatibility file is autogenerated using the following
-file from Hazelcast IMDG repository.
+The metrics binary compatibility file is autogenerated using the following file from Hazelcast repository.
 
 https://github.com/hazelcast/hazelcast/blob/master/hazelcast/src/test/java/com/hazelcast/internal/metrics/impl/MetricsCompatibilityFileGenerator.java
 

Original file line number	Diff line number	Diff line change
`@@ -25,8 +25,8 @@ import {DistributedObject} from '../core';`
`25`	`25`	`* failures and network partitions. If a network partition occurs, it remains`
`26`	`26`	`* available on at most one side of the partition.`
`27`	`27`	`*`
`28`		`- * FencedLock works on top of CP sessions. Please refer to CP Session`
`29`		`- * IMDG documentation section for more information.`
	`28`	`+ * FencedLock works on top of CP sessions. Please refer to Hazelcast CP Session`
	`29`	`+ * documentation section for more information.`
`30`	`30`	`*`
`31`	`31`	`* Important note: FencedLock is non-reentrant. Once a caller acquires`
`32`	`32`	`* the lock, it can not acquire the lock reentrantly. So, the next acquire`