docs: complete documentation parity and accuracy fixes

LessUp · LessUp · commit 666822d5a6fa · 2026-05-08T18:55:56.000+08:00
## 中文基准测试文档补全
- 添加 Arithmetic 和 Range Coder 性能表格
- 添加交互式图表组件 &lt;BenchmarkChart /&gt;
- 补充"如何复现"和"另见"章节
- 补充完整的测试数据表格（包含 10MiB 文件）
- 添加输出格式说明和添加新基准测试章节

## C++ API 文档更新
- 移除"零依赖"描述，更新为"共享依赖"
- 明确说明依赖 algorithms/shared/cpp/ 中的公共代码
- 统一中英文档结构

## 验证
- ✅ 文档构建成功
- ✅ 中英文档内容一致
diff --git a/docs/en/api/cpp.md b/docs/en/api/cpp.md
@@ -2,7 +2,7 @@
 
 See also: [Streaming API](/en/api/streaming)
 
-All C++ implementations remain single-file algorithm cores, but now share a C++17 streaming/buffer facade under `algorithms/shared/cpp/include/compresskit/`.
+All C++ implementations keep single-file algorithm cores, but now depend on a shared streaming/buffer facade under `algorithms/shared/cpp/include/compresskit/`.
 
 ## Compilation
 
@@ -101,9 +101,8 @@ Repeated `(count: uint32 LE, value: byte)` pairs.
 
 | Pattern | Description |
 |---------|-------------|
-| Single file | Each algorithm in one `main.cpp` |
-| Zero dependencies | Only standard library |
-| `#include <...>` | Standard library only |
+| Single-file core | Each algorithm core in one `main.cpp` |
+| Shared dependencies | Uses common code from `algorithms/shared/cpp/` |
 | Error handling | `fprintf(stderr, ...)` + `exit(1)` |
 | Memory management | `std::unique_ptr` with custom deleters |
 
diff --git a/docs/zh/api/cpp.md b/docs/zh/api/cpp.md
@@ -2,7 +2,7 @@
 
 另请参阅: [Streaming API](/zh/api/streaming)
 
-所有 C++ 算法核心仍然保持单文件、零依赖风格，但现在额外共享了 `algorithms/shared/cpp/include/compresskit/` 下的 streaming / buffer 门面层。
+所有 C++ 算法核心仍然保持单文件风格，但现在依赖 `algorithms/shared/cpp/include/compresskit/` 下的共享 streaming/buffer 门面层。
 
 ## 编译
 
@@ -20,7 +20,7 @@ g++ -std=c++17 -O2 -Wall -Wextra -o <binary> main.cpp
 | `-fsanitize=address` | 地址消毒器（调试版本） |
 | `-fsanitize=undefined` | 未定义行为消毒器（调试版本） |
 
-## Huffman 编码
+## Huffman 编码 (`algorithms/huffman/cpp/main.cpp`)
 
 ```bash
 ./huffman_cpp encode input.bin output.huf
@@ -44,21 +44,57 @@ g++ -std=c++17 -O2 -Wall -Wextra -o <binary> main.cpp
 
 ---
 
-## 算术编码 / 区间编码 / RLE
+## 算术编码 (`algorithms/arithmetic/cpp/main.cpp`)
 
-遵循相同的单文件、零依赖模式。CLI 接口统一为：
+```bash
+./arithmetic_cpp encode input.bin output.aenc
+./arithmetic_cpp decode output.aenc decoded.bin
+```
+
+### 关键类
+
+- `ArithmeticEncoder` — 状态机，包含 `low`、`high`、`pendingBits`
+- `ArithmeticDecoder` — 解码器，包含 `code` 初始化
+
+---
+
+## 区间编码 (`algorithms/range/cpp/main.cpp`)
 
 ```bash
