ts-docblocks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add Missing Docblocks

补充缺失的JSDoc注释块

Scan the specified path (or entire repository if no path given) and add missing docblocks to all exported functions, classes, interfaces, types, and constants.

扫描指定路径（若未提供路径则扫描整个仓库），为所有导出的函数、类、接口、类型和常量补充缺失的JSDoc注释块。

Key Rules

核心规则

All exported functions, types, interfaces, and constants MUST have JSDoc docblocks.
Start with
```
/**
```
, use
```
*
```
prefix for each line, end with
```
*/
```
— each on its own line.
Begin with a clear one-to-two line summary. Add a blank line before tags.
Include
```
@param
```
,
```
@typeParam
```
,
```
@return
```
,
```
@throws
```
, and at least one
```
@example
```
when helpful.
Use
```
{@link ...}
```
to reference related items. Add
```
@see
```
tags at the end for related APIs.
Do NOT modify real code outside of docblocks. Do NOT modify existing docblocks.

所有导出的函数、类型、接口和常量必须有JSDoc注释块。
以
```
/**
```
开头，每行用
```
*
```
作为前缀，以
```
*/
```
结尾，三者各占单独一行。
开头先写1-2行清晰的概述，标签前加一个空行。
适用场景下需包含
```
@param
```
、
```
@typeParam
```
、
```
@return
```
、
```
@throws
```
，以及至少一个
```
@example
```
示例。
使用
```
{@link ...}
```
引用相关内容，末尾添加
```
@see
```
标签指向相关API。
不要修改注释块之外的实际代码，也不要修改已有的注释块。

Guidelines

规范指南

Style

格式规范

Use JSDoc format with the following conventions:

Start with
```
/**
```
on its own line.
Use
```
*
```
prefix for each line.
End with
```
*/
```
on its own line.
Keep descriptions concise but complete.
Start your sentences with a capital letter and end with a period.
Limit your usage of em dashes but, when you do use them, use spaces on both sides.
Begin with a clear one or two line summary (no
```
@summary
```
tag needed).
Add a blank line after the summary if adding more details.
Include
```
@param
```
tags for all parameters.
Include
```
@typeParam
```
tags for all type parameters. Use
```
@typeParam
```
, not
```
@template
```
.
Include
```
@return
```
tag briefly describing the return value.
Add
```
@throws
```
for functions that may throw errors and list these errors.
Include at least one
```
@example
```
section whenever usage examples would be helpful. If the file is a TypeScript file, use TypeScript syntax in examples. Try to make the examples realistic but concise and pleasant to read. They must illustrate the concepts clearly at first glance. When more than one example is preferred, use multiple
```
@example
```
tags and keep the first one as simple as possible to illustrate the basic usage. Never use
```
any
```
type in examples. Display the
```
import
```
statements required for the example to work when imports from multiple libraries are required. It is acceptable to use placeholder variable names like
```
myUser
```
or even
```
/* ... */
```
for parts that are not relevant to the example. When multiple example sections are provided, add a brief description before each code block to quickly explain what the example illustrates.
In the rare case where more advanced documentation is also needed for the item, use the
```
@remarks
```
tag to add this extra information after any example sections. These remarks can include longer explanations and even additional code blocks if necessary.
When an item is deprecated, include a
```
@deprecated
```
tag with a brief explanation and, if applicable, suggest an alternative.
Use
```
{@link ...}
```
tags to reference other items in the codebase when relevant.
Add
```
@see
```
tags at the very end when applicable to point to other related items or documentation. Use
```
@see {@link ...}
```
format when linking to other code items.

遵循以下JSDoc格式约定：

