JSDOC_GUIDELINES.md•3.66 kB
# JSDoc 规范指南
本项目强制要求使用符合 JSDoc 标准的注释。所有函数、类、方法和导出的变量都必须包含完整的 JSDoc 注释。
## 基本要求
- ✅ 所有函数声明必须有 JSDoc 注释
- ✅ 所有类声明必须有 JSDoc 注释
- ✅ 所有方法定义必须有 JSDoc 注释
- ✅ 所有箭头函数必须有 JSDoc 注释
- ✅ 所有函数表达式必须有 JSDoc 注释
## JSDoc 格式规范
### 1. 描述要求
- 必须包含完整的描述
- 描述必须以句号结尾
- 描述和标签之间需要空行
### 2. 参数文档
- 所有参数必须有 `@param` 标签
- 参数描述必须完整且以句号结尾
- 参数名称必须与函数签名一致
### 3. 返回值文档
- 有返回值的函数必须有 `@returns` 标签
- 返回值描述必须完整且以句号结尾
## 正确示例
```typescript
/**
* 处理图片缓冲区并应用指定的选项。
*
* @param buffer 要处理的图片缓冲区。
* @param options 处理选项配置。
* @returns 处理后的图片缓冲区。
*/
function processImage(buffer: Buffer, options: ProcessingOptions): Buffer {
return buffer
}
/**
* 图片处理器主类。
* 提供各种图片处理功能。
*/
class ImageProcessor {
/**
* 压缩给定的图片数据。
*
* @param data 要压缩的图片数据。
* @returns 压缩后的图片数据。
*/
compress(data: string): string {
return data
}
}
/**
* 计算图片的总面积。
*
* @param width 图片宽度（像素）。
* @param height 图片高度（像素）。
* @returns 总面积（平方像素）。
*/
const calculateSize = (width: number, height: number): number => {
return width * height
}
```
## 接口和类型注释
```typescript
/**
* 处理选项接口。
*/
interface ProcessingOptions {
/** 质量等级（0-100）。 */
quality: number
/** 输出格式。 */
format: string
}
```
## ESLint 规则说明
项目配置了以下 JSDoc 相关的 ESLint 规则：
- `jsdoc/require-jsdoc` - 要求所有函数、类、方法都有 JSDoc 注释
- `jsdoc/require-description` - 要求所有 JSDoc 都有描述
- `jsdoc/require-description-complete-sentence` - 要求描述是完整句子（以句号结尾）
- `jsdoc/require-param` - 要求所有参数都有 @param 标签
- `jsdoc/require-param-description` - 要求所有参数都有描述
- `jsdoc/require-returns` - 要求有返回值的函数有 @returns 标签
- `jsdoc/require-returns-description` - 要求返回值有描述
- `jsdoc/check-param-names` - 检查参数名称是否一致
- `jsdoc/check-tag-names` - 检查标签名称是否正确
- `jsdoc/check-syntax` - 检查 JSDoc 语法
- `jsdoc/check-alignment` - 检查注释对齐
- `jsdoc/no-blank-blocks` - 不允许空白的 JSDoc 块
## 违规示例（会被 ESLint 报错）
```typescript
// ❌ 错误：缺少 JSDoc 注释
function processImage(buffer: Buffer) {
return buffer
}
// ❌ 错误：JSDoc 不完整
/**
* processImage
*/
function processImage(buffer: Buffer) {
return buffer
}
// ❌ 错误：缺少参数描述
/**
* 处理图片缓冲区。
* @param buffer
* @returns 处理后的缓冲区
*/
function processImage(buffer: Buffer) {
return buffer
}
```
## 运行检查
```bash
# 检查所有文件的 JSDoc 规范
npm run lint
# 自动修复可修复的 JSDoc 格式问题
npm run lint:fix
```
## 注意事项
- TypeScript 已提供类型信息，因此禁用了 `@param` 和 `@returns` 的类型要求
- 未使用的参数建议以下划线开头（如 `_options`）以避免 ESLint 警告
- VSCode 会在保存时自动执行 ESLint 修复，包括 JSDoc 格式修复