Fix JSDoc syntax errors that were causing doc generation errors and a…

…dd minimal docs to demonstrate functionality

Signed-off-by: Frank Hinek <[email protected]>

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`.

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"
   }
 }

src/did/connect/ws-client.js

@@ -1,35 +1,67 @@
+/**
+ * WebSocketClient class for managing WebSocket connections.
+ */
 export class WebSocketClient {
   #port;
   #requestID = 0;
   #socket;
   #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;
     this.#socket = socket;
     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<WebSocketClient>}
+   * 
+   * @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 }));
   }
-}
+}

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
  */
 
 /**

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<Web5SendResponse>} - A promise that resolves to the response object.
    */
   async send(target, request) {
     let { author, data, message } = request;