JSDocでJavaScript API文書を生成する際の版と出力管理

JSDocの仕事はAPI文書の生成

jsdoc/jsdocはJavaScript向けのAPIドキュメント生成ツールです。READMEの説明は短く、ソースのコメントや構造からドキュメントを作るCLIとして位置付けています。素材時点のGitHub情報ではstarsは15,454、forksは1,488、open issuesは459で、既定ブランチはmainです。最新リリース情報には4.0.4があり、リポジトリの更新時点は2024年10月19日です。

このツールの採用判断では、生成対象のJavaScript、コメント規約、テンプレート、出力場所が揃うかを見ます。JSDocを導入しただけで既存コードのコメントが正確になるわけではなく、文書の内容は入力ソースと設定に左右されます。まず小さなモジュールで入力からHTMLなどの生成物までを確認してください。

グローバル導入とローカル導入

READMEは、npm install -g jsdocで全体へ導入する方法と、npm install --save-dev jsdocでプロジェクトのpackage.jsonへ開発依存として保存する方法を示しています。チームのCIや複数プロジェクトで版を揃えるなら、ローカル導入とlockfileを使う構成が管理しやすくなります。グローバル導入は手元での試行には簡単ですが、端末ごとの版がずれる可能性があります。

JSDocはNode.js 8.15.0以降の安定版をサポートするとREADMEに記載されています。この対応表は資料時点の説明であり、現在のCIや採用するJSDoc版が必要とするNode.jsを別途確認します。npmがグローバル書き込みでsudoを要求する場合の権限問題も、実行環境の設定として記録してください。

CLIとoutディレクトリの流れ

ローカル導入では、./node_modules/.bin/jsdoc yourJavaScriptFile.jsを実行して文書を生成できます。グローバル導入ならjsdoc yourJavaScriptFile.jsです。出力先を指定しない場合、生成物はoutというディレクトリへ保存され、別の場所へ出したい場合は--destinationまたは-dを使います。全CLIオプションはjsdoc --helpで確認します。

この流れをCIへ置くときは、入力ファイルの一覧、設定ファイル、テンプレート、outの削除と生成の順序を固定します。生成された文書だけを成果物として保存し、node_modulesを含めるかどうかも決めます。READMEのコマンドは基本形なので、プロジェクト固有の構成やブラウザ向けの公開設定を推測して追加しないでください。

テンプレートと周辺ツールの選択

JSDocのコミュニティには、生成物の見た目やナビゲーションを変えるテンプレートがあります。READMEはjaguarjs-jsdoc、DocStrap、jsdoc3Template、minami、docdash、tui-jsdoc-template、better-docsを例に挙げています。テンプレートはJSDoc本体とは別のリポジトリで保守されるため、対応するJSDoc版、ライセンス、更新状況を個別に確認します。

ビルド連携にはGruntプラグイン、Gulpプラグイン、GitHub Actionが挙げられています。生成結果をMarkdownへ変換するjsdoc-to-markdownや、GitBookとの連携例も案内されています。これらは選択肢の一覧であって、JSDocに標準搭載された全機能ではありません。導入時は一つのテンプレートと一つのCI経路に絞り、生成物のリンク、コード例、公開範囲を点検してください。

バージョン更新を差分で管理する

READMEは、npmがpackage.jsonへcaret演算子を付ける既定動作を説明し、例として^3.6.3ではなく、最新パッチレベルに更新を限定しやすいtilde演算子を勧めています。採用版を固定する方法は、プロジェクトの依存管理方針とNode.jsの対応状況を合わせて決めます。

JSDocを更新したら、同じ入力ソースから生成した文書の差分を確認します。見出し、リンク、型表示、テンプレートの静的ファイルが変わる可能性があるため、成果物のレビューをCIへ置きます。リリース履歴には4.0.4と過去の3.5.5、3.5.4が記録されています。古い版の利用実績を理由に現在の環境が同じ動作をすると断定せず、採用版とNode.jsをセットで試験してください。

文書の所在と問い合わせ先

公式文書はjsdoc.appにあり、文書への貢献先としてjsdoc/jsdoc.github.ioが案内されています。質問先にはJSDoc Usersメーリングリストと、jsdocタグ付きのStack Overflowが挙げられています。ソースやドキュメントの変更を提案する場合は、CONTRIBUTING.mdを読むようREADMEに記載されています。

問い合わせ先の存在は、個別のサポート契約や応答時間を意味しません。社内で問題を調べるため、Node.jsの版、JSDocの版、実行コマンド、入力コメント、設定、テンプレート、エラーの全文を保存します。生成された文書を公開する場合は、ソースに含まれる秘密情報、内部URL、個人情報が出力へ現れないかも確認します。

Apache 2.0と採用前の確認

JSDocはApache License 2.0で提供されます。READMEは著作権者と貢献者、LICENSEファイルへの参照を示しています。利用、改変、配布を検討する際はJSDoc本体だけでなく、選んだテンプレート、プラグイン、GitHub Action、変換ツールのライセンスも分けて確認してください。

素材からは生成性能、互換性の完全な表、文書の正確性、商用サポートの保証までは確認できません。導入前にはローカル版をpackage.jsonへ固定し、Node.jsの実行環境を決め、入力からoutへの生成、destination変更、テンプレート追加、CI再実行を試します。生成物の公開範囲と、更新時に人が確認する差分を決められるなら、JSDocを開発工程へ組み込む判断がしやすくなります。

生成物のレビュー手順

CIにJSDocを組み込む場合は、入力ファイルの範囲と設定ファイルを固定し、生成前にoutを消去してから同じコマンドを実行します。差分では、API名、引数、戻り値、継承関係、リンク、テンプレートの静的ファイルを確認します。公開文書へ内部パスや秘密情報が出ていないかも点検してください。版を更新したときは、Node.js、JSDoc、テンプレート、プラグインの組み合わせを記録し、問題が起きた入力を保存します。READMEの例は入口であり、社内のコメント規約や公開審査は別の手順として設ける必要があります。

編集部の結論

JSDocは、JavaScriptのソースからAPIドキュメントを生成するCLIをプロジェクトへ組み込みたいチームに向く、目的の明確なツールです。グローバル導入か開発依存としてのローカル導入かを決め、Node.jsの対応版、package.jsonの依存固定、入力ファイル、出力先、テンプレートを先に揃えてください。READMEの既定出力はoutで、テンプレートやプラグインの品質まで含めた成果物を保証するものではありません。4.0.4など採用版を固定し、生成物の差分とCIでの再現性を確認してから運用へ組み込むのが適切です。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes