chore(docs): Add descriptions for config parameters

neet · neet · commit ade9eb2f6bfa · 2024-02-24T17:26:24.000+09:00
diff --git a/src/adapters/clients.ts b/src/adapters/clients.ts
@@ -18,6 +18,16 @@ import { SerializerNativeImpl } from "./serializers";
 import { WebSocketConnectorImpl } from "./ws";
 
 interface LogConfigProps {
+  /**
+   * Log level for the client.
+   *
+   * - `debug`: Log everything.
+   * - `info`: Log important information.
+   * - `warn`: Log warnings.
+   * - `error`: Log errors.
+   *
+   * Defaults to `warn`.
+   */
   readonly log?: LogType;
 }
 
@@ -52,7 +62,11 @@ export const createOAuthAPIClient = (
 };
 
 interface WebSocketCustomImplProps {
-  /** Custom WebSocket implementation. In Deno, you can use `WebSocket` to avoid potential errors. */
+  /**
+   * Custom WebSocket implementation. In Deno, you can use `WebSocket` to avoid potential errors.
+   *
+   * Defaults to `window.WebSocket`.
+   */
   readonly implementation?: unknown;
 }
 
diff --git a/src/adapters/config/http-config.ts b/src/adapters/config/http-config.ts
@@ -5,9 +5,30 @@ import { mergeHeadersInit } from "./merge-headers-init";
 const DEFAULT_TIMEOUT_MS = 1000 * 300;
 
 export interface MastoHttpConfigProps {
+  /**
+   * REST API URL for your Mastodon instance.
+   */
   readonly url: string;
+
+  /**
+   * Access token for the REST API.
+   *
+   * Please refer to the [quickstart](https://github.com/neet/masto.js?tab=readme-ov-file#quick-start) for how to get an access token.
+   */
   readonly accessToken?: string;
+
+  /**
+   * Timeout in milliseconds.
+   *
+   * Defaults to 1000 * 300 = 300 seconds.
+   */
   readonly timeout?: number;
+
+  /**
+   * Additional options for the `fetch` function.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch
+   */
   readonly requestInit?: Omit<RequestInit, "body" | "method">;
 }
 
diff --git a/src/adapters/config/web-socket-config.ts b/src/adapters/config/web-socket-config.ts
@@ -1,9 +1,55 @@
 import { type Serializer, type WebSocketConfig } from "../../interfaces";
 
 export interface WebSocketConfigProps {
+  /**
+   * Streaming API URL for your Mastodon instance.
+   *
+   * Note that this is often different from the REST API URL.
+   *
+   * If you are not sure which URL to use, you can obtain it via the following script:
+   *
+   * @example
+   * ```ts
+   * import { createRestAPIClient, createStreamingAPIClient } from "masto";
+   *
+   * const rest = createRestAPIClient({
+   *   url: "https://example.com",
+   * });
+   *
+   * const instance = await rest.v2.instance.fetch();
+   *
+   * const streaming = createStreamingAPIClient({
+   *  streamingApiUrl: instance.configuration.urls.streamingApi,
+   * })
+   * ```
+   */
   readonly streamingApiUrl: string;
-  readonly retry?: boolean | number;
+
+  /**
+   * Access token for the streaming API.
+   *
+   * If it is not provided, you won't be able to use private APIs.
+   */
   readonly accessToken?: string;
+
+  /**
+   * Whether to retry the connection when it fails.
+   *
+   * - If `true`, it will retry indefinitely.
+   * - If `false`, it will not retry.
+   * - If a number, it will retry that many times.
+   *
+   * Defaults to `true`.
+   */
+  readonly retry?: boolean | number;
+
+  /**
+   * Whether to use the access token as a query parameter.
+   *
+   * This is useful when your instance runs an old version of Mastodon that does not support the `Sec-Websocket-Protocols`
+   *
+   * Defaults to `false`.
+   */
   readonly useInsecureAccessToken?: boolean;
 }
 