以单独一行的
```
/**
```
开头。
每行使用
```
*
```
作为前缀。
以单独一行的
```
*/
```
结尾。
描述简洁且完整。
句子首字母大写，末尾加句号。
尽量少用破折号，若使用则两侧需加空格。
开头写1-2行清晰的概述（无需使用
```
@summary
```
标签）。
若要补充更多细节，在概述后加一个空行。
所有参数都要添加
```
@param
```
标签。
所有类型参数都要添加
```
@typeParam
```
标签，使用
```
@typeParam
```
而非
```
@template
```
。
添加
```
@return
```
标签简要描述返回值。
可能抛出错误的函数要添加
```
@throws
```
标签并列出所有错误。
只要示例有用就至少添加一个
```
@example
```
部分。如果是TypeScript文件，示例使用TypeScript语法。尽量让示例真实、简洁、易读，第一眼就能清晰说明概念。如果需要多个示例，使用多个
```
@example
```
标签，第一个示例尽量简单，展示基础用法。示例中不要使用
```
any
```
类型。如果需要引入多个库，要展示示例所需的
```
import
```
语句。可以使用
```
myUser
```
这类占位变量名，或者用
```
/* ... */
```
表示和示例无关的部分。如果提供了多个示例，每个代码块前加简要说明，快速解释示例的用途。
极少数情况下需要为项补充更高级的文档时，在所有示例部分后使用
```
@remarks
```
标签添加额外信息，备注可以包含更长的说明，必要时也可以加额外的代码块。
如果某项已废弃，添加
```
@deprecated
```
标签并附简要说明，适用的话给出替代方案。
相关场景下使用
```
{@link ...}
```
标签引用代码库中的其他项。
适用的话在最末尾添加
```
@see
```
标签指向其他相关项或文档，链接到其他代码项时使用
```
@see {@link ...}
```
格式。

Examples

示例

/**
 * Creates a retry wrapper around an async function.
 *
 * Retries the given function up to `maxRetries` times with exponential
 * backoff between attempts.
 *
 * @param fn - The async function to retry.
 * @param maxRetries - Maximum number of retry attempts.
 * @param baseDelay - Base delay in milliseconds between retries.
 * @return A wrapped version of `fn` that retries on failure.
 * @throws Throws the last error if all retry attempts are exhausted.
 *
 * @example
 * ```ts
 * const fetchWithRetry = withRetry(fetchData, 3, 1000);
 * const data = await fetchWithRetry('/api/users');
 * ```
 *
 * @example
 * Custom retry configuration for flaky network calls.
 * ```ts
 * const resilientFetch = withRetry(
 *   () => fetch('https://api.example.com/data'),
 *   5,
 *   500,
 * );
 * ```
 */
export function withRetry<T>(
    fn: (...args: unknown[]) => Promise<T>,
    maxRetries: number,
    baseDelay: number,
): (...args: unknown[]) => Promise<T>;

/**
 * Fixes a `Uint8Array` to the specified length.
 *
 * If the array is longer than the specified length, it is truncated.
 * If the array is shorter than the specified length, it is padded with zeroes.
 *
 * @param bytes - The byte array to truncate or pad.
 * @param length - The desired length of the byte array.
 * @return The byte array truncated or padded to the desired length.
 *
 * @example
 * Truncates the byte array to the desired length.
 * ```ts
 * const bytes = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
 * const fixedBytes = fixBytes(bytes, 2);
 * //    ^ [0x01, 0x02]
 * ```
 *
 * @example
 * Adds zeroes to the end of the byte array to reach the desired length.
 * ```ts
 * const bytes = new Uint8Array([0x01, 0x02]);
 * const fixedBytes = fixBytes(bytes, 4);
 * //    ^ [0x01, 0x02, 0x00, 0x00]
 * ```
 */
export const fixBytes = (
    bytes: ReadonlyUint8Array | Uint8Array,
    length: number,
): ReadonlyUint8Array | Uint8Array;

/**
 * A tree structure representing a set of instructions with execution constraints.
 *
 * Supports parallel execution, sequential execution, and combinations of both
 * through recursive composition of plan nodes.
 *
 * @example
 * ```ts
 * const plan: InstructionPlan = parallelPlan([
 *     sequentialPlan([instructionA, instructionB]),
 *     instructionC,
 *     instructionD,
 * ]);
 * ```
 *
 * @see {@link SingleInstructionPlan}
 * @see {@link ParallelInstructionPlan}
 * @see {@link SequentialInstructionPlan}
 */
export type InstructionPlan =
    | ParallelInstructionPlan
    | SequentialInstructionPlan
    | SingleInstructionPlan;

