# CSharpStringExtractor.ts 代码注释计划

## 目标
为 `e:\DATA\Projects\ZhiYou\UnityI18N\scancscode\src\CSharpStringExtractor.ts` 文件添加详细的中文注释，解释代码逻辑意图和注意事项。

## 文件结构分析

### 1. CodeSnippet 类 (行 1-107)
- **功能**: 存储提取的代码片段信息
- **属性说明**:
  - `originalIndex`: 代码片段在原始源代码中的起始位置索引
  - `originalCode`: 从源代码中提取的原始代码片段
  - `convertedCode`: 经过国际化处理后的代码片段
  - `literals`: 从代码片段中提取出的字符串字面量数组
  - `unexpects`: 意外情况记录数组

### 2. CSharpStringExtractor 类 (行 109-3148)

#### 2.1 核心提取方法

| 方法名 | 行号 | 功能说明 |
|--------|------|----------|
| `extractStrings` | 116-274 | 主入口方法，遍历代码提取字符串 |
| `extractClassMemberStrings` | 276-465 | 提取类成员中的字符串（如类字段初始化） |
| `extractObjectInitializerStrings` | 466-670 | 提取对象初始化器中的字符串 |
| `extractCommentStrings` | 671-821 | 提取注释中的字符串 |
| `processFunctionCallArguments` | 823-1102 | 处理函数调用参数中的字符串 |

#### 2.2 字符串处理方法

| 方法名 | 行号 | 功能说明 |
|--------|------|----------|
| `processStringTemplates` | 1721-1923 | 处理字符串模板 ($"...", $"..."...) |
| `processStringFormat` | 1925-1952 | 处理 string.Format() 调用 |
| `processTextAssignments` | 1954-2046 | 处理 .text 和 .title 赋值语句 |
| `processStringConcatenation` | 2048-2286 | 处理字符串拼接 (+ 操作符) |
| `processSingleArgument` | 1466-1479 | 处理单个参数 |
| `extractPlainStrings` | 2311-2337 | 提取普通字符串字面量 |
| `extractTrFormatStrings` | 1689-1719 | 提取 Tr.Format() 中的字符串 |

#### 2.3 辅助方法

| 方法名 | 行号 | 功能说明 |
|--------|------|----------|
| `findMatchingParenthesis` | 1337-1384 | 查找匹配的括号位置 |
| `splitArguments` | 1386-1464 | 分割函数参数列表 |
| `splitExpression` | 2339-2412 | 分割表达式（按+号分割） |
| `isStatementToProcess` | 1606-1633 | 判断语句是否需要处理 |
| `isSpecialAssignment` | 1601-1604 | 判断是否为特殊赋值语句 |
| `extractValueExpression` | 2414-2690 | 提取值表达式 |

## 注释添加计划

### 阶段1: 类的整体注释 (50分钟)
1. 添加文件级别的注释，说明文件用途
2. 添加 CodeSnippet 类的详细注释
3. 添加 CSharpStringExtractor 类的整体注释

### 阶段2: 核心提取方法注释 (80分钟)
1. `extractStrings` 方法 - 详细注释遍历逻辑
2. `extractClassMemberStrings` 方法 - 注释状态机逻辑
3. `extractObjectInitializerStrings` 方法 - 注释嵌套处理
4. `extractCommentStrings` 方法 - 注释注释识别

### 阶段3: 处理方法注释 (70分钟)
1. `processStringTemplates` - 注释插值字符串处理
2. `processStringFormat` - 注释 Format 处理
3. `processTextAssignments` - 注释 .text/.title 处理
4. `processStringConcatenation` - 注释拼接处理

### 阶段4: 辅助方法注释 (60分钟)
1. `findMatchingParenthesis` - 注释括号匹配算法
2. `splitArguments` - 注释参数分割
3. `splitExpression` - 注释表达式分割

### 阶段5: 注意事项和边界情况 (40分钟)
1. 添加转义字符处理说明
2. 添加嵌套字符串处理说明
3. 添加多行字符串处理说明

## 关键逻辑说明要点

### 1. 状态机模式
代码使用多个状态变量跟踪解析位置：
- `inString`: 是否在字符串内部
- `inComment`: 是否在注释内部
- `escapeNext`: 是否遇到转义字符
- `parenthesesDepth`: 括号深度

### 2. 字符串类型识别
需要识别以下字符串类型：
- 普通字符串: `"..."`
- 插值字符串: $"..."
- 原生插值字符串: $@"..."
- 多行字符串: @"..."

### 3. 位置索引计算
- `originalIndex`: 必须在原始代码中的精确位置
- 影响测试用例: `originalIndex` 用于验证代码片段位置

## 预计总工时
约 300 分钟（5小时）