---
phase: 08-documentation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - src/parser.rs
  - src/error.rs
autonomous: true
requirements:
  - DOC-01
must_haves:
  truths:
    - "LogParser 结构体及其所有公开方法有中文 rustdoc 注释"
    - "LogIterator 结构体有中文 rustdoc 注释"
    - "LogParserBuilder 结构体及其所有链式方法有中文 rustdoc 注释"
    - "过滤方法 filter_by_exec_time、filter_by_sql_contains 有中文 rustdoc 注释"
    - "parse_record 公开函数有中文 rustdoc 注释"
    - "cargo doc --no-deps 无 missing_docs 警告"
  artifacts:
    - path: "src/parser.rs"
      provides: "所有公开类型、方法均含中文 rustdoc"
      min_lines: 480
    - path: "src/error.rs"
      provides: "ParseError 变体字段（含 line_number）均含 rustdoc"
    - path: "stdout"
      provides: "cargo doc --no-deps 无 warning 输出"
  key_links:
    - from: "src/parser.rs"
      to: "cargo doc --no-deps"
      via: "//! doc comments 转为 HTML"
    - from: "src/error.rs"
      to: "cargo doc --no-deps"
      via: "//! doc comments 转为 HTML"
---

<objective>
为 `src/parser.rs` 和 `src/error.rs` 中所有公开类型、方法、函数补全中文 rustdoc 注释，使 `cargo doc --no-deps` 无任何 missing_docs 警告。

Purpose: 满足 DOC-01 要求 — 所有 pub 类型、方法、字段均有 rustdoc 注释，语言为中文（per D-01）。
Output: `src/parser.rs` 和 `src/error.rs` 中每个公开项均带中文 rustdoc 注释。
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/ROADMAP.md
@.planning/REQUIREMENTS.md
@.planning/phases/07-apiergonomics/07-CONTEXT.md
@.planning/phases/08-documentation/08-CONTEXT.md
@CLAUDE.md
@src/parser.rs
@src/error.rs
@src/lib.rs

<interfaces>
<!-- 现有代码的关键类型签名，executor 无需重新探索 -->

