TSDoc Authoring Standard

This repository uses TSDoc to make public APIs self-documenting in editor hover, autocomplete, and generated declarations.

Scope

Apply these rules to exported symbols in package source files:

• packages/*/src/**/*.{ts,tsx}
• packages/internals/*/src/**/*.{ts,tsx}

Skip generated code and re-export-only barrel files.

Required for Exported Symbols

1. Add a concise summary sentence on every exported declaration.
2. For exported function-like APIs, document each argument with @param.
3. For exported generic APIs, document each generic with @typeParam.
4. For exported non-void function-like APIs, add @returns.
5. For exported interfaces, document each property with a short property comment.

Balanced Depth (Default)

Use concise, accurate comments by default. Add richer sections only when they clarify important behavior.

• Use @remarks for behavior caveats, defaults, and lifecycle semantics.
• Use @example for high-impact entrypoints and integration setup APIs.
• Use @throws when callers need to branch on failures.

Formatting

• Use TSDoc tags (not JSDoc type braces):
  • @param name - Description
  • @typeParam T - Description
  • @returns Description
• Keep summaries imperative and behavior-focused.
• Prefer documenting contract semantics over implementation details.

Example

/**
 * Creates a configured SDK client for DSAR API operations.
 *
 * @param config - Runtime configuration for endpoint calls and retries.
 * @returns A typed client grouped by DSAR API domains.
 */
export const createNodeSdk = (config?: NodeSdkConfig): NodeSdkClient => {
	// ...
};

Property Comment Pattern

Use property-level comments so tooltips are visible during object construction:

export interface NodeSdkConfig {
	/** DSAR API base URL override (falls back to environment). */
	readonly baseUrl?: string;
	/** Auth token used for bearer authorization. */
	readonly token?: string;
}