documentation-generator

ドキュメント生成ツール

目的

別のドキュメントを正確な状態で作成し、すぐに古くなるものではなく、コードを信頼できる情報源としてドキュメントを作成します。入力はコードベース、モジュール、または API 仕様です。出力は、ソース内のドキュメントコメント、生成されたリファレンスサイト、README、変更履歴、図などに加え、まだドキュメント化されていない内容の正直な一覧です。

コードのそばに書かれたドキュメントは、数週間で実態とずれていきます。コードから生成されたドキュメントがずれるのは、誰かがコメントを変更せずにシグネチャを変更したときだけです。ジェネレーターはその変更を検出して報告できます。この検出こそが価値の大半を占めており、文章を書くこと自体は簡単です。

使用する場面

• 公開 API のリファレンスドキュメントがない、またはリファクタリング後に古くなっている
• 公開シンボルのドキュメントコメントがなく、ツールチェーンが警告を出している
• OpenAPI 仕様はあるが、人が読める REST ドキュメントがない
• コミットが一定の規約に沿っており、リリースに変更履歴が必要
• 新しいコントリビューターが状況を把握するための README やアーキテクチャ概要を必要としている

このスキルの対象外：

• ユーザーと一緒に設計ドキュメント、提案書、仕様書を作成する → doc-coauthoring
• サードパーティライブラリのドキュメントを調べる → find-docs
• ドキュメントの不足も指摘する、プロジェクト全体の監査 → code-analyzer
• 特定の図を導出するのではなく、手作業で描く → draw-io-diagram-generator
• 既存のドキュメントを別の形式に変換する → markitdown

前提条件

1. 何をドキュメント化し、どのツールチェーンがすでに管理していますか？ ファイル拡張子ではなく、ビルドファイルから判定します。ドキュメント用ツールチェーンはそこに宣言されており、すでに導入されているプロジェクトでは、主な方針がすでに決まっているためです。

ビルドファイル／シグナル	スタック	リファレンス
build.gradle.kts に kotlin("multiplatform") または org.jetbrains.dokka がある	Kotlin / KMP / CMP	kotlin-kmp.md
pubspec.yaml	Flutter / Dart	flutter-dart.md
Package.swift、*.xcodeproj、*.docc/	Swift（iOS/macOS）	swift-apple.md
Cargo.toml	Rust	rust-cpp.md
CMakeLists.txt、Doxyfile、conanfile.txt	C / C++	rust-cpp.md
openapi.yaml、swagger.json、paths: + components:	REST API 仕様	api-specs.md
package.json、pyproject.toml、go.mod	JS/TS、Python、Go	other-languages.md
README、CHANGELOG、図、バージョン管理されたサイト	任意 — 分野横断	project-docs.md

スタックのリファレンスを1つ読み込み、タスクで必要な場合は project-docs.md も読み込みます。すべて読み込むと、対象外のツールチェーンの慣習が混在し、必要な情報が埋もれてしまいます。

2. すでにどのようなドキュメントがありますか？ 生成を始める前に、現在のドキュメントを確認してください。docs/ ディレクトリ、既存の README、すでにドキュメント化されている公開シンボルが3、4個あれば確認します。文体、詳しさ、構成、使用言語はすでに決まっています。どのような慣習よりも、それらに合わせることが重要です。周囲のページとまったく異なる読み味の生成ページは、手作業で書き直されることになります。会話の言語ではなく、既存のドキュメントの言語で書いてください。英語のコードベースについて、ハンガリー語で依頼された場合でも、ドキュメントコメントは英語で書きます。

# existing docs, doc config, and the conventions already in use
ls -d docs doc site .docc *.docc 2>/dev/null
find . -maxdepth 2 \( -name 'Doxyfile*' -o -name 'mkdocs.yml' -o -name 'dokka*' \
  -o -name '*.docc' -o -name 'cliff.toml' -o -name 'redocly.yaml' \) -not -path '*/build/*'

3. ドキュメント化できるほどコードは安定していますか？ まもなく変更される API をドキュメント化すると、作業が二度無駄になります。対象がリファクタリングの途中であれば、そのことを伝え、確定している部分のドキュメント化を提案してください。

ワークフロー

ステップ 1：読者が必要としているものを判断する

ドキュメントは、文章の質が低いことよりも、読者に対する説明の粒度が合っていないことで失敗することのほうがはるかに多いです。誰が読み、何をしようとしているのかに基づいて、種類を選びます。

