# API 文档

本项目使用 [TypeDoc](https://typedoc.org/) 自动生成 API 文档。

## 本地开发

### 生成文档

```bash
# 生成静态文档
npm run docs

# 启动本地服务器预览文档
npm run docs:serve

# 监听文件变化并自动重新生成
npm run docs:watch
```

### 文档脚本说明

- `npm run docs` - 生成静态 HTML 文档到 `./docs` 目录
- `npm run docs:serve` - 启动本地服务器预览文档（默认端口 3000）
- `npm run docs:watch` - 监听文件变化并自动重新生成文档
- `npm run docs:generate` - 使用脚本生成文档
- `npm run docs:deploy` - 生成并部署文档到 GitHub Pages

## 文档结构

生成的文档包含以下主要部分：

### 核心类 (Core Classes)
- `RealseeVRSignalsClient` - VR 信号客户端类
- `RealseeVRSignalsRemote` - VR 信号远程控制类
- `Base` - 基础类
- `StandardEventTarget` - 标准事件目标类
- `StandardActionManager` - 标准 Action 管理器
- `Logger` - 日志记录器
- `SecurityUtils` - 安全工具类

### 类型定义 (Types)
- `DefaultActionMap` - 默认 Action 映射类型
- `DefaultEventMap` - 默认 Event 映射类型
- `ClientOptions` - 客户端配置选项
- `RemoteOptions` - 远程控制配置选项
- `ConnectionStatus` - 连接状态枚举
- `Message` - 消息结构体

### 工具函数 (Utilities)
- `debounce` - 防抖函数
- `throttle` - 节流函数
- `deepClone` - 深拷贝函数
- `retry` - 重试函数
- `delay` - 延迟函数

### 兼容性配置 (Compatibility)
- `getV1CompatibilityConfig` - 获取 1.x 版本兼容配置
- `getAutoCompatibilityConfig` - 自动获取兼容性配置
- `isV1Environment` - 检测是否为 1.x 版本环境

## 配置说明

TypeDoc 配置文件位于 `typedoc.json`，主要配置项：

- `entryPoints` - 入口文件
- `out` - 输出目录
- `theme` - 主题样式
- `readme` - README 文件路径
- `categorizeByGroup` - 按组分类
- `excludePrivate` - 排除私有成员
- `excludeProtected` - 排除受保护成员

# API 文档

本项目使用 [TypeDoc](https://typedoc.org/) 自动生成 API 文档，并通过 npm 包发布，使用 unpkg 提供在线访问。

## 本地开发

### 生成文档

```bash
# 生成静态文档
npm run docs

# 启动本地服务器预览文档
npm run docs:serve

# 监听文件变化并自动重新生成
npm run docs:watch
```

### 文档脚本说明

- `npm run docs` - 生成静态 HTML 文档到 `./docs` 目录
- `npm run docs:serve` - 启动本地服务器预览文档（默认端口 3000）
- `npm run docs:watch` - 监听文件变化并自动重新生成文档
- `npm run docs:generate` - 使用脚本生成文档

## 文档发布

文档会在发布 npm 包时自动生成并包含在包中：

```bash
# 发布包（会自动生成文档）
npm publish
```

发布后，文档可以通过以下方式访问：

- **unpkg 在线文档**: https://unpkg.com/@realsee/vr-signals@latest/docs/
- **特定版本**: https://unpkg.com/@realsee/vr-signals@2.0.0-beta.4/docs/
- **本地预览**: `npm run docs:serve` 后访问 http://localhost:3000

### 测试发布流程

在发布包之前，可以运行测试脚本验证发布流程：

```bash
# 测试包发布流程
bash scripts/test-publish.sh
```

这个脚本会：
1. 清理之前的构建
2. 重新构建包
3. 生成文档
4. 检查所有必需的文件是否存在
5. 验证 package.json 配置

## 贡献指南

### 添加 JSDoc 注释

为新的类、方法、接口添加 JSDoc 注释：

```typescript
/**
 * 类的描述
 * 
 * @template T 泛型参数说明
 * @example
 * ```typescript
 * const instance = new MyClass()
 * ```
 * 
 * @category Core Classes
 */
class MyClass<T> {
  /**
   * 方法的描述
   * 
   * @param param1 参数1说明
   * @param param2 参数2说明
   * @returns 返回值说明
   * 
   * @example
   * ```typescript
   * const result = instance.myMethod('param1', 'param2')
   * ```
   */
  myMethod(param1: string, param2: number): boolean {
    // 实现
  }
}
```

### 分类标签

使用 `@category` 标签对文档进行分类：

- `Core Classes` - 核心类
- `Types` - 类型定义
- `Utilities` - 工具函数
- `Compatibility` - 兼容性配置

### 示例代码

为重要的 API 添加使用示例：

```typescript
/**
 * @example
 * ```typescript
 * import { RealseeVRSignalsClient } from '@realsee/vr-signals'
 * 
 * const client = new RealseeVRSignalsClient({
 *   vrLink: 'http://localhost:3000/vr-app',
 *   element: iframeElement
 * })
 * ```
 */
```