```rust
// src/parser.rs — 当前公开项状态
// LogParser (struct) — NO doc
// LogParser::from_path (fn, Phase 7 将移除) — NO doc
// LogParser::iter (fn) — NO doc
// LogParser::par_iter (fn) — 有英文 doc（需转为中文）
// LogParser::index (fn) — 已有中文 doc
// RecordIndex (struct) — 已有中文 doc
// RecordIndex::len (fn) — 已有中文 doc
// RecordIndex::is_empty (fn) — 已有中文 doc
// LogIterator (struct) — NO doc
// parse_record (fn) — NO doc

// Phase 7 新增（位于 parser.rs，本 plan 为其添加 doc）：
// LogParserBuilder — builder 结构体
// LogParserBuilder::new(path) -> Self
// LogParserBuilder::threads(n: usize) -> &mut Self
// LogParserBuilder::parallel_threshold(n: usize) -> &mut Self
// LogParserBuilder::encoding(hint: FileEncodingHint) -> &mut Self
// LogParserBuilder::build() -> Result<LogParser, ParseError>
// LogIterator::filter_by_exec_time(min_ms: u64) -> impl Iterator<...>
// LogIterator::filter_by_sql_contains(pattern: &str) -> impl Iterator<...>

// src/error.rs — 当前公开项状态
// ParseError (enum) — 已有中文 doc
// InvalidFormat { raw: String, line_number: u64 } — raw 有 doc，line_number 需 doc
// FileNotFound { path: String } — 已有 doc
// InvalidRecordStartLine { raw: String, line_number: u64 } — raw 有 doc，line_number 需 doc
// IntParseError { field: String, value: String, raw: String, line_number: u64 } — field/value/raw 有 doc，line_number 需 doc
// IoError(String) — 已有 doc
```
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: 补全 parser.rs 现有公开 API 的中文 rustdoc</name>
  <files>src/parser.rs</files>
  <read_first>src/parser.rs, CLAUDE.md</read_first>
  <action>
    为 `src/parser.rs` 中以下所有当前缺少 doc 的公开项添加中文 rustdoc 注释（per D-01）：

    1. `LogParser` 结构体（第 33 行）— 用中文描述其作用（内存映射文件 + 编码检测，供迭代解析使用），提及 Builder 是推荐入口。
    2. `LogParser::iter()`（第 93 行）— 中文描述：返回顺序迭代器，逐条解析记录。说明每次调用返回新的 `LogIterator`。
    3. `LogParser::par_iter()`（第 130 行）— 将现有英文 doc 翻译为中文（per D-01）。保留原有语义：大文件按记录边界分区、O(threads) 开销、小文件单线程。
    4. `LogIterator` 结构体（第 176 行）— 中文描述其迭代器角色，提及它是 `LogParser::iter()` 的返回类型，Item 为 `Result<Sqllog, ParseError>`。
    5. `parse_record()` 函数（第 275 行）— 中文描述：从原始字节解析单条 SQL 日志记录，自动检测多行模式（含嵌入换行的记录）。提及 `LogIterator::next()` 内部调用此函数。

    注意事项：
    - D-02：代码示例中的变量名和注释保持英文，示例描述文字用中文。
    - 不要修改 LogParser::from_path — Phase 7 会将其移除，加 doc 是浪费。
    - 不要修改非 pub 项（如 find_next_record_start、is_timestamp_start、make_invalid_format_error）。
    - LogParser::index（第 101 行）和 RecordIndex 已存在中文 doc，若质量足够则不做修改。
    - 注意不要在注释中引入 `#![deny(missing_docs)]` — 该 lint 由 cargo doc 验证替代。
  </action>
  <acceptance_criteria>
    所有上述 5 个公开项均有非空的中文 rustdoc：
    - `grep -c '///.*LogParser' src/parser.rs` 返回 ≥2（struct + methods）
    - `grep -c '///.*LogIterator' src/parser.rs` 返回 ≥1
    - `grep -c '///.*parse_record' src/parser.rs` 返回 ≥1
    - `LogParser::par_iter` 的 doc 注释为中文（不含英文"Returns"、"parallel"等）
  </acceptance_criteria>
  <verify>
    <automated>
      grep -c '^///' src/parser.rs | awk '{print $1}' > /dev/null 2>&1
      grep 'LogParser' src/parser.rs | head -1 | grep -q '///'
    </automated>
  </verify>
  <done>LogParser 结构体、iter()、par_iter()、LogIterator 结构体、parse_record() 均有中文 rustdoc</done>
</task>