読者の疑問	成果物	生成元
「この関数は何をするのか？」	API リファレンス	公開シンボルのドキュメントコメント
「このエンドポイントはどう呼び出すのか？」	REST リファレンス	OpenAPI 仕様
「これはどう使い始めればよいのか？」	README／スタートガイド	パッケージのメタデータ＋実際に動作する例
「これはどのように連携しているのか？」	アーキテクチャ概要	モジュールグラフ、レイヤー構成、主要な型
「何が変わったのか？」	変更履歴	コミット履歴
「X を実現するにはどうすればよいのか？」	ガイド／チュートリアル	どちらでもありません。これは生成するのではなく、執筆するものです。

最後の行は重要です。ガイドはシグネチャから導き出せません。順序や動機は作者の頭の中にあるためです。ユーザーから依頼された場合は、その背景をユーザーから聞き出すか、doc-coauthoring に引き継いでください。

ステップ 2：ドキュメントが不足している箇所を見つける

ファイルを読む代わりに、ツールチェーンに確認させましょう。どのスタックにも、公開シンボルのドキュメント不足を警告する仕組みがあります。スタックのリファレンスには、Rust の #![warn(missing_docs)]、Dart の public_member_api_docs、Doxygen の WARN_IF_UNDOCUMENTED など、具体的な設定方法が記載されています。

不足箇所はアルファベット順ではなく、優先度順に並べます。

1. まず公開 API の範囲から。 呼び出し側から見えないものは、ドキュメントに記載する必要がありません。
2. 末端より先に入口から。 最初にインスタンス化する型には、プライベートヘルパーより先にコメントを付けます。
3. 明白な動作より、明白でない動作から。 単位、スレッド処理、null 許容性、所有権、エラー条件、副作用こそ、読者が実際に知りたいことです。

シグネチャを言い換えただけのコメント（getName() に対する /** 名前を返します。 */ など）はノイズです。保守コストが増えるだけで、情報は何も増えません。そのコメントは省略し、省略したこととその理由を伝えてください。

ステップ 3：ドキュメントコメントを書く

ソース内に、スタック固有のマークアップとタグを使って記述します。構文や慣用表現はスタックのリファレンスを参照してください。どのスタックでも、有用なコメントと内容のないコメントを分けるポイントは共通しています。

• 仕組みではなく、契約を最初に書きます。 実装方法ではなく、保証する内容を書きます。実装は変わりますが、呼び出し側が依存するのは契約です。
• シグネチャでは伝わらないことを記載します。 単位、有効範囲、null 許容性、スレッド／アイソレート／アクターとの親和性、所有権とライフタイム、ブロッキングの有無、べき等性などです。
• 呼び出し側が対処すべきすべてのエラーパスを記載します。 スローされる例外、Err のバリアント、失敗する future、ゼロ以外の戻り値と、それぞれが発生する条件を示します。
• ツールチェーンが対応している場合は、コンパイル可能な例を記載します。 rustdoc のドックテスト、KDoc の @sample、DocC のスニペット、Doxygen の @snippet などです。CI で破損が検出されるため、古くなったまま気づかれずに残ることがない唯一の例です。
• 説明を繰り返すのではなく、リンクします。 どのツールチェーンにもドキュメント内のリンク機能があります。説明を重複させると、正確さを保つべき箇所がもう一つ増えてしまいます。

シグネチャを目の前にしていても疑問が残る呼び出し側に向けて書いてください。

ステップ 4：出力を生成して確認する

ジェネレーターを実行し、警告を確認してください。リンク切れ、ドキュメント化されていないシンボル、未解決の参照こそ、このスキルが検出するためのドリフトです。コマンドはスタックのリファレンスに記載されています。

毎回確認しておきたいことが 2 つあります。

• サンプルはコンパイルして実行できますか？ ツールチェーンに用意されている場合は、doc-test を実行してください。コンパイルできないサンプルは、サンプルがないよりも悪いものです。
• リンク先は存在しますか？ ドキュメント内のリンク切れは、通常、シンボルが名前変更されたのに参照が更新されていないことを示します。これはドリフトの兆候であり、書式上の些細な問題ではありません。

ジェネレーターがインストールされていない、または実行できない場合（ツールチェーンが不足している、npx 用のネットワークがないなど）は、レポートにその旨を記載し、ユーザーが実行すべき正確なコマンドを示してください。確認せずにツールチェーンをグローバルにインストールしてはいけません。また、生成していない出力を生成したかのように説明してはいけません。ソースコメントだけでも、十分に価値があります。

