Enable jsdoc lint for classes and methods

.eslintrc.json

@@ -16,6 +16,18 @@
     "@typescript-eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }],
 
     "jsdoc/require-description": 1,
+    "jsdoc/require-jsdoc": [
+      "error",
+      {
+        "require": {
+          "FunctionDeclaration": true,
+          "MethodDefinition": true,
+          "ClassDeclaration": true,
+          "ArrowFunctionExpression": false,
+          "FunctionExpression": false
+        }
+      }
+    ],
     "jsdoc/require-throws": 1,
 
     "jsdoc/require-param-type": 0,

src/client.ts

@@ -331,6 +331,11 @@ export class SkynetClient {
   // Private Methods
   // ===============
 
+  /**
+   * Make a request to resolve the provided `initialPortalUrl`.
+   *
+   * @returns - The portal URL.
+   */
   protected async resolvePortalUrl(): Promise<string> {
     const response = await this.executeRequest({
       ...this.customOptions,

src/mysky/connector.ts

@@ -31,7 +31,20 @@ export const DEFAULT_CONNECTOR_OPTIONS = {
   handshakeAttemptsInterval: defaultHandshakeAttemptsInterval,
 };
 
+/**
+ * The object that connects to a child iframe and keeps track of information
+ * about it.
+ */
 export class Connector {
+  /**
+   * Creates a `Connector`.
+   *
+   * @param url - The iframe URL.
+   * @param client - The Skynet Client.
+   * @param childFrame - The iframe handle.
+   * @param connection - The postmessage handshake connection.
+   * @param options - The custom options.
+   */
   constructor(
     public url: string,
     public client: SkynetClient,
@@ -42,6 +55,14 @@ export class Connector {
 
   // Static initializer
 
+  /**
+   * Initializes a `Connector` instance.
+   *
+   * @param client - The Skynet Client.
+   * @param domain - The MySky domain to open.
+   * @param [customOptions] - Additional settings that can optionally be set.
+   * @returns - The `Connector`.
+   */
   static async init(client: SkynetClient, domain: string, customOptions?: CustomConnectorOptions): Promise<Connector> {
     const opts = { ...DEFAULT_CONNECTOR_OPTIONS, ...customOptions };
 
@@ -80,6 +101,13 @@ export class Connector {
     return new Connector(domainUrl, client, childFrame, connection, opts);
   }
 
+  /**
+   * Calls the given method with the given arguments.
+   *
+   * @param method - The remote method to call over the connection.
+   * @param args - The list of optional arguments.
+   * @returns - The result of the call.
+   */
   async call(method: string, ...args: unknown[]): Promise<unknown> {
     return this.connection.remoteHandle().call(method, ...args);
   }

src/mysky/dac.ts

@@ -5,18 +5,41 @@ import { Permission } from "skynet-mysky-utils";
 import { SkynetClient } from "../client";
 import { Connector, CustomConnectorOptions } from "./connector";
 
+/**
+ * The base DAC class with base and required methods.
+ */
 export abstract class DacLibrary {
   protected connector?: Connector;
 
+  /**
+   * Constructs the DAC.
+   *
+   * @param dacDomain - The domain of the DAC.
+   */
   public constructor(protected dacDomain: string) {}
 
+  /**
+   * Initializes the `Connector` with the DAC iframe and calls `init` on the
+   * DAC.
+   *
+   * @param client - The Skynet Client.
+   * @param customOptions - The custom options.
+   */
   public async init(client: SkynetClient, customOptions: CustomConnectorOptions): Promise<void> {
     this.connector = await Connector.init(client, this.dacDomain, customOptions);
     await this.connector.connection.remoteHandle().call("init");
   }
 
+  /**
+   * Returns the permissions required by the DAC.
+   *
+   * @returns - The DAC permissions.
+   */
   abstract getPermissions(): Permission[];
 
+  /**
+   * The hook to run on user login.
+   */
   async onUserLogin(): Promise<void> {
     if (!this.connector) {
       throw new Error("init was not called");

src/mysky/index.ts

@@ -116,6 +116,10 @@ export async function loadMySky(
   return mySky;
 }
 
+/**
+ * The singleton object that allows skapp developers to initialize and
+ * communicate with MySky.
+ */
 export class MySky {
   static instance: MySky | null = null;
 
@@ -132,6 +136,14 @@ export class MySky {
   // Constructors
   // ============
 
+  /**
+   * Creates a `MySky` instance.
+   *
+   * @param connector - The `Connector` object.
+   * @param permissions - The initial requested permissions.
+   * @param hostDomain - The domain of the host skapp.
+   * @param currentPortalUrl - The URL of the current portal. This is the portal that the skapp is running on, not the portal that may have been requested by the developer when creating a `SkynetClient`.
+   */
   constructor(
     protected connector: Connector,
     permissions: Permission[],
@@ -141,6 +153,14 @@ export class MySky {
     this.pendingPermissions = permissions;
   }
 
+  /**
+   * Initializes MySky and returns a `MySky` instance.
+   *
+   * @param client - The Skynet Client.
+   * @param [skappDomain] - The domain of the host skapp.
+   * @param [customOptions] - Additional settings that can optionally be set.
+   * @returns - A `MySky` instance.
+   */
   static async New(client: SkynetClient, skappDomain?: string, customOptions?: CustomConnectorOptions): Promise<MySky> {
     const opts = { ...DEFAULT_CONNECTOR_OPTIONS, ...customOptions };
 
@@ -219,6 +239,11 @@ export class MySky {
     await Promise.all(promises);
   }
 
+  /**
+   * Adds the given permissions to the list of pending permissions.
+   *
+   * @param permissions - The list of permissions to add.
+   */
   async addPermissions(...permissions: Permission[]): Promise<void> {
     this.pendingPermissions.push(...permissions);
   }
@@ -276,6 +301,11 @@ export class MySky {
   }
 
   // TODO: Document what this does exactly.
+  /**
+   * Log out the user.
+   *
+   * @returns - An empty promise.
+   */
   async logout(): Promise<void> {
     return await this.connector.connection.remoteHandle().call("logout");
   }
@@ -353,6 +383,11 @@ export class MySky {
     return loggedIn;
   }
 
+  /**
+   * Returns the user ID (i.e. same as the user's public key).
+   *
+   * @returns - The hex-encoded user ID.
+   */
   async userID(): Promise<string> {
     return await this.connector.connection.remoteHandle().call("userID");
   }
@@ -754,11 +789,24 @@ export class MySky {
   // Internal Methods
   // ================
 
+  /**
+   * Catches any errors returned from the UI and dispatches them in the current
+   * window. This is how we bubble up errors from the MySky UI window to the
+   * skapp.
+   *
+   * @param errorMsg - The error message.
+   */
   protected async catchError(errorMsg: string): Promise<void> {
     const event = new CustomEvent(dispatchedErrorEvent, { detail: errorMsg });
     window.dispatchEvent(event);
   }
 
+  /**
+   * Launches the MySky UI popup window.
+   *
+   * @returns - The window handle.
+   * @throws - Will throw if the window could not be opened.
+   */
   protected launchUI(): Window {
     const mySkyUrl = new URL(this.connector.url);
     mySkyUrl.pathname = mySkyUiRelativeUrl;
@@ -774,6 +822,12 @@ export class MySky {
     return childWindow;
   }
 
+  /**
+   * Connects to the MySky UI window by establishing a postmessage handshake.
+   *
+   * @param childWindow - The MySky UI window.
+   * @returns - The `Connection` with the other window.
+   */
   protected async connectUi(childWindow: Window): Promise<Connection> {
     const options = this.connector.options;
 
@@ -797,10 +851,20 @@ export class MySky {
     return connection;
   }
 
+  /**
+   * Gets the preferred portal from MySky, or `null` if not set.
+   *
+   * @returns - The preferred portal if set.
+   */
   protected async getPreferredPortal(): Promise<string | null> {
     return await this.connector.connection.remoteHandle().call("getPreferredPortal");
   }
 
+  /**
+   * Loads the given DAC.
+   *
+   * @param dac - The dac to load.
+   */
   protected async loadDac(dac: DacLibrary): Promise<void> {
     // Initialize DAC.
     await dac.init(this.connector.client, this.connector.options);
@@ -874,7 +938,7 @@ export class MySky {
     const preferredPortalUrl = await this.getPreferredPortal();
     if (preferredPortalUrl !== null && shouldRedirectToPreferredPortalUrl(currentUrl, preferredPortalUrl)) {
       // Redirect.
-      const newUrl = await getRedirectUrlOnPreferredPortal(
+      const newUrl = getRedirectUrlOnPreferredPortal(
         this.currentPortalUrl,
         window.location.hostname,
         preferredPortalUrl
@@ -883,10 +947,24 @@ export class MySky {
     }
   }
 
+  /**
+   * Asks MySky to sign the non-encrypted registry entry.
+   *
+   * @param entry - The non-encrypted registry entry.
+   * @param path - The MySky path.
+   * @returns - The signature.
+   */
   protected async signRegistryEntry(entry: RegistryEntry, path: string): Promise<Signature> {
     return await this.connector.connection.remoteHandle().call("signRegistryEntry", entry, path);
   }
 
+  /**
+   * Asks MySky to sign the encrypted registry entry.
+   *
+   * @param entry - The encrypted registry entry.
+   * @param path - The MySky path.
+   * @returns - The signature.
+   */
   protected async signEncryptedRegistryEntry(entry: RegistryEntry, path: string): Promise<Signature> {
     return await this.connector.connection.remoteHandle().call("signEncryptedRegistryEntry", entry, path);
   }

src/mysky/tweak.ts

@@ -15,17 +15,30 @@ export function deriveDiscoverableFileTweak(path: string): string {
   return toHexString(bytes);
 }
 
+/**
+ * The tweak for the discoverable bucket for the given path.
+ */
 export class DiscoverableBucketTweak {
   version: number;
   path: Array<Uint8Array>;
 
+  /**
+   * Creates a new `DiscoverableBucketTweak`.
+   *
+   * @param path - The MySky data path.
+   */
   constructor(path: string) {
     const paths = splitPath(path);
     const pathHashes = paths.map(hashPathComponent);
     this.version = DISCOVERABLE_BUCKET_TWEAK_VERSION;
     this.path = pathHashes;
   }
 
+  /**
+   * Encodes the tweak into a byte array.
+   *
+   * @returns - The encoded byte array.
+   */
   encode(): Uint8Array {
     const size = 1 + 32 * this.path.length;
     const buf = new Uint8Array(size);
@@ -39,6 +52,11 @@ export class DiscoverableBucketTweak {
     return buf;
   }
 
+  /**
+   * Gets the hash of the tweak.
+   *
+   * @returns - The hash.
+   */
   getHash(): Uint8Array {
     const encoding = this.encode();
     return hashAll(encoding);

src/request.ts

@@ -76,11 +76,22 @@ export async function buildRequestUrl(
   return url;
 }
 
+/**
+ * The error type returned by `executeRequestError`.
+ */
 export class ExecuteRequestError extends Error {
   originalError: AxiosError;
   responseStatus: number | null;
   responseMessage: string | null;
 
+  /**
+   * Creates an `ExecuteRequestError`.
+   *
+   * @param message - The error message.
+   * @param axiosError - The original axios error.
+   * @param responseStatus - The response status, if found in the original error.
+   * @param responseMessage - The response message, if found in the original error.
+   */
   constructor(message: string, axiosError: AxiosError, responseStatus: number | null, responseMessage: string | null) {
     super(message);
     this.originalError = axiosError;

src/revision_cache.ts

@@ -10,6 +10,9 @@ export class RevisionNumberCache {
   private mutex: Mutex;
   private cache: { [key: string]: CachedRevisionNumber };
 
+  /**
+   * Creates the `RevisionNumberCache`.
+   */
   constructor() {
     this.mutex = new Mutex();
     this.cache = {};
@@ -86,6 +89,9 @@ export class CachedRevisionNumber {
   mutex: Mutex;
   revision: bigint;
 
+  /**
+   * Creates a `CachedRevisionNumber`.
+   */
   constructor() {
     this.mutex = new Mutex();
     this.revision = BigInt(-1);