-<algorithm>_cpp encode <input> <output>
-<algorithm>_cpp decode <input> <output>
+./rangecoder_cpp encode input.bin output.rcnc
+./rangecoder_cpp decode output.rcnc decoded.bin
 ```
 
-### 通用模式
+### 文件格式
+
+| 偏移 | 大小 | 字段 |
+|------|------|------|
+| 0 | 4B | 魔数: `RCNC` |
+| 4 | 4B | 频率表大小 |
+| 8 | 可变 | 频率表 |
+| ... | 可变 | 字节流（重归一化区间） |
+
+---
+
+## RLE (`algorithms/rle/cpp/main.cpp`)
+
+```bash
+./rle_cpp encode input.bin output.rle
+./rle_cpp decode output.rle decoded.bin
+```
+
+### 文件格式
+
+重复的 `(count: uint32 LE, value: byte)` 对。
+
+---
+
+## 通用模式
 
 | 模式 | 描述 |
 |------|------|
-| 单文件 | 每个算法在一个 `main.cpp` 中 |
-| 零依赖 | 仅使用标准库 |
+| 单文件核心 | 每个算法核心在一个 `main.cpp` 中 |
+| 共享依赖 | 使用 `algorithms/shared/cpp/` 中的公共代码 |
 | 错误处理 | `fprintf(stderr, ...)` + `exit(1)` |
 | 内存管理 | `std::unique_ptr` + 自定义删除器 |
 
diff --git a/docs/zh/benchmarks/how-to-run.md b/docs/zh/benchmarks/how-to-run.md
@@ -38,14 +38,18 @@ cd algorithms/rle/benchmark
 python3 bench.py
 ```
 
-## 测试数据
+## 基准测试配置
+
+### 测试数据
 
 | 文件 | 生成方式 | 大小 |
 |------|----------|------|
-| `random_1MiB.bin` | `os.urandom(1024*1024)` | 1 MiB |
-| `random_10MiB.bin` | `os.urandom(10*1024*1024)` | 10 MiB |
-| `repetitive_1MiB.bin` | 重复 256 字节模式 | 1 MiB |
-| `textli_1MiB.bin` | 加权英文字母 | 1 MiB |
+| `tests/data/random_1MiB.bin` | `os.urandom(1024*1024)` | 1 MiB |
+| `tests/data/random_10MiB.bin` | `os.urandom(10*1024*1024)` | 10 MiB |
+| `tests/data/repetitive_1MiB.bin` | 重复 256 字节模式 | 1 MiB |
+| `tests/data/repetitive_10MiB.bin` | 重复 256 字节模式 | 10 MiB |
+| `tests/data/textli_1MiB.bin` | 加权英文字母 | 1 MiB |
+| `tests/data/textli_10MiB.bin` | 加权英文字母 | 10 MiB |
 
 重新生成：
 
