# MoonDocCheck User Guide

这份文档面向第一次使用 MoonDocCheck 的用户。它会从“这个工具解决什么问题”开始，逐步说明如何运行、如何读懂报告、如何根据报告修改 MoonBit 项目文档。

## 1. MoonDocCheck 是什么

MoonDocCheck 是一个 MoonBit 项目文档质量检查工具。

它不会修改你的项目源码，也不会替代 MoonBit 官方工具。它的作用是扫描一个 MoonBit 仓库，然后告诉你：

- 哪些公开 API 没有文档注释。
- 哪些文档注释太弱，像 `TODO` 或 `FIXME` 这样的占位内容。
- README 是否包含项目介绍、价值说明、入口目录、文档跳转和必要的使用入口。
- Markdown 文档里是否有 MoonBit 示例，以及这些示例是否使用了 `mbt check` / `mbt nocheck` 标记。
- `moon.mod` 是否包含项目发布常见元数据，并识别旧版 `moon.mod.json`。
- 是否生成了 `pkg.generated.mbti` 接口摘要。
- GitHub Actions 是否运行了常见 MoonBit 检查命令，或是否调用了验证脚本。
- 项目整体和每个源文件的公开 API 文档覆盖率是多少。
- 是否存在可以通过配置排除的示例、夹具或测试数据目录。
- 项目整体发布准备度如何，并根据实际问题生成下一步建议。

简单说，MoonDocCheck 帮你回答一个问题：

> 这个 MoonBit 项目是否已经具备让别人快速理解、使用和维护的基础文档？

## 2. 适合什么时候使用

你可以在这些场景使用 MoonDocCheck：

- 准备发布 MoonBit 包之前。
- 准备提交开源项目评审之前。
- 给自己的 MoonBit 项目补文档之前。
- 团队代码审查时检查文档完整性。
- 在 CI 里自动检查 README、API 文档和基础项目元数据。
- 学习 MoonBit 项目结构时，观察一个项目还缺哪些公开说明。

## 3. 基本概念

### 3.1 公开 API

MoonDocCheck 重点检查公开 API。公开 API 是别人使用你的包时最需要理解的部分，例如：

```moonbit
/// Add two integers.
pub fn add(a : Int, b : Int) -> Int {
  a + b
}
```

这里的 `pub fn add` 就是公开 API。它前面的 `/// Add two integers.` 是文档注释。

如果公开 API 没有文档注释，使用者就很难知道它的用途、输入含义和返回结果。

### 3.2 文档注释

MoonBit 中常见的 API 文档注释写法是 `///`：

```moonbit
/// Return the project display name.
pub fn project_name() -> String {
  "MoonDocCheck"
}
```

MoonDocCheck 会检查公开 API 附近是否有这样的注释。

### 3.3 弱文档

有文档注释不代表文档一定有用。下面这种注释形式太弱：

```moonbit
/// TODO
pub fn parse(input : String) -> Unit {
  ()
}
```

MoonDocCheck 会把 `TODO`、`FIXME` 或过短的占位式说明标记为弱文档。

### 3.4 `mbt check` 示例

MoonBit 文档可以包含可检查的代码块：

````markdown
```mbt check
test {
  inspect(add(1, 2), content="3")
}
```
````

这类示例比普通代码块更可靠，因为它们可以被 MoonBit 工具链检查。

MoonDocCheck 会统计 Markdown 中的 `mbt check`、`mbt nocheck` 和普通 MoonBit 代码块。

## 4. 安装与准备

目前 MoonDocCheck 以源码项目形式运行。你需要先安装 MoonBit 工具链，并进入 MoonDocCheck 项目目录。

确认项目可以检查：

```bash
moon check
```

确认测试可以运行：

```bash
moon test
```

生成或更新接口摘要：

```bash
moon info
```

如果这些命令都能通过，说明本地环境已经可以运行 MoonDocCheck。

## 5. 最基础的使用方式

当前版本通过源码运行，因此下列 `moon run cmd/main` 命令都必须在 MoonDocCheck 仓库根目录中执行。命令最后的路径才是待检测项目。