/**
 * Creates a retry wrapper around an async function.
 *
 * Retries the given function up to `maxRetries` times with exponential
 * backoff between attempts.
 *
 * @param fn - The async function to retry.
 * @param maxRetries - Maximum number of retry attempts.
 * @param baseDelay - Base delay in milliseconds between retries.
 * @return A wrapped version of `fn` that retries on failure.
 * @throws Throws the last error if all retry attempts are exhausted.
 *
 * @example
 * ```ts
 * const fetchWithRetry = withRetry(fetchData, 3, 1000);
 * const data = await fetchWithRetry('/api/users');
 * ```
 *
 * @example
 * Custom retry configuration for flaky network calls.
 * ```ts
 * const resilientFetch = withRetry(
 *   () => fetch('https://api.example.com/data'),
 *   5,
 *   500,
 * );
 * ```
 */
export function withRetry<T>(
    fn: (...args: unknown[]) => Promise<T>,
    maxRetries: number,
    baseDelay: number,
): (...args: unknown[]) => Promise<T>;

/**
 * Fixes a `Uint8Array` to the specified length.
 *
 * If the array is longer than the specified length, it is truncated.
 * If the array is shorter than the specified length, it is padded with zeroes.
 *
 * @param bytes - The byte array to truncate or pad.
 * @param length - The desired length of the byte array.
 * @return The byte array truncated or padded to the desired length.
 *
 * @example
 * Truncates the byte array to the desired length.
 * ```ts
 * const bytes = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
 * const fixedBytes = fixBytes(bytes, 2);
 * //    ^ [0x01, 0x02]
 * ```
 *
 * @example
 * Adds zeroes to the end of the byte array to reach the desired length.
 * ```ts
 * const bytes = new Uint8Array([0x01, 0x02]);
 * const fixedBytes = fixBytes(bytes, 4);
 * //    ^ [0x01, 0x02, 0x00, 0x00]
 * ```
 */
export const fixBytes = (
    bytes: ReadonlyUint8Array | Uint8Array,
    length: number,
): ReadonlyUint8Array | Uint8Array;

/**
 * A tree structure representing a set of instructions with execution constraints.
 *
 * Supports parallel execution, sequential execution, and combinations of both
 * through recursive composition of plan nodes.
 *
 * @example
 * ```ts
 * const plan: InstructionPlan = parallelPlan([
 *     sequentialPlan([instructionA, instructionB]),
 *     instructionC,
 *     instructionD,
 * ]);
 * ```
 *
 * @see {@link SingleInstructionPlan}
 * @see {@link ParallelInstructionPlan}
 * @see {@link SequentialInstructionPlan}
 */
export type InstructionPlan =
    | ParallelInstructionPlan
    | SequentialInstructionPlan
    | SingleInstructionPlan;

Command Process

命令执行流程

When invoked as a command, follow these steps:

作为命令调用时，遵循以下步骤：

Arguments

参数

```
[path]
```
(optional): Narrow the scan to a specific path (e.g.
```
src/utils
```
or
```
packages/my-lib/src
```
).
```
[--all]
```
(optional): Also scan non-exported items.

```
[path]
```
（可选）：限定扫描的特定路径，例如
```
src/utils
```
或
```
packages/my-lib/src
```
。
```
[--all]
```
（可选）：同时扫描非导出项。

Steps

执行步骤

If a path argument is provided, scan only that path; otherwise scan the entire repository.
Look for TypeScript/JavaScript files (
```
.ts
```
,
```
.tsx
```
,
```
.js
```
,
```
.jsx
```
).
Identify exported items without docblocks:
- ```
export function
```
- ```
export class
```
- ```
export interface
```
- ```
export type
```
- ```
export const
```
  (for constants and arrow functions)
If
```
--all
```
is passed, also identify non-exported items.
For each item missing a docblock:
- Analyze the code to understand its purpose (this may span multiple files).
- Examine parameters, return types, and behavior.
- Generate an appropriate docblock following the style guide.
Present all changes clearly, grouped by file. Apply all changes without requiring further approval.

若提供了路径参数则仅扫描该路径，否则扫描整个仓库。
查找TypeScript/JavaScript文件（
```
.ts
```
、
```
.tsx
```
、
```
.js
```
、
```
.jsx
```
）。

识别没有注释块的导出项：

```
export function
```
```
export class
```
```
export interface
```
```
export type
```
```
export const
```
（常量和箭头函数）

如果传入了
```
--all
```
参数，同时识别非导出项。
对每个缺少注释块的项：
- 分析代码理解其用途（可能涉及多个文件）。
- 检查参数、返回类型和行为。
- 按照格式规范生成合适的JSDoc注释块。
按文件分组清晰展示所有变更，无需额外确认即可应用所有修改。