Add automated JSDoc documentation generation

.github/workflows/docs-publish.yml

@@ -0,0 +1,92 @@
+# Workflow that deploys project documentation to GitHub Pages
+name: Build and Deploy Docs
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches:
+      - main
+
+  # 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: |
+          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
+        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

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

@@ -0,0 +1,40 @@
+{
+  "opts": {
+    "encoding": "utf8",
+    "destination": "./docs/",
+    "readme": "README-docs.md",
+    "recurse": true,
+    "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": "(^|\\/|\\\\)_"
+  },
+  "sourceType": "module",
+  "tags": {
+    "allowUnknownTags": true,
+    "dictionaries": ["jsdoc","closure"]
+  },
+  "templates": {
+    "cleverLinks": false,
+    "monospaceLinks": false
+  }
+}

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;