例如，MoonDocCheck 和待检测项目位于同一个上级目录时：

```bash
moon run cmd/main -- scan ../my_moonbit_project
```

命令含义：

- `moon run cmd/main`：运行 MoonDocCheck 的命令行入口。
- `--`：把后面的参数传给 MoonDocCheck，而不是传给 `moon run`。
- `scan`：执行扫描操作。
- `../my_moonbit_project`：从 MoonDocCheck 目录指向待检测项目。也可以使用绝对路径。

使用绝对路径时，待检测项目可以放在任意位置：

```bash
moon run cmd/main -- scan /absolute/path/to/my_moonbit_project
```

也可以直接扫描公开 GitHub 仓库：

```bash
moon run cmd/main -- scan https://github.com/user/project.git
```

这种方式会临时浅克隆远程仓库，然后对克隆结果执行同样的检查。你需要本机已经安装 `git`，并且目标仓库是公开可访问的。

## 6. 输出报告格式

MoonDocCheck 支持四种输出格式：文本、HTML、Markdown、JSON。文本、HTML 和 Markdown 报告默认使用中文，也可以通过 `--lang en` 输出英文。

### 6.1 文本报告

默认格式是文本报告，适合直接在终端查看：

```bash
moon run cmd/main -- scan ../my_moonbit_project
```

它会输出项目概览、公开 API 文档覆盖率、README 检查结果、示例统计、CI 检查结果和问题列表。

如果需要英文报告：

```bash
moon run cmd/main -- scan ../my_moonbit_project --lang en
```

### 6.2 HTML 预览报告

如果项目问题较多，推荐生成 HTML 报告后用浏览器查看：

```bash
moon run cmd/main -- scan ../my_moonbit_project --format html --output report.html
```

HTML 报告是单文件，不依赖网络资源。它会用更清晰的卡片、表格和状态颜色展示摘要、重灾区、文件覆盖率、问题清单和下一步建议，适合长报告阅读和人工评审。

HTML 报告还包含一些本地交互功能：

- 在文件覆盖率区搜索文件路径。
- 按覆盖率区间筛选文件。
- 只查看仍有缺失文档的文件。
- 在问题清单中搜索路径、API 名称或问题内容。
- 按问题类型筛选，例如 API 文档、README、`moon.mod`、CI。
- 展开单条问题，查看判定依据和修复建议。

也可以输出英文 HTML：

```bash
moon run cmd/main -- scan ../my_moonbit_project --format html --lang en --output report.html
```

### 6.3 Markdown 报告

如果你想把报告保存成文档，可以使用 Markdown：

```bash
moon run cmd/main -- scan ../my_moonbit_project --format markdown --output DOC_REPORT.md
```

参数含义：

- `--format markdown`：使用 Markdown 格式输出。
- `--output DOC_REPORT.md`：把结果写入 `DOC_REPORT.md`。

Markdown 报告适合作为临时评审材料发给项目维护者、评审人员，或放进 CI 产物中。

Markdown 也支持语言参数：

```bash
moon run cmd/main -- scan ../my_moonbit_project --format markdown --lang en --output DOC_REPORT.md
```

### 6.4 JSON 报告

如果你希望其他程序读取扫描结果，可以使用 JSON：

```bash
moon run cmd/main -- scan ../my_moonbit_project --format json --output doc-report.json
```

JSON 报告适合后续接入网页展示、CI 自动判断、统计面板或其他工具链。

### 6.5 哪些报告文件不建议提交

扫描报告通常是本地评审产物，不建议直接提交到仓库。项目默认忽略这些文件：

- `DOC_REPORT.md`
- `DOC_REPORT.html`
- `DOC_REPORT*.html`
- `report.html`
- `doc-report.json`

如果你确实希望把某次报告作为评审材料纳入版本记录，可以换一个明确的文件名，并在提交说明中解释它的用途。一般情况下，更推荐提交源码、README、配置文件和用户文档，而不是提交扫描结果本身。

### 6.6 查看完整问题列表