<task type="auto">
  <name>Task 2: 补全 Phase 7 新增 API（parser.rs）的中文 rustdoc</name>
  <files>src/parser.rs</files>
  <read_first>src/parser.rs, .planning/phases/07-apiergonomics/07-CONTEXT.md</read_first>
  <action>
    Phase 7 的实现位于 `src/parser.rs`。为此新增的公开 API 添加中文 rustdoc 注释（per D-01, D-02）：

    1. `LogParserBuilder` 结构体 — 中文描述：链式配置 `LogParser` 的构建器。替代已弃用的 `LogParser::from_path`。列出支持的配置项（threads、parallel_threshold、编码提示）。
    2. `LogParserBuilder::new(path)` — 中文描述：用文件路径创建构建器。参数 path 为 `impl AsRef<Path>`。
    3. `LogParserBuilder::threads(n: usize)` — 中文描述：设置并行解析线程数。
    4. `LogParserBuilder::parallel_threshold(n: usize)` — 中文描述：设置触发并行解析的最小文件大小（字节）。
    5. `LogParserBuilder::encoding(hint: FileEncodingHint)` — 中文描述：设置文件编码提示（Auto/Utf8/Gb18030）。
    6. `LogParserBuilder::build()` — 中文描述：构建 `LogParser`，执行文件打开和编码探测。返回 `Result<LogParser, ParseError>`。
    7. `LogIterator::filter_by_exec_time(min_ms: u64)` — 中文描述：过滤执行时间 ≥ min_ms（毫秒）的记录。对于无 indicators 的记录自动过滤掉。返回 `impl Iterator<Item = Result<Sqllog, ParseError>>`。
    8. `LogIterator::filter_by_sql_contains(pattern: &str)` — 中文描述：过滤 SQL 语句体包含指定子串的记录。匹配不区分大小写。返回 `impl Iterator<Item = Result<Sqllog, ParseError>>`。

    注意事项：
    - 如果 Phase 7 的实现将 `LogParserBuilder` 放在另一个文件（如 `src/builder.rs`），则在对应文件操作。
    - 不要添加代码示例（assert 注释）—— D-03 将示例集中放在 lib.rs。
    - 保持 D-02 风格：代码中变量名、注释用英文，doc 描述文字用中文。
    - 如果 Phase 7 未实现某个具体方法（如 `encoding()`），只为已存在的方法加 doc，不要创建新方法。
  </action>
  <acceptance_criteria>
    所有 Phase 7 新增的公开 API 均有中文 rustdoc：
    - 如果 `LogParserBuilder` 在 `src/parser.rs` 中，其 struct 和每个方法均有 `///` 注释
    - `filter_by_exec_time` 和 `filter_by_sql_contains` 均有 doc
  </acceptance_criteria>
  <verify>
    <automated>
      cargo doc --no-deps 2>&1 | grep -v '^    Checking\|^    Documenting\|^   Finished' | head -20
    </automated>
  </verify>
  <done>Phase 7 新增 API 全部有中文 rustdoc，cargo doc --no-deps 无 warning</done>
</task>

<task type="auto">
  <name>Task 3: 补全 error.rs 中 Phase 6 新增 line_number 字段的 rustdoc</name>
  <files>src/error.rs</files>
  <read_first>src/error.rs, .planning/phases/06-errorhandling/06-01-PLAN.md</read_first>
  <action>
    Phase 6 在 `src/error.rs` 中为 `InvalidFormat`、`InvalidRecordStartLine`、`IntParseError` 三个变体新增了 `line_number: u64` 字段。

    为这三个字段添加中文 rustdoc：
    1. `InvalidFormat` 中的 `line_number: u64` — "记录行号（文件中从 1 开始计数的行数）"
    2. `InvalidRecordStartLine` 中的 `line_number: u64` — 同上语义
    3. `IntParseError` 中的 `line_number: u64` — 同上语义

    注意事项：
    - ParseError 枚举本身和现有字段（raw、path、field、value）已有 doc，不要重复修改。
    - 此任务仅添加 line_number 字段的 doc（如果 Phase 6 已添加了 doc 则跳过）。
  </action>
  <acceptance_criteria>
    所有 `line_number: u64` 字段在三个变体中均有 `///` 注释行。
    `grep -A1 'line_number: u64' src/error.rs | grep '///'` 返回 3 个匹配。
  </acceptance_criteria>
  <verify>
    <automated>
      grep -c '///.*行号' src/error.rs; # 应 ≥3
      cargo doc --no-deps 2>&1 | grep -i 'warning.*missing' | head -5
    </automated>
  </verify>
  <done>error.rs 所有字段均有 rustdoc，cargo doc --no-deps 无 warning</done>
</task>

</tasks>

<verification>
```bash
# 最终验证：无 missing docs 警告
cargo doc --no-deps 2>&1 | grep -v '^    Checking\|^    Documenting\|^   Finished'
# 预期输出无 "warning: missing documentation for" 或 "warning: doc comment not used"
```
</verification>

<success_criteria>
1. `cargo doc --no-deps` 无任何 warning（包含 missing_docs）
2. parser.rs 中所有 pub 项均有中文 rustdoc
3. error.rs 中所有字段（含 line_number）均有 rustdoc
</success_criteria>
