Merge #141

141: Use typedoc r=D4nte a=D4nte



Co-authored-by: Franck Royer <franck@status.im>

.cspell.json

@@ -42,6 +42,7 @@
     "mplex",
     "muxed",
     "muxer",
+    "mvps",
     "nodekey",
     "peerhave",
     "prettierignore",

.github/workflows/deploy-gh-pages.yml

@@ -48,3 +48,14 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./examples/web-chat/build
+
+      - name: Generate docs
+        run: npm run doc:html
+
+      - name: Deploy documentation on gh pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          keep_files: true # Do not delete web chat app
+          publish_dir: ./build/docs
+          destination_dir: docs

README.md

@@ -2,6 +2,17 @@
 
 A JavaScript implementation of the [Waku v2 protocol](https://specs.vac.dev/specs/waku/v2/waku-v2).
 
+## Documentation
+
+Latest `main` branch documentation can be found at [https://status-im.github.io/js-waku/docs/](https://status-im.github.io/js-waku/docs/).
+
+Docs can also be generated locally using:
+
+```shell
+npm install
+npm run doc
+```
+
 ## Waku Protocol Support
 
 You can track progress on the [project board](https://github.com/status-im/js-waku/projects/1).

netlify.toml

@@ -0,0 +1,21 @@
+[build]
+publish = "build/html/"
+
+# Default build command.
+command = '''
+npm install
+npm run build
+npm run doc:html
+cd examples/web-chat
+npm install
+npm run build
+cd ../../
+mkdir -p ./build/html
+mv -v examples/web-chat/build ./build/html/js-waku
+mv -v build/docs ./build/html/
+'''
+
+[[redirects]]
+from = "/"
+to = "/js-waku"
+status = 200

package.json

@@ -43,8 +43,8 @@
     "cov:send": "run-s cov:lcov && codecov",
     "cov:check": "nyc report && nyc check-coverage --lines 100 --functions 100 --branches 100",
     "doc": "run-s doc:html && open-cli build/docs/index.html",
-    "doc:html": "typedoc src/ --exclude **/*.spec.ts --target ES6 --mode file --out build/docs",
-    "doc:json": "typedoc src/ --exclude **/*.spec.ts --target ES6 --mode file --json build/docs/typedoc.json",
+    "doc:html": "typedoc --exclude **/*.spec.ts --out build/docs src/",
+    "doc:json": "typedoc src/ --exclude **/*.spec.ts --json build/docs/typedoc.json",
     "doc:publish": "gh-pages -m \"[ci skip] Updates\" -d build/docs",
     "version": "standard-version",
     "reset-hard": "git clean -dfx && git reset --hard && npm i",

src/lib/chat_message/index.ts

@@ -2,6 +2,13 @@ import { Reader } from 'protobufjs/minimal';
 
 import * as proto from '../../proto/chat/v2/chat_message';
 
+/**
+ * ChatMessage is used by the various show case waku apps that demonstrates
+ * waku used as the network layer for chat group applications.
+ *
+ * This is included to help building PoC and MVPs. Apps that aim to be
+ * production ready should use a more appropriate data structure.
+ */
 export class ChatMessage {
   public constructor(public proto: proto.ChatMessage) {}
 
@@ -23,11 +30,19 @@ export class ChatMessage {
     });
   }
 
+  /**
+   * Decode a protobuf payload to a ChatMessage.
+   * @param bytes The payload to decode.
+   */
   static decode(bytes: Uint8Array): ChatMessage {
     const protoMsg = proto.ChatMessage.decode(Reader.create(bytes));
     return new ChatMessage(protoMsg);
   }
 
+  /**
+   * Encode this ChatMessage to a byte array, to be used as a protobuf payload.
+   * @returns The encoded payload.
+   */
   encode(): Uint8Array {
     return proto.ChatMessage.encode(this.proto).finish();
   }

src/lib/waku_relay/relay_heartbeat.ts

@@ -1,3 +1,8 @@
+/**
+ * @hidden
+ * @module
+ */
+
 import Gossipsub from 'libp2p-gossipsub';
 import { Heartbeat } from 'libp2p-gossipsub/src/heartbeat';
 import { shuffle } from 'libp2p-gossipsub/src/utils';

src/lib/waku_store/index.ts

@@ -10,15 +10,21 @@ import { HistoryRPC } from './history_rpc';
 
 export const StoreCodec = '/vac/waku/store/2.0.0-beta3';
 
+/**
+ * Implements the [Waku v2 Store protocol](https://rfc.vac.dev/spec/13/).
+ */
 export class WakuStore {
   constructor(public libp2p: Libp2p) {}
 
   /**
-   * Retrieve history from given peer
-   * @param peerId
-   * @param contentTopics
-   * @param pubsubTopic
-   * @throws if not able to reach peer
+   * Query given peer using Waku Store.
+   *
+   * @param peerId The peer to query.
+   * @param contentTopics The content topics to retrieve, leave empty to
+   * retrieve all messages.
+   * @param pubsubTopic The pubsub topic to retrieve. Currently, all waku nodes
+   * use the same pubsub topic. This is reserved for future applications.
+   * @throws If not able to reach the peer to query.
    */
   async queryHistory(
     peerId: PeerId,

src/test_utils/async_fs.ts

@@ -1,3 +1,10 @@
+/**
+ * Various promisify of fs utilities.
+ *
+ * @hidden
+ * @module
+ */
+
 import fs, { promises as asyncFs } from 'fs';
 import { promisify } from 'util';
 

src/test_utils/constants.ts

@@ -1,2 +1,9 @@
+/**
+ * Some constants for test purposes.
+ *
+ * @hidden
+ * @module
+ */
+
 export const NOISE_KEY_1 = Buffer.alloc(32, 1);
 export const NOISE_KEY_2 = Buffer.alloc(32, 1);

src/test_utils/index.ts

@@ -1,3 +1,10 @@
+/**
+ * A collection of tools to test the WakuJS library.
+ *
+ * @hidden
+ * @module
+ */
+
 export * from './async_fs';
 export * from './constants';
 export * from './log_file';

src/test_utils/log_file.ts

@@ -1,3 +1,10 @@
+/**
+ * Utilities to make it help check nim-waku logs.
+ *
+ * @hidden
+ * @module
+ */
+
 import { Context } from 'mocha';
 import pTimeout from 'p-timeout';
 import { Tail } from 'tail';

src/test_utils/nim_waku.ts

@@ -1,3 +1,8 @@
+/**
+ * @hidden
+ * @module
+ */
+
 import { ChildProcess, spawn } from 'child_process';
 import { randomInt } from 'crypto';