终端文本报告默认只展示前 20 条 Issues，避免长项目刷屏。如果你要一次性查看全部问题，可以加：

```bash
moon run cmd/main -- scan ../my_moonbit_project --all-issues
```

也可以导出 Markdown 报告：

```bash
moon run cmd/main -- scan ../my_moonbit_project --format markdown --output DOC_REPORT.md
```

Markdown 报告更适合提交给维护者或评审人员阅读。

如果主要是人工阅读，HTML 报告通常比裸 Markdown 更舒服：

```bash
moon run cmd/main -- scan ../my_moonbit_project --format html --all-issues --output report.html
```

## 7. 排除不想扫描的目录

MoonDocCheck 默认会跳过一些常见生成目录或依赖目录，例如：

- `.git`
- `.moon`
- `.mooncakes`
- `.repos`
- `_build`
- `target`
- `build`

如果你的项目还有其他不想扫描的目录，可以使用 `--exclude`：

```bash
moon run cmd/main -- scan ../my_moonbit_project --exclude vendor
```

也可以重复使用：

```bash
moon run cmd/main -- scan ../my_moonbit_project --exclude vendor --exclude generated
```

这适合跳过第三方代码、生成代码、临时文件目录或大型测试数据。

如果这些排除规则会长期使用，推荐在扫描目录下创建 `moondoccheck.toml`：

```toml
exclude = [
  "examples/missing_docs",
  "fixtures",
  "testdata"
]

[rules]
check_readme = true
check_moon_mod = true
check_ci = true
check_generated_mbti = true

[coverage]
min_public_api_coverage = 90
```

`exclude` 适合排除故意写坏的示例、测试夹具、第三方代码或生成目录。命令行中的 `--exclude` 会和配置文件里的 `exclude` 同时生效。

## 8. 如何读懂报告

下面是一段简化后的文本报告示例：

```text
MoonDocCheck Report

Project: examples/missing_docs
Files scanned: 4
MoonBit source files: 1

Public API documentation:
  Total: 3
  Documented: 2
  Missing: 1
  Coverage: 66%

File coverage:
  - examples/missing_docs/sample.mbt: 2/3 documented (66%)

Issues:
  - examples/missing_docs/sample.mbt:8 Missing documentation for public API `missing_doc`
  - examples/missing_docs/sample.mbt:14 Weak documentation for public API `WeakDoc`
```

### 8.1 Project

`Project` 表示被扫描的目录。

### 8.2 Files scanned

`Files scanned` 表示实际参与扫描的文件数量。被默认忽略或被 `--exclude` 排除的文件不会计入。

### 8.3 MoonBit source files

`MoonBit source files` 表示扫描到的 `.mbt` 源文件数量。

### 8.4 Public API documentation

这一部分是最核心的统计：

- `Total`：公开 API 总数。
- `Documented`：已有文档注释的公开 API 数量。
- `Missing`：缺少文档注释的公开 API 数量。
- `Coverage`：文档覆盖率。

### 8.5 Overall assessment / 总体评价

这一部分给出一个面向用户和评审者的简短结论：

```text
Overall assessment / 总体评价:
  Level / 等级: High risk / 高风险
  Comment / 说明: Public API documentation is the main blocker. / 公开 API 文档覆盖率是当前主要短板。
```

评价依据包括：

- 公开 API 文档覆盖率。
- README 是否存在，并提供项目介绍和文档入口。
- `moon.mod` 元数据是否存在。
- `pkg.generated.mbti` 是否存在。
- CI 是否包含 `moon check` 和 `moon test`。

这个评价不是 MoonBit 官方结论，而是 MoonDocCheck 根据项目文档信号给出的发布前参考。

报告还会列出 `Top missing-doc files / 缺文档重灾区`。如果项目问题很多，建议优先处理这里列出的文件，因为它们通常贡献了最多缺失 API 文档。

### 8.6 File coverage

这一部分按文件展示文档覆盖率。它能帮助你快速定位问题集中在哪个文件。

例如：

```text
examples/missing_docs/sample.mbt: 2/3 documented (66%)
```

