innomind-vita/docs/specs/api/api-documentation.md

InnoMind Vita - AI-Powered Industrial Software Platform

# API 文档规范

## TypeDoc 注释规范

### 1. 类注释
```typescript
/**
 * 类的简要描述
 * 
 * 详细描述（可选）
 * 
 * @example
 * ```typescript
 * const instance = new MyClass();
 * instance.doSomething();
 * ```
 * 
 * @since 1.0.0
 */
class MyClass {
  // ...
}
```

### 2. 方法注释
```typescript
/**
 * 方法的简要描述
 * 
 * 详细描述（可选）
 * 
 * @param param1 - 参数1的说明
 * @param param2 - 参数2的说明
 * @returns 返回值说明
 * @throws {Error} 可能抛出的错误说明
 * 
 * @example
 * ```typescript
 * const result = instance.method('param1', 123);
 * ```
 */
method(param1: string, param2: number): boolean {
  // ...
}
```

### 3. 属性注释
```typescript
/**
 * 属性的说明
 * 
 * @type {string} 类型说明
 * @default 'default value' 默认值（可选）
 */
property: string;
```

### 4. 接口注释
```typescript
/**
 * 接口的简要描述
 * 
 * 详细描述（可选）
 * 
 * @interface
 */
interface IExample {
  /**
   * 属性说明
   */
  property: string;

  /**
   * 方法说明
   */
  method(): void;
}
```

## API 设计规范

### 1. 命名规范
- 使用驼峰命名法
- 方法名使用动词开头
- 布尔属性使用 is/has/can 开头
- 常量使用全大写下划线

### 2. 参数规范
- 必选参数在前，可选参数在后
- 参数数量不超过3个
- 超过3个使用配置对象
- 避免使用布尔标记参数

### 3. 返回值规范
- 保持类型一致性
- 明确错误处理方式
- 避免返回 null
- Promise 必须指定泛型

### 4. 错误处理
- 使用自定义错误类
- 提供错误代码
- 包含详细错误信息
- 支持错误链追踪

## 版本管理

### 1. 版本号规范
- 遵循语义化版本
- 主版本号：不兼容的API修改
- 次版本号：向下兼容的功能性新增
- 修订号：向下兼容的问题修正

### 2. 变更记录
- 记录所有API变更
- 标注废弃信息
- 提供迁移指南
- 保持向后兼容

## 文档生成

### 1. 工具配置
```json
{
  "typedoc": {
    "entryPoints": ["src/index.ts"],
    "out": "docs/api",
    "excludePrivate": true,
    "excludeProtected": true,
    "excludeExternals": true
  }
}
```

### 2. 生成命令
```bash
# 生成API文档
pnpm typedoc

# 检查文档覆盖率
pnpm typedoc --coverage
```