docs: Update documentation for JSON-RPC methods

packages/snaps-sdk/src/types/methods/cancel-background-event.ts

@@ -1,5 +1,6 @@
 /**
- * The request parameters for the `snap_cancelBackgroundEvent` method.
+ * An object containing the parameters for the `snap_cancelBackgroundEvent`
+ * method.
  */
 export type CancelBackgroundEventParams = {
   /**
@@ -9,8 +10,6 @@ export type CancelBackgroundEventParams = {
 };
 
 /**
- * The result returned for the `snap_cancelBackgroundEvent` method.
- *
- * This method does not return anything.
+ * This method does not return any data, so the result is always `null`.
  */
 export type CancelBackgroundEventResult = null;

packages/snaps-sdk/src/types/methods/clear-state.ts

@@ -1,5 +1,5 @@
 /**
- * The request parameters for the `snap_clearState` method.
+ * An object containing the parameters for the `snap_clearState` method.
  *
  * @property encrypted - Whether to use the separate encrypted state, or the
  * unencrypted state. Defaults to the encrypted state. Encrypted state can only
@@ -11,6 +11,6 @@ export type ClearStateParams = {
 };
 
 /**
- * The result returned by the `snap_clearState` method.
+ * This method does not return any data, so the result is always `null`.
  */
 export type ClearStateResult = null;

packages/snaps-sdk/src/types/methods/close-web-socket.ts

@@ -1,5 +1,5 @@
 /**
- * The request parameters for the `snap_closeWebSocket` method.
+ * An object containing the parameters for the `snap_closeWebSocket` method.
  *
  * @property id - The ID of the WebSocket connection to close.
  */
@@ -8,6 +8,6 @@ export type CloseWebSocketParams = {
 };
 
 /**
- * The result returned by the `snap_closeWebSocket` method.
+ * This method does not return any data, so the result is always `null`.
  */
 export type CloseWebSocketResult = null;

packages/snaps-sdk/src/types/methods/create-interface.ts

@@ -1,7 +1,7 @@
 import type { ComponentOrElement, InterfaceContext } from '..';
 
 /**
- * The request parameters for the `snap_createInterface` method.
+ * An object containing the parameters for the `snap_createInterface` method.
  */
 export type CreateInterfaceParams = {
   /**

packages/snaps-sdk/src/types/methods/dialog.ts

@@ -25,78 +25,103 @@ export type DefaultDialog =
 
 /**
  * An alert dialog.
- *
- * @property type - The type of dialog. Must be `alert`.
- * @property content - The content to display in the dialog.
- * @property id - The Snap interface ID.
  */
 export type AlertDialog =
   | {
+      /**
+       * The literal string "alert" to indicate that this is an alert dialog.
+       */
       type: EnumToUnion<DialogType.Alert>;
+
+      /**
+       * The content to display in the alert dialog.
+       */
       content: ComponentOrElement;
     }
   | {
+      /**
+       * The literal string "alert" to indicate that this is an alert dialog.
+       */
       type: EnumToUnion<DialogType.Alert>;
+
+      /**
+       * The Snap interface ID, which can be used to display a previously
+       * created interface. See [`snap_createInterface`](https://docs.metamask.io/snaps/reference/snaps-api/snap_createinterface).
+       */
       id: string;
     };
 
 /**
  * A confirmation dialog.
- *
- * @property type - The type of dialog. Must be `confirmation`.
- * @property content - The content to display in the dialog.
- * @property id - The Snap interface ID.
  */
 export type ConfirmationDialog =
   | {
+      /**
+       * The literal string "confirmation" to indicate that this is a
+       * confirmation dialog.
+       */
       type: EnumToUnion<DialogType.Confirmation>;
+
+      /**
+       * The content to display in the confirmation dialog.
+       */
       content: ComponentOrElement;
     }
   | {
+      /**
+       * The literal string "confirmation" to indicate that this is a
+       * confirmation dialog.
+       */
       type: EnumToUnion<DialogType.Confirmation>;
+
+      /**
+       * The Snap interface ID, which can be used to display a previously
+       * created interface. See [`snap_createInterface`](https://docs.metamask.io/snaps/reference/snaps-api/snap_createinterface).
+       */
       id: string;
     };
 
 /**
  * A prompt dialog.
- *
- * @property type - The type of dialog. Must be `prompt`.
- * @property content - The content to display in the dialog.
- * @property id - The Snap interface ID.
- * @property placeholder - An optional placeholder text to display in the text
- * input.
  */
 export type PromptDialog =
   | {
+      /**
+       * The literal string "prompt" to indicate that this is a prompt dialog.
+       */
       type: EnumToUnion<DialogType.Prompt>;
+
+      /**
+       * The content to display in the prompt dialog.
+       */
       content: ComponentOrElement;
+
+      /**
+       * An optional placeholder text to display in the text input.
+       */
       placeholder?: string;
     }
   | {
+      /**
+       * The literal string "prompt" to indicate that this is a prompt dialog.
+       */
       type: EnumToUnion<DialogType.Prompt>;
+
+      /**
+       * The Snap interface ID, which can be used to display a previously
+       * created interface. See [`snap_createInterface`](https://docs.metamask.io/snaps/reference/snaps-api/snap_createinterface).
+       */
       id: string;
+
+      /**
+       * An optional placeholder text to display in the text input.
+       */
       placeholder?: string;
     };
 
-/* eslint-disable jsdoc/check-indentation */
 /**
  * An object containing the contents of the dialog.
  *
- * - `type` - The type of dialog. Not providing a type will create a fully
- * [custom dialog](https://docs.metamask.io/snaps/features/custom-ui/dialogs/#display-a-custom-dialog).
- * Possible values are:
- *   - `alert` - An alert that can only be acknowledged.
- *   - `confirmation` - A confirmation that can be accepted or rejected.
- *   - `prompt` - A prompt where the user can enter a text response.
- *
- * - One of:
- *   - `content` - The content of the alert, as a
- * [custom UI](https://docs.metamask.io/snaps/features/custom-ui/) component.
- *   - `id` - The ID of an
- * [interactive interface](https://docs.metamask.io/snaps/reference/snaps-api/snap_createinterface).
- * - `placeholder` - An optional placeholder text to display in the dialog. Only
- * applicable for the `prompt` dialog.
- *
  * @property type - The type of dialog to display.
  * @property content - The content to display in the dialog.
  * @property id - The Snap interface ID.
@@ -108,7 +133,6 @@ export type DialogParams =
   | ConfirmationDialog
   | PromptDialog
   | DefaultDialog;
-/* eslint-enable jsdoc/check-indentation */
 
 /**
  * - If the dialog is an `alert`, the result is `null`.

packages/snaps-sdk/src/types/methods/get-background-events.ts

@@ -22,23 +22,35 @@ export type BackgroundEvent = {
   snapId: SnapId;
   date: string;
   request: {
+    /**
+     * The method to be called when the event is fired.
+     */
     method: string;
+
+    /**
+     * The optional JSON-RPC version for the request, which is always "2.0" if
+     * provided.
+     */
     jsonrpc?: '2.0' | undefined;
+
+    /**
+     * The optional ID for the request.
+     */
     id?: string | number | null | undefined;
+
+    /**
+     * The optional parameters for the request.
+     */
     params?: Json[] | Record<string, Json> | undefined;
   };
 };
 
 /**
- * The result returned by the `snap_getBackgroundEvents` method.
- *
- * It consists of an array background events (if any) for a snap.
+ * An array of scheduled background events.
  */
 export type GetBackgroundEventsResult = BackgroundEvent[];
 
 /**
- * The request parameters for the `snap_getBackgroundEvents` method.
- *
  * This method does not accept any parameters.
  */
 export type GetBackgroundEventsParams = never;