表示这个文件里有 3 个公开 API，其中 2 个有文档注释，覆盖率是 66%。

### 8.7 Issues

`Issues` 是具体问题列表。每条问题通常包含：

- 文件路径。
- 行号。
- 问题说明。
- 简短修复提示。

例如：

```text
examples/missing_docs/sample.mbt:8 Missing documentation for public API `missing_doc`
```

表示 `sample.mbt` 第 8 行的公开 API `missing_doc` 缺少文档注释。

对于缺少 API 文档的问题，通常在对应声明前补充 `///` 注释即可：

```moonbit
/// Return a sample value used by the demo.
pub fn missing_doc() -> Int {
  42
}
```

### 8.8 下一步

`下一步` 不是固定模板，而是根据当前报告生成。

例如：

- 如果公开 API 文档缺失很多，会优先建议补 `///` 文档注释。
- 如果 README 缺少使用入口，会建议补项目入口、文档跳转或简短 Quick start。
- 如果普通 MoonBit 代码块很多但没有 `mbt check`，会建议把关键示例改成可检查代码块。
- 如果项目只有 `moon.mod.json`，会提示这是旧版格式。
- 如果 CI 通过脚本运行检查，会显示脚本式验证，而不是简单判定为没有 CI。

## 9. MoonDocCheck 会检查哪些文件

### 9.1 `.mbt`

MoonBit 源文件。MoonDocCheck 会从这些文件中提取公开 API，并检查它们是否有文档注释。

重点检查内容：

- `pub fn`
- `pub async fn`
- `pub fn Type::method`
- `pub struct`
- `pub enum`
- `pub type`
- `pub trait`
- `pub suberror`
- `pub impl`
- `pub(all) fn`
- `pub(all) struct`
- `pub(all) enum`
- `declare pub`

MoonDocCheck 只把公开 API 前方连续的 `///` 注释视为 API 文档。写在声明后面的行尾注释不会被当作文档注释，因为它更适合作为实现说明，而不是生成给用户阅读的公开文档。

### 9.2 Markdown 文件

包括 `.md` 和 `.mbt.md`。

MoonDocCheck 会统计代码块，并识别：

- `mbt check`
- `mbt nocheck`
- `moonbit`

### 9.3 README

README 是项目入口文档。MoonDocCheck 更关注它是否能帮助新读者快速理解项目，而不是要求把所有命令都堆在 README 中。

一个更推荐的 README 结构是：

- 项目介绍。
- 项目价值和适用场景。
- 开头目录，能跳转到中文版、英文版和用户指南。
- 简短使用入口或 Quick start。
- 更详细文档的链接，例如 `docs/USER_GUIDE.md`。
- 许可证说明。

### 9.4 `moon.mod` 和 `moon.mod.json`

MoonBit 项目的模块元数据文件。MoonDocCheck 会优先检查 `moon.mod`，也会识别旧版 `moon.mod.json`。

MoonDocCheck 会检查其中是否包含常见发布信息，例如：

- `name`
- `version`
- `description`
- `repository`
- `license`
- `keywords`
- `readme`

### 9.5 `pkg.generated.mbti`

这是 `moon info` 生成的公开接口摘要。它能帮助维护者审查项目暴露给使用者的 API。

如果项目没有生成这个文件，MoonDocCheck 会提示。

### 9.6 GitHub Actions

MoonDocCheck 会检查 `.github/workflows/` 中的工作流文件，并识别是否运行了常见 MoonBit 命令：

- `moon check`
- `moon test`
- `moon fmt`
- `moon info`
- `moon run`

这些命令代表项目是否有基础自动化质量检查。

如果 workflow 没有直接写 `moon check` 或 `moon test`，但调用了 `scripts/devcheck.sh` 这类脚本，MoonDocCheck 会把它识别为脚本式验证。它不会展开脚本内容做深度分析，但会避免把这种项目简单判定为完全没有验证。

## 10. 常见问题与修复方式

### 10.1 Missing documentation

问题示例：

```text
Missing documentation for public API `parse`
```

修复方式：

