From b4f31dd5e8e2902d2f20aba4c74975ee66e3ab38 Mon Sep 17 00:00:00 2001 From: Franck Royer Date: Mon, 10 May 2021 15:31:36 +1000 Subject: [PATCH 1/4] Fix typedoc command --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index eb8b176b6c..1c3fdf1e2d 100644 --- a/package.json +++ b/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", From 40fd7ff36579de96590700efa9a00af74aeddf02 Mon Sep 17 00:00:00 2001 From: Franck Royer Date: Mon, 10 May 2021 15:53:05 +1000 Subject: [PATCH 2/4] Use Typedoc comment style --- .cspell.json | 1 + src/lib/chat_message/index.ts | 15 +++++++++++++++ src/lib/waku_relay/relay_heartbeat.ts | 5 +++++ src/lib/waku_store/index.ts | 16 +++++++++++----- src/test_utils/async_fs.ts | 7 +++++++ src/test_utils/constants.ts | 7 +++++++ src/test_utils/index.ts | 7 +++++++ src/test_utils/log_file.ts | 7 +++++++ src/test_utils/nim_waku.ts | 5 +++++ 9 files changed, 65 insertions(+), 5 deletions(-) diff --git a/.cspell.json b/.cspell.json index 03e3041bda..2c619023e7 100644 --- a/.cspell.json +++ b/.cspell.json @@ -42,6 +42,7 @@ "mplex", "muxed", "muxer", + "mvps", "nodekey", "peerhave", "prettierignore", diff --git a/src/lib/chat_message/index.ts b/src/lib/chat_message/index.ts index e12db9462c..04e3389d17 100644 --- a/src/lib/chat_message/index.ts +++ b/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(); } diff --git a/src/lib/waku_relay/relay_heartbeat.ts b/src/lib/waku_relay/relay_heartbeat.ts index 21b81cb83f..054af00c96 100644 --- a/src/lib/waku_relay/relay_heartbeat.ts +++ b/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'; diff --git a/src/lib/waku_store/index.ts b/src/lib/waku_store/index.ts index 1a328cb63c..329265b04e 100644 --- a/src/lib/waku_store/index.ts +++ b/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, diff --git a/src/test_utils/async_fs.ts b/src/test_utils/async_fs.ts index dc671f45ba..fff62e3903 100644 --- a/src/test_utils/async_fs.ts +++ b/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'; diff --git a/src/test_utils/constants.ts b/src/test_utils/constants.ts index dd832689df..152e58b9a2 100644 --- a/src/test_utils/constants.ts +++ b/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); diff --git a/src/test_utils/index.ts b/src/test_utils/index.ts index 59bbdc199b..e97b1a2943 100644 --- a/src/test_utils/index.ts +++ b/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'; diff --git a/src/test_utils/log_file.ts b/src/test_utils/log_file.ts index 6412f39c20..70e5f0aca5 100644 --- a/src/test_utils/log_file.ts +++ b/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'; diff --git a/src/test_utils/nim_waku.ts b/src/test_utils/nim_waku.ts index 19b5725399..bb9040499a 100644 --- a/src/test_utils/nim_waku.ts +++ b/src/test_utils/nim_waku.ts @@ -1,3 +1,8 @@ +/** + * @hidden + * @module + */ + import { ChildProcess, spawn } from 'child_process'; import { randomInt } from 'crypto'; From faf5f46a358b3cecffd6de985f703b4df81adb30 Mon Sep 17 00:00:00 2001 From: Franck Royer Date: Mon, 10 May 2021 16:52:53 +1000 Subject: [PATCH 3/4] Deploy docs on GH Pages --- .github/workflows/deploy-gh-pages.yml | 11 +++++++++++ README.md | 11 +++++++++++ 2 files changed, 22 insertions(+) diff --git a/.github/workflows/deploy-gh-pages.yml b/.github/workflows/deploy-gh-pages.yml index 15c5a2dadd..050a87edb6 100644 --- a/.github/workflows/deploy-gh-pages.yml +++ b/.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 diff --git a/README.md b/README.md index d2b274bb87..6442d6e6f0 100644 --- a/README.md +++ b/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). From c7ffdda926d73b0fde0805ac464e29f5f5c435ea Mon Sep 17 00:00:00 2001 From: Franck Royer Date: Mon, 10 May 2021 21:02:24 +1000 Subject: [PATCH 4/4] Add netlify config --- netlify.toml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 netlify.toml diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 0000000000..aef4684080 --- /dev/null +++ b/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