@@ -55,7 +59,7 @@ make test-data
 python3 tests/gen_testdata.py
 ```
 
-## 测量指标
+### 测量指标
 
 | 指标 | 描述 |
 |------|------|
@@ -65,6 +69,39 @@ python3 tests/gen_testdata.py
 | 解码速度 | MiB/s = 输入大小 / 解码时间 |
 | 压缩比 | 输出大小 / 输入大小（越小越好） |
 
+### 输出格式
+
+结果保存在 `reports/` 目录：
+
+```
+reports/
+├── huffman_cpp_report.txt
+├── huffman_go_report.txt
+├── huffman_rust_report.txt
+├── arithmetic_cpp_report.txt
+├── ...
+```
+
+每个报告包含：
+
+```
+Algorithm: Huffman
+Language: C++
+Input: 10 MiB random data
+Encode: 245 ms (40.8 MiB/s)
+Decode: 198 ms (50.5 MiB/s)
+Compression ratio: 1.23
+```
+
+## 添加新基准测试
+
+添加新测试数据集：
+
+1. 编辑 `tests/gen_testdata.py`
+2. 在 `generate_random_file()` 中添加生成代码或创建新生成器
+3. 运行 `make test-data`
+4. 编辑相应的 `benchmark/bench.py` 以包含新文件
+
 ## 故障排除
 
 ### "Binary not found"
diff --git a/docs/zh/benchmarks/results.md b/docs/zh/benchmarks/results.md
@@ -6,6 +6,10 @@
 基准测试结果取决于硬件和操作系统。请在本地运行 `make bench` 获取您系统的数值。
 :::
 
+## 交互式性能图表
+
+<BenchmarkChart />
+
 ## 测试数据
 
 | 数据集 | 大小 | 描述 |
@@ -22,12 +26,41 @@
 | Go | 10 MiB 随机 | ~300 | ~250 | ~33 | ~40 | ~1.2× |
 | Rust | 10 MiB 随机 | ~220 | ~180 | ~45 | ~55 | ~1.2× |
 | C++ | 10 MiB 类文本 | ~200 | ~160 | ~50 | ~62 | ~1.8× |
+| Go | 10 MiB 类文本 | ~250 | ~200 | ~40 | ~50 | ~1.8× |
+| Rust | 10 MiB 类文本 | ~180 | ~140 | ~55 | ~71 | ~1.8× |
 
 **关键发现：**
 - Huffman 在类文本数据上表现最好（频率分布不均匀）
 - Rust 始终最快，C++ 和 Go 相当
 - 随机数据压缩比 ≈ 1.2×（接近熵限）
 
+## 算术编码
+
+| 语言 | 输入 | 编码 (ms) | 解码 (ms) | 压缩比 |
+|------|------|-----------|-----------|--------|
+| C++ | 10 MiB 随机 | ~350 | ~300 | ~1.2× |
+| Go | 10 MiB 随机 | ~400 | ~350 | ~1.2× |
+| Rust | 10 MiB 随机 | ~320 | ~280 | ~1.2× |
+| C++ | 10 MiB 类文本 | ~300 | ~250 | ~1.8× |
+
+**关键发现：**
+- 算术编码比 Huffman 慢约 40%，但压缩率更好
+- Go 实现由于边界检查开销最大
+- 分数位编码比 Huffman 提升 5-10% 压缩率
+
+## 区间编码
+
+| 语言 | 输入 | 编码 (ms) | 解码 (ms) | 压缩比 |
+|------|------|-----------|-----------|--------|
+| C++ | 10 MiB 随机 | ~200 | ~180 | ~1.2× |
+| Go | 10 MiB 随机 | ~250 | ~220 | ~1.2× |
+| Rust | 10 MiB 随机 | ~180 | ~150 | ~1.2× |
+
+**关键发现：**
+- 区间编码比算术编码快约 30%（字节级 I/O vs 位级）
+- 压缩率与算术编码相同
+- ⚠️ 已知问题：解码在 >500KB 文件上会卡住，请使用较小的测试文件
+
 ## RLE
 
 | 语言 | 输入 | 编码 (ms) | 解码 (ms) | 压缩比 |
@@ -39,12 +72,12 @@
 
 **关键发现：**
 - RLE 在重复数据上是最快的算法
-- 随机数据用 RLE 会膨胀 ~5×
+- 随机数据用 RLE 会膨胀 ~5×（每个字节变成 5 字节：4 字节计数 + 1 字节值）
 - 最适合作为 BWT 等变换的预处理
 
 ## 跨语言对比
 
-### 速度（最快 → 最慢）
+### 速度排名（最快 → 最慢）
 
 | 算法 | 编码 | 解码 |
 |------|------|------|
@@ -61,3 +94,22 @@
 | 算术编码 | 1.2× | 1.0× | 1.9× |
 | 区间编码 | 1.2× | 1.0× | 1.9× |
 | RLE | 0.2×（膨胀） | 25× | 1.1× |
+
+## 如何复现
+
+```bash
+# 生成测试数据
+make test-data
+
+# 运行所有基准测试
+make bench
+
+# 结果保存在 reports/ 目录
+ls reports/
+```
+
+## 另见
+
+- [如何运行基准测试](/zh/benchmarks/how-to-run) — 详细说明
+- [跨语言测试](/zh/testing/cross-language) — 验证方法
+- [算法指南](/zh/guide/algorithms) — 对比和选择指南
