MoonDocCheck

Demo 展示

HTML 报告	Markdown 报告	终端报告
GitHub Pages HTML Demo

Markdown 和终端 Demo 受限于截图长度，仅展示报告开头。

中文

项目简介

MoonDocCheck 关注的是 MoonBit 项目的“文档准备度”：当一个陌生开发者打开仓库时，他能不能快速理解项目价值、找到使用入口，并判断这个项目是否值得信任。

它不会替代 moon check、moon test 或 MoonBit 官方文档工具，而是补充检查那些常常被忽略的文档信号：公开 API 是否有说明、README 是否像项目门面、示例是否可检查、元数据是否完整、接口摘要是否生成、CI 是否体现基础验证。

为什么值得使用

很多项目的代码已经能运行，但对外展示还不够完整。评审者或使用者通常不会先读完整源码，而是先看 README、API 注释、示例和项目元数据。

MoonDocCheck 把这些信号整合成一份报告，帮助维护者在发布、参赛、课程提交、社区评审或团队交接前快速发现短板。

它尤其适合：

MoonBit 开源项目发布前自检。
比赛、课程或社区项目评审。
为已有项目补全文档。
快速了解陌生 MoonBit 仓库的文档成熟度。
团队内部统一文档质量标准。

核心能力

检查公开 MoonBit API 是否缺少 /// 文档注释。
识别 TODO、FIXME 等弱文档。
按项目和文件统计 API 文档覆盖率。
找出缺文档最集中的文件。
检查 README 是否包含项目介绍、文档入口和许可证信息。
统计 Markdown 中的 MoonBit 示例，识别 mbt check / mbt nocheck。
检查 moon.mod 元数据，并识别旧版 moon.mod.json。
检查 pkg.generated.mbti 是否存在。
检查 GitHub Actions 或脚本式验证信号。
支持扫描本地目录和公开 GitHub 仓库 URL。
支持文本、HTML、Markdown、JSON 四种报告格式。

基础使用

以下命令需要在 MoonDocCheck 仓库根目录中运行。扫描与 MoonDocCheck 并列存放的其他 MoonBit 项目：

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

生成适合人工评审的 HTML 报告：

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

扫描公开 GitHub 仓库：

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

更完整的参数、配置文件、报告解读和排除规则请查看用户指南。

MoonDocCheck 会生成包含摘要、总体评价、文件覆盖率、问题清单和下一步建议的报告。Markdown 报告适合作为临时评审材料，JSON 报告适合接入其他工具链。生成的报告文件通常是本地评审产物，默认不建议提交到仓库。

中文文档

用户指南：完整使用方式、报告解读、配置文件和常见问题。
MoonBit checked documentation：官方 .mbt.md、mbt check 和文档代码块说明。
Moon module configuration：官方 moon.mod 配置说明。
Moon package publishing guide：官方包发布与元数据说明。

English

Overview

MoonDocCheck is a documentation quality checker for MoonBit projects.

It focuses on documentation readiness: when a new developer opens a repository, can they understand what the project is, find the right entry points, and trust the project enough to start using it?

MoonDocCheck does not replace moon check, moon test, or official MoonBit documentation tools. It complements them by checking documentation-facing signals that matter during publishing, review, handoff, and open-source evaluation.

Why It Matters

A project can compile and still be difficult to adopt. Reviewers and users usually look at the README, API docs, examples, metadata, and CI signals before reading the full source code.

MoonDocCheck gathers those signals into one report so maintainers can quickly find documentation gaps before release or review.

It is useful for:

Pre-release checks for MoonBit open-source packages.
Course, contest, or community project review.
Improving documentation for existing repositories.
Understanding the documentation maturity of an unfamiliar MoonBit project.
Keeping documentation quality consistent across a team.

Core Features

Detect missing /// comments on public MoonBit APIs.
Detect weak placeholder documentation such as TODO and FIXME.
Summarize API documentation coverage by project and file.
Highlight files with the most missing API docs.
Check whether README has a project overview, documentation entry, and license signal.
Count MoonBit examples in Markdown and recognize mbt check / mbt nocheck.
Inspect moon.mod metadata and recognize legacy moon.mod.json.
Check whether pkg.generated.mbti exists.
Inspect GitHub Actions and script-based validation signals.
Scan local directories and public GitHub repository URLs.
Render text, HTML, Markdown, and JSON reports.

Basic Usage

Run the following commands from the MoonDocCheck repository root. To scan another MoonBit project stored next to MoonDocCheck:

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

Generate an HTML report for human review:

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

Scan a public GitHub repository:

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

For full options, configuration, report interpretation, and exclusion rules, see the User Guide.

MoonDocCheck reports include a summary, overall assessment, file coverage, issue list, and issue-specific next steps. Markdown reports are useful as temporary review artifacts, and JSON reports are useful for tool integration. Generated reports are local artifacts by default and are usually not committed.

Documentation

User Guide: full usage guide, report explanation, configuration, and examples.
MoonBit checked documentation: official .mbt.md, mbt check, and documentation code block behavior.
Moon module configuration: official moon.mod configuration reference.
Moon package publishing guide: official package metadata and publishing workflow.

指导手册

License

This project is licensed under the MIT License.