Improve docs (#519)

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - **Breaking**: Upgrade `libp2p` to `0.36.2` & `libp2p-gossipsub` to `0.13.0`. Some APIs are now async.
+- docs: Various improvements.
+- Ran `npm audit fix`.
 
 ## [0.16.0] - 2022-01-31
 

package.json

@@ -46,7 +46,7 @@
     "watch:build": "tsc -p tsconfig.json -w",
     "watch:test": "nyc --silent mocha --watch",
     "doc": "run-s doc:*",
-    "doc:html": "typedoc --excludeInternal --listInvalidSymbolLinks --exclude **/*.spec.ts --out build/docs src/",
+    "doc:html": "typedoc",
     "doc:cname": "echo 'js-waku.wakuconnect.dev' > build/docs/CNAME",
     "doc:examples": "mkdir -p build/docs/examples",
     "deploy": "node ci/deploy.js",

src/lib/utils.ts

@@ -1,5 +1,8 @@
 import { keccak256, Message } from "js-sha3";
 
+/**
+ * Convert input to a Buffer.
+ */
 export function hexToBuf(hex: string | Buffer | Uint8Array): Buffer {
   if (typeof hex === "string") {
     return Buffer.from(hex.replace(/^0x/i, ""), "hex");
@@ -8,11 +11,17 @@ export function hexToBuf(hex: string | Buffer | Uint8Array): Buffer {
   }
 }
 
+/**
+ * Convert input to hex string (no `0x` prefix).
+ */
 export function bufToHex(buf: Uint8Array | Buffer | ArrayBuffer): string {
   const _buf = Buffer.from(buf);
   return _buf.toString("hex");
 }
 
+/**
+ * Compare both inputs, return true if they represent the same byte array.
+ */
 export function equalByteArrays(
   a: Uint8Array | Buffer | string,
   b: Uint8Array | Buffer | string
@@ -34,6 +43,9 @@ export function equalByteArrays(
   return aBuf.compare(bBuf) === 0;
 }
 
+/**
+ * Return Keccak-256 of the input.
+ */
 export function keccak256Buf(message: Message): Buffer {
   return Buffer.from(keccak256.arrayBuffer(message));
 }

src/lib/waku.ts

@@ -144,9 +144,7 @@ export class Waku {
   }
 
   /**
-   * Create new waku node
-   *
-   * @param options Takes the same options than `Libp2p`.
+   * Create and start new waku node.
    */
   static async create(options?: CreateOptions): Promise<Waku> {
     // Get an object in case options or libp2p are undefined
@@ -296,7 +294,8 @@ export class Waku {
 
   /**
    * Return the local multiaddr with peer id on which libp2p is listening.
-   * @throws if libp2p is not listening on localhost
+   *
+   * @throws if libp2p is not listening on localhost.
    */
   getLocalMultiaddrWithID(): string {
     const localMultiaddr = this.libp2p.multiaddrs.find((addr) =>

src/lib/waku_light_push/index.node.spec.ts

@@ -2,7 +2,7 @@ import { expect } from "chai";
 import debug from "debug";
 
 import { makeLogFileName, NimWaku, NOISE_KEY_1 } from "../../test_utils";
-import { delay } from "../delay";
+import { delay } from "../../test_utils/delay";
 import { Protocols, Waku } from "../waku";
 import { WakuMessage } from "../waku_message";
 

src/lib/waku_message/index.node.spec.ts

@@ -7,7 +7,7 @@ import {
   NOISE_KEY_1,
   WakuRelayMessage,
 } from "../../test_utils";
-import { delay } from "../delay";
+import { delay } from "../../test_utils/delay";
 import { hexToBuf } from "../utils";
 import { Protocols, Waku } from "../waku";
 

src/lib/waku_relay/index.node.spec.ts

@@ -7,7 +7,7 @@ import {
   NOISE_KEY_1,
   NOISE_KEY_2,
 } from "../../test_utils";
-import { delay } from "../delay";
+import { delay } from "../../test_utils/delay";
 import { DefaultPubSubTopic, Protocols, Waku } from "../waku";
 import { DecryptionMethod, WakuMessage } from "../waku_message";
 import {

src/lib/waku_store/index.node.spec.ts

@@ -7,7 +7,7 @@ import {
   NOISE_KEY_1,
   NOISE_KEY_2,
 } from "../../test_utils";
-import { delay } from "../delay";
+import { delay } from "../../test_utils/delay";
 import { Protocols, Waku } from "../waku";
 import { DecryptionMethod, WakuMessage } from "../waku_message";
 import {

src/lib/waku_store/index.ts

@@ -93,6 +93,8 @@ export interface QueryOptions {
 
 /**
  * Implements the [Waku v2 Store protocol](https://rfc.vac.dev/spec/13/).
+ *
+ * The Waku Store protocol can be used to retrieved historical messages.
  */
 export class WakuStore {
   pubSubTopic: string;
@@ -112,10 +114,11 @@ export class WakuStore {
   }
 
   /**
-   * Do a History Query to a Waku Store.
+   * Do a query to a Waku Store to retrieve historical/missed messages.
    *
    * @param contentTopics The content topics to pass to the query, leave empty to
    * retrieve all messages.
+   * @param options Optional parameters.
    *
    * @throws If not able to reach a Waku Store peer to query
    * or if an error is encountered when processing the reply.

src/test_utils/async_fs.ts

@@ -8,7 +8,8 @@
 import fs, { promises as asyncFs } from "fs";
 import { promisify } from "util";
 
-import { delay } from "../lib/delay";
+import { delay } from "./delay";
+
 export const existsAsync = (filepath: string): Promise<void> =>
   asyncFs.access(filepath, fs.constants.F_OK);
 

typedoc.json

@@ -0,0 +1,10 @@
+{
+  "entryPoints": ["./src/index.ts"],
+  "out": "build/docs",
+  "exclude": "**/*.spec.ts",
+  "excludeInternal": true,
+  "validation": {
+    "invalidLink": true,
+    "notExported": true
+  }
+}