From 6a1039393e3523806143f3bd7232216f9d3069c0 Mon Sep 17 00:00:00 2001 From: Frank Hinek Date: Sat, 22 Apr 2023 20:55:11 -0400 Subject: [PATCH] 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;