```moonbit
/// Parse source text into a project report.
pub fn parse(source : String) -> ProjectReport {
  ...
}
```

### 10.2 Weak documentation

问题示例：

```text
Weak documentation for public API `Config`
```

可能原因：

```moonbit
/// TODO
pub struct Config {
  enabled : Bool
}
```

修复方式：

```moonbit
/// Configuration used to control project scanning behavior.
pub struct Config {
  enabled : Bool
}
```

### 10.3 README 信息不足

如果 README 缺少入口信息，建议优先补充项目介绍、目录和文档跳转，而不是把完整命令手册都放在 README 里。例如：

````markdown
# Project Name

Short project introduction.

## Contents

- [中文介绍](#中文介绍)
- [English Overview](#english-overview)
- [User Guide](docs/USER_GUIDE.md)

## 中文介绍

说明项目解决什么问题，为什么值得使用。

## English Overview

Explain what the project does and why it is useful.
````

具体安装、运行、配置和报告解读内容，更推荐放到 `docs/USER_GUIDE.md`。

### 10.4 `moon.mod` 元数据不足

可以检查 `moon.mod` 是否包含类似信息：

```toml
name = "user/project"
version = "0.1.0"
readme = "README.md"
repository = "https://github.com/user/project.git"
license = "MIT"
description = "A short project description."
keywords = ["moonbit", "documentation"]
```

### 10.5 缺少 `pkg.generated.mbti`

运行：

```bash
moon info
```

然后确认生成的 `pkg.generated.mbti` 是否应该进入版本控制。

### 10.6 示例或夹具影响覆盖率

如果项目中有故意缺文档的反面示例，例如：

```text
examples/missing_docs
```

可以用配置文件排除：

```toml
exclude = [
  "examples/missing_docs"
]
```

这样主项目的文档覆盖率不会被教学示例或测试夹具拉低。

## 11. 推荐工作流

第一次整理项目文档时，可以按这个顺序使用 MoonDocCheck：

1. 运行 `moon check` 和 `moon test`，确认项目本身可用。
2. 运行 `moon info`，生成接口摘要。
3. 在 MoonDocCheck 仓库根目录运行 `moon run cmd/main -- scan ../my_moonbit_project` 查看待检测项目的终端报告。
4. 优先修复 `Issues` 中的缺失 API 文档。
5. 补充 README 的项目介绍、价值说明、目录跳转和用户指南入口。
6. 补充 `moon.mod` 中的描述、仓库、许可证等元数据。
7. 再次运行扫描，确认覆盖率和问题列表改善。
8. 如需人工评审，运行 `--format html --output report.html`。
9. 如需给评审者临时留档，运行 `--format markdown --output DOC_REPORT.md`。

发布或评审前推荐使用这一组命令：

```bash
moon check
moon test
moon info
moon run cmd/main -- scan ../my_moonbit_project
```

其中 `moon info` 是 MoonBit 官方工具，用于生成 `pkg.generated.mbti` 公开接口摘要。MoonDocCheck 会检查这个摘要是否存在，并结合 README、公开 API 文档、元数据和 CI 信号判断项目是否具备发布前的基础文档准备。

## 12. 当前限制

MoonDocCheck 当前是轻量级检查器，不是完整 MoonBit 编译器前端。

需要注意：

- 它不会执行完整语义分析。
- 它不会自动修改源码。
- 它不会判断自然语言文档是否真正“写得好”。
- 它更适合发现明显缺失、明显占位和项目文档结构问题。
- 它支持常见多行声明、公开方法、异步函数和公开 impl，但仍不是完整语法解析器。
- GitHub URL 扫描只支持公开仓库，并依赖本机 `git`。

这些限制不会影响它作为项目发布前文档自检工具的主要用途。

## 13. 给新用户的最短路径

如果你只想快速试一下，运行：

```bash
moon run cmd/main -- scan examples/missing_docs
```

然后再运行：

```bash
moon run cmd/main -- scan examples/good_project
```

对比两个报告，你会很快理解 MoonDocCheck 希望帮助你发现什么问题。