packages/snaps-sdk/src/types/methods/get-bip32-entropy.ts

@@ -3,7 +3,7 @@ import type { JsonSLIP10Node } from '@metamask/key-tree';
 import type { Bip32Entropy } from '../permissions';
 
 /**
- * The request parameters for the `snap_getBip32Entropy` method.
+ * An object containing the parameters for the `snap_getBip32Entropy` method.
  */
 export type GetBip32EntropyParams = Bip32Entropy & {
   /**
@@ -15,8 +15,6 @@ export type GetBip32EntropyParams = Bip32Entropy & {
 };
 
 /**
- * The result returned by the `snap_getBip32Entropy` method.
- *
- * @see https://github.com/MetaMask/key-tree#usage
+ * A JSON-serializable SLIP-10 node containing the requested BIP-32 entropy.
  */
 export type GetBip32EntropyResult = JsonSLIP10Node;

packages/snaps-sdk/src/types/methods/get-bip32-public-key.ts

@@ -1,7 +1,7 @@
 import type { Bip32Entropy } from '../permissions';
 
 /**
- * The request parameters for the `snap_getBip32PublicKey` method.
+ * An object containing the parameters for the `snap_getBip32PublicKey` method.
  */
 export type GetBip32PublicKeyParams = Bip32Entropy & {
   /**

packages/snaps-sdk/src/types/methods/get-bip44-entropy.ts

@@ -3,7 +3,7 @@ import type { JsonBIP44CoinTypeNode } from '@metamask/key-tree';
 import type { Bip44Entropy } from '../permissions';
 
 /**
- * The request parameters for the `snap_getBip44Entropy` method.
+ * An object containing the parameters for the `snap_getBip44Entropy` method.
  */
 export type GetBip44EntropyParams = Bip44Entropy & {
   /**
@@ -15,8 +15,7 @@ export type GetBip44EntropyParams = Bip44Entropy & {
 };
 
 /**
- * The result returned by the `snap_getBip44Entropy` method.
- *
- * @see https://github.com/MetaMask/key-tree#usage
+ * A JSON-serializable BIP-44 coin type node containing the requested BIP-44
+ * entropy.
  */
 export type GetBip44EntropyResult = JsonBIP44CoinTypeNode;

packages/snaps-sdk/src/types/methods/get-client-status.ts

@@ -1,30 +1,31 @@
 /**
- * The request parameters for the `snap_getClientStatus` method.
- *
  * This method does not accept any parameters.
  */
 export type GetClientStatusParams = never;
 
 /**
- * The result returned by the `snap_getClientStatus` method.
- *
- * It returns an object containing useful information about the client.
+ * An object containing information about the client that the Snap is running
+ * in.
  */
 export type GetClientStatusResult = {
   /**
    * The semantic version of the client that the Snap is running in.
    */
   clientVersion: string;
+
   /**
    * The Snaps Platform version that the client is running.
    */
   platformVersion: string;
+
   /**
    * A boolean flag that indicates whether the client is locked or not.
    */
   locked: boolean;
+
   /**
-   * A boolean flag that indicates whether the client is active or not.
+   * A boolean flag that indicates whether the client is active or not. The
+   * client is considered active if the client is visible.
    */
   active: boolean;
 };

packages/snaps-sdk/src/types/methods/get-entropy.ts

@@ -1,7 +1,7 @@
 import type { Hex } from '@metamask/utils';
 
 /**
- * The request parameters for the `snap_getEntropy` method.
+ * An object containing the parameters for the `snap_getEntropy` method.
  */
 export type GetEntropyParams = {
   /**

packages/snaps-sdk/src/types/methods/get-file.ts

@@ -10,7 +10,7 @@ export enum AuxiliaryFileEncoding {
 }
 
 /**
- * The request parameters for the `snap_getFile` method.
+ * An object containing the parameters for the `snap_getFile` method.
  */
 export type GetFileParams = {
   /**

packages/snaps-sdk/src/types/methods/get-interface-context.ts

@@ -1,7 +1,8 @@
 import type { InterfaceContext } from '../interface';
 
 /**
- * The request parameters for the `snap_getInterfaceContext` method.
+ * An object containing the parameters for the `snap_getInterfaceContext`
+ * method.
  *
  * @property id - The interface ID.
  */
@@ -10,6 +11,7 @@ export type GetInterfaceContextParams = {
 };
 
 /**
- * The context for the given interface.
+ * The context for the given interface. May be `null` if no context was provided
+ * when the interface was created.
  */
 export type GetInterfaceContextResult = InterfaceContext | null;

packages/snaps-sdk/src/types/methods/get-interface-state.ts

@@ -1,7 +1,7 @@
 import type { InterfaceState } from '../interface';
 
 /**
- * The request parameters for the `snap_getInterfaceState` method.
+ * An object containing the parameters for the `snap_getInterfaceState` method.
  *
  * @property id - The interface ID.
  */

packages/snaps-sdk/src/types/methods/get-locale.ts

@@ -1,6 +1,4 @@
 /**
- * The request parameters for the `snap_getLocale` method.
- *
  * This method does not accept any parameters.
  */
 export type GetLocaleParams = never;