From 8f499b19fac9e5ce1dd4490e381ef22d93158ec4 Mon Sep 17 00:00:00 2001 From: Frank Hinek Date: Sat, 22 Apr 2023 20:29:26 -0400 Subject: [PATCH 1/3] Add JSDoc configuration file and GitHub Actions Workflow Signed-off-by: Frank Hinek --- .github/workflows/docs-publish.yml | 89 ++++++++++++++++++++++++++++++ jsdoc.json | 24 ++++++++ 2 files changed, 113 insertions(+) create mode 100644 .github/workflows/docs-publish.yml create mode 100644 jsdoc.json diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml new file mode 100644 index 000000000..52a154169 --- /dev/null +++ b/.github/workflows/docs-publish.yml @@ -0,0 +1,89 @@ +# Workflow that deploys project documentation to GitHub Pages +name: Build and Deploy Docs + +on: + # Runs on pushes targeting the default branch + push: + branches: + - main + - docs/autogenerate + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + + build: + permissions: + contents: write # to write documentation files to the repo + + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Set up Node.js + uses: actions/setup-node@v3 + with: + node-version: 18 + + - name: Install dependencies + run: | + npm ci + npm i jsdoc + npm i clean-jsdoc-theme + + - name: Generate documentation + run: npx jsdoc -c jsdoc.json + + - name: Upload documentation artifacts + uses: actions/upload-artifact@v3 + with: + name: jsdoc + path: ./docs + + deploy: + # Add a dependency to the build job + needs: build + + # Grant GITHUB_TOKEN the permissions required to make a Pages deployment + permissions: + contents: read # to read from project repo + pages: write # to deploy to Pages + id-token: write # to verify the deployment originates from an appropriate source + + # Deploy to the github-pages environment + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Setup Pages + uses: actions/configure-pages@v3 + + - name: Download JSDoc artifacts + uses: actions/download-artifact@v3 + with: + name: jsdoc + path: ./docs + + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: './docs' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/jsdoc.json b/jsdoc.json new file mode 100644 index 000000000..c22a695a1 --- /dev/null +++ b/jsdoc.json @@ -0,0 +1,24 @@ +{ + "opts": { + "encoding": "utf8", + "destination": "./docs/", + "recurse": true, + "template": "node_modules/clean-jsdoc-theme" + }, + "plugins": [], + "recurseDepth": 10, + "source": { + "include": ["src"], + "includePattern": ".+\\.js(doc|x)?$", + "excludePattern": "(^|\\/|\\\\)_" + }, + "sourceType": "module", + "tags": { + "allowUnknownTags": true, + "dictionaries": ["jsdoc","closure"] + }, + "templates": { + "cleverLinks": false, + "monospaceLinks": false + } +} From 6a1039393e3523806143f3bd7232216f9d3069c0 Mon Sep 17 00:00:00 2001 From: Frank Hinek Date: Sat, 22 Apr 2023 20:55:11 -0400 Subject: [PATCH 2/3] Fix JSDoc syntax errors that were causing doc generation errors and add minimal docs to demonstrate functionality Signed-off-by: Frank Hinek --- README.md | 2 ++ jsdoc.json | 14 ++++++++ src/did/connect/ws-client.js | 66 +++++++++++++++++++++++++++++++++--- src/types.js | 15 +++++--- src/web5.js | 13 ++++++- 5 files changed, 99 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index cf67b5509..ab3574af4 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ possible. ## Docs +[API Reference](https://tbd54566975.github.io/web5-js/) + ### **`new Web5([options])`** Creates an isolated API object for doing Web5 things, split into three main top-level objects: `did`, `dwn`, and `vc`. diff --git a/jsdoc.json b/jsdoc.json index c22a695a1..1505fc5ab 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -20,5 +20,19 @@ "templates": { "cleverLinks": false, "monospaceLinks": false + }, + "theme_opts": { + "base_url": "https://tbd54566975.github.io/web5-js/", + "default_theme": "dark", + "homepageTitle": "API Reference", + "menu": [ + { + "title": "GitHub", + "link": "https://github.com/TBD54566975/web5-js", + "target": "_blank" + } + ], + "search": true, + "title": "Web5 JS SDK" } } diff --git a/src/did/connect/ws-client.js b/src/did/connect/ws-client.js index 49f49a329..7cb2e0cb3 100644 --- a/src/did/connect/ws-client.js +++ b/src/did/connect/ws-client.js @@ -1,3 +1,6 @@ +/** + * WebSocketClient class for managing WebSocket connections. + */ export class WebSocketClient { #port; #requestID = 0; @@ -5,8 +8,10 @@ export class WebSocketClient { #web5; /** - * - * @param {WebSocket} socket + * Creates a new WebSocketClient instance. + * + * @param {WebSocket} socket - A WebSocket instance. + * @param {Web5} web5 - A Web5 instance. */ constructor(socket, web5) { this.#port = (new URL(socket.url)).port; @@ -14,22 +19,49 @@ export class WebSocketClient { this.#web5 = web5; } + /** + * Gets the port number of the WebSocket connection. + * + * @returns {number} The port number. + */ get port() { return this.#port; } + /** + * Checks if the WebSocket connection is open. + * + * @returns {boolean} True if the connection is open, otherwise false. + */ get connected() { return this.#socket.readyState === WebSocket.OPEN; } + /** + * Gets the next request ID and increments the internal counter. + * + * @returns {number} The next request ID. + */ get requestID() { return ++this.#requestID; } + /** + * Adds an event listener to the WebSocket. + * + * @param {string} event - The event type for which the listener is called. + * @param {function} callback - The function to call when the event occurs. + * @param {Object} [options] - Optional configuration parameters for the event listener. + */ addEventListener(event, callback, options = undefined) { this.#socket.addEventListener(event, callback, options); } + /** + * Closes the WebSocket connection and resets the instance. + * + * @returns {boolean} True if the connection was closed successfully, otherwise false. + */ close() { if (!this.connected) { return false; @@ -43,10 +75,17 @@ export class WebSocketClient { } /** + * Creates a new WebSocketClient instance by connecting to the provided URL. * - * @param {string} host protocol://hostname or protocol://hostname:port to connect to + * @param {string} url The WebSocket server URL to connect to.protocol://hostname or protocol://hostname:port to connect to * @param {Web5} web5 Web5 instance - * @returns + * @returns {Promise} + * + * @example + * const web5 = new Web5(); + * const url = 'ws://localhost:8080'; + * + * const wsClient = await WebSocketClient.create(url, web5); */ static async create(url, web5) { return new Promise((resolve, _reject) => { @@ -59,15 +98,32 @@ export class WebSocketClient { }); } + /** + * Sets the onmessage event listener for the WebSocket. + * + * @param {function} callback - The function to call when a message is received. + */ onmessage(callback) { this.#socket.onmessage = callback; } + /** + * Removes an event listener from the WebSocket. + * + * @param {string} event - The event type for which the listener was called. + * @param {function} callback - The listener function to remove. + */ removeEventListener(event, callback) { this.#socket.removeEventListener(event, callback); } + /** + * Transmits JSON RPC Request using the WebSocket connection + * + * @param {string} method - The method name to be called on the server. + * @param {Object} [params] - The parameters to be passed to the method (optional). + */ sendRequest(method, params = undefined) { this.#socket.send(JSON.stringify({ id: this.requestID, method, params })); } -} \ No newline at end of file +} diff --git a/src/types.js b/src/types.js index 879bc159b..e19e6a04c 100644 --- a/src/types.js +++ b/src/types.js @@ -79,8 +79,9 @@ */ /** - * @typedef {BaseMessage & Object} ProtocolsConfigureMessage + * @typedef {Object} ProtocolsConfigureMessage * @property {ProtocolsConfigureDescriptor} descriptor + * @augments BaseMessage */ /** @@ -93,8 +94,9 @@ */ /** - * @typedef {BaseMessage & Object} ProtocolsQueryMessage + * @typedef {Object} ProtocolsQueryMessage * @property {ProtocolsQueryDescriptor} descriptor + * @augments BaseMessage */ /** @@ -115,11 +117,12 @@ */ /** - * @typedef {BaseMessage & Object} RecordsWriteMessage + * @typedef {Object} RecordsWriteMessage * @property {string} recordId * @property {string} [contextId] * @property {RecordsWriteDescriptor} descriptor * @property {GeneralJws} [attestation] + * @augments BaseMessage */ /** @@ -185,8 +188,9 @@ */ /** - * @typedef {BaseMessage & Object} RecordsQueryMessage + * @typedef {Object} RecordsQueryMessage * @property {RecordsQueryDescriptor} descriptor + * @augments BaseMessage */ /** @@ -204,8 +208,9 @@ */ /** - * @typedef {BaseMessage & Object} RecordsDeleteMessage + * @typedef {Object} RecordsDeleteMessage * @property {RecordsDeleteDescriptor} descriptor + * @augments BaseMessage */ /** diff --git a/src/web5.js b/src/web5.js index 767c6e468..df30d1450 100644 --- a/src/web5.js +++ b/src/web5.js @@ -4,11 +4,20 @@ import { AppTransport } from './transport/app-transport.js'; import { HttpTransport } from './transport/http-transport.js'; import { isUnsignedMessage, parseUrl } from './utils.js'; +/** + * Provides a high-level interface for working with decentralized + * web nodes (DWNs), decentralized identifiers (DIDs), and + * network services. + */ export class Web5 extends EventTarget { #dwn; #did; #transports; + /** + * Constructs a new Web5 instance with the provided options. + * @param {Object} [options] - Optional configuration options. + */ constructor(options = { }) { super(); @@ -34,12 +43,14 @@ export class Web5 extends EventTarget { } /** + * Sends a request message to the specified target DID. + * * @param {string} target The DID to send the message to. * @param {object} request - Object containing the request parameters. * @param {string} request.author - The DID of the author of the message. * @param {*} request.data - The message data (if any). * @param {object} request.message - The DWeb message. - * @returns Promise + * @returns {Promise} - A promise that resolves to the response object. */ async send(target, request) { let { author, data, message } = request; From cc556df59fcd404b6f023c85640480feb149fd1f Mon Sep 17 00:00:00 2001 From: Frank Hinek Date: Sun, 23 Apr 2023 07:34:49 -0400 Subject: [PATCH 3/3] Improve generated doc site styling Signed-off-by: Frank Hinek --- .github/workflows/docs-publish.yml | 9 ++++-- jsdoc.json | 46 ++++++++++++++++-------------- 2 files changed, 30 insertions(+), 25 deletions(-) diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml index 52a154169..d39cf11f8 100644 --- a/.github/workflows/docs-publish.yml +++ b/.github/workflows/docs-publish.yml @@ -6,7 +6,6 @@ on: push: branches: - main - - docs/autogenerate # Allows you to run this workflow manually from the Actions tab workflow_dispatch: @@ -35,13 +34,17 @@ jobs: node-version: 18 - name: Install dependencies - run: | + run: | npm ci npm i jsdoc npm i clean-jsdoc-theme - name: Generate documentation - run: npx jsdoc -c jsdoc.json + run: | + echo "# Web5 JS SDK" > README-docs.md + echo "Select from the menu on the left to view API reference documentation." >> README-docs.md + npx jsdoc -c jsdoc.json + curl -o docs/favicon.ico https://developer.tbd.website/img/favicon.ico - name: Upload documentation artifacts uses: actions/upload-artifact@v3 diff --git a/jsdoc.json b/jsdoc.json index 1505fc5ab..56ae93fe2 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -2,37 +2,39 @@ "opts": { "encoding": "utf8", "destination": "./docs/", + "readme": "README-docs.md", "recurse": true, - "template": "node_modules/clean-jsdoc-theme" + "template": "node_modules/clean-jsdoc-theme", + "theme_opts": { + "base_url": "https://tbd54566975.github.io/web5-js/", + "default_theme": "dark", + "favicon": "favicon.ico", + "homepageTitle": "Web5 JS API Reference", + "menu": [ + { + "title": "GitHub", + "link": "https://github.com/TBD54566975/web5-js", + "target": "_blank" + } + ], + "search": true, + "title": "API Reference" + } }, "plugins": [], "recurseDepth": 10, "source": { - "include": ["src"], - "includePattern": ".+\\.js(doc|x)?$", - "excludePattern": "(^|\\/|\\\\)_" + "include": ["src"], + "includePattern": ".+\\.js(doc|x)?$", + "excludePattern": "(^|\\/|\\\\)_" }, "sourceType": "module", "tags": { - "allowUnknownTags": true, - "dictionaries": ["jsdoc","closure"] + "allowUnknownTags": true, + "dictionaries": ["jsdoc","closure"] }, "templates": { - "cleverLinks": false, - "monospaceLinks": false - }, - "theme_opts": { - "base_url": "https://tbd54566975.github.io/web5-js/", - "default_theme": "dark", - "homepageTitle": "API Reference", - "menu": [ - { - "title": "GitHub", - "link": "https://github.com/TBD54566975/web5-js", - "target": "_blank" - } - ], - "search": true, - "title": "Web5 JS SDK" + "cleverLinks": false, + "monospaceLinks": false } }