出力は簡潔にしてください。ドキュメントジェネレーターの出力は冗長なので、実行結果全体を貼り付けるのではなく、警告とエラーに絞ってください。生成されたサイトをコンテキストに読み込んではいけません。これはビルド出力であり、レビュー対象はソースコメントです。

ステップ 5：ドキュメント化されている内容と、されていない内容を報告する

## Documentation added
<files touched, and what each now documents>

## Generated
<command run, output location, and the real result — including warning count>

## Still undocumented
<specific public symbols or endpoints, as `file:line` — with why, where there is a reason>

## Drift found
<docs that contradict the implementation, if any>

ドリフトのセクションは、実際に対応が取られる部分です。コードに存在しなくなった動作を説明するコメントは、コメントがない場合よりも悪質です。信じられてしまうからです。修正が作業範囲外であっても、報告してください。

操作

操作	ユーザーの意図	出力
comments（デフォルト）	「このクラス／モジュールをドキュメント化する」	プロジェクトのマークアップ形式でソースに記述されたドキュメントコメント
reference	「API ドキュメントを生成する」「Dokka／DocC／dartdoc を設定する」	ジェネレーターを設定して実行し、リファレンスサイトまたは Markdown を生成
api	「この REST API をドキュメント化する」	OpenAPI 仕様に基づく人が読める REST ドキュメント。仕様の lint に関する問題も報告
readme	「README を作成する」	パッケージのメタデータと、動作を確認したサンプルを基に README のひな形を作成
changelog	「このリリースの変更履歴を生成する」	最後のタグ以降のコミットに基づき、Keep a Changelog 形式の項目を作成
architecture	「全体の構成を説明する」	ビルドグラフから導出した Mermaid のモジュール／レイヤー図を含む概要ドキュメント
audit	「ドキュメントが古くなっている」	ドキュメント化されていないシンボルと、ドキュメントと実装のドリフトを優先順位順に列挙。修正は依頼された場合のみ

重要な制約

• 読んでいない動作をドキュメント化してはいけません。 ざっと目を通しただけのコードに、もっともらしいコメントを書くのは、書いた人がいなくなった後も残る、自信に満ちた嘘です。実装を読むか、質問してください。
• API の仕様を捏造してはいけません。 コードまたは仕様にないエンドポイント、パラメーター、エラーコード、設定キーを追加してはいけません。読者はコードよりもドキュメントを信頼するため、ここでの捏造は特に大きな損失を招きます。
• ドキュメントを作成する際に、実装コードを変更してはいけません。 明確さのための名前変更や、コメントから判明した問題の「修正」は別の変更です。提案はしても、紛れ込ませてはいけません。
• プロジェクトがすでにコミットしている場合を除き、生成された出力をコミットしてはいけません。 まず .gitignore で docs/api/、target/doc/、doc/api/ を確認してください。生成済みドキュメントをコミットすると、レビュー時には古くなっています。
• サンプルに認証情報、内部ホスト名、顧客データ、未発表の製品名を記載してはいけません。 ドキュメントはリポジトリの成果物の中で最も広く公開されるものです。ツールチェーン独自のプレースホルダー規則を使用してください。
• 生成されたドキュメントのために既存のドキュメントを削除してはいけません。 手書きのドキュメントには、通常、ジェネレーターでは再現できない背景情報が含まれています。統合するか、確認してください。
• 解釈できないコミットについて、変更履歴の項目を捏造してはいけません。 そのまま「その他」の見出しの下に列挙し、人が分類できるようにしてください。

参考資料

• kotlin-kmp.md — KDoc タグ、Dokka のセットアップとタスク、KMP のソースセットごとのドキュメント、@sample、expect／actual のドキュメント
• flutter-dart.md — dartdoc コメント、dart doc、マクロとテンプレート、pub.dev のメタデータ、ドキュメントの Lint
• swift-apple.md — DocC マークアップ、.docc カタログ、トピック、チュートリアル、swift package generate-documentation、静的ホスティング
• rust-cpp.md — rustdoc、ドキュメントテスト、ドキュメント内リンク、docs.rs のメタデータ、Doxygen、Breathe／Sphinx
• api-specs.md — OpenAPI／Swagger の Lint、リファレンスサイトと Markdown の生成、既存の仕様書のドキュメント化
• other-languages.md — TSDoc／TypeDoc、Python の docstring と Sphinx／MkDocs、Go のドキュメントコメント
• project-docs.md — README のひな形、Conventional Commits 形式の変更履歴、Mermaid によるアーキテクチャ図、バージョン管理されたドキュメントサイト