ドキュメンテーションジェネレータ
ドキュメンテーションジェネレータ（英: documentation generator）は、特別なコメントが記述されたソースコードファイル（ソースファイル）の集合、または一部の例[要説明]ではバイナリファイルの集合から、プログラマ向けのAPIリファレンス（プログラミングガイド）やエンドユーザー向けのマニュアル（エンドユーザーガイド）、またはその両方を対象としたドキュメンテーション[注釈 1]を生成するプログラミングツールである。
プログラミング言語の場合、ソースファイルやヘッダーファイル自身、名前空間またはパッケージ、ユーザー定義のデータ型（列挙型や構造体やクラスなど）、サブルーチン（関数）、構造体やクラスのメンバー（フィールドやメソッドやコンストラクタなど）、グローバル変数あるいは定数、といったプログラムの構成要素の宣言または定義に対して、一定の構文規則を持つコメントを前置または後置したものを、ジェネレータプログラムにパースさせることでドキュメントを生成する。ドキュメント化の対象となる要素は一般的に外部仕様となりうるものに限られ、サブルーチン内部のローカル変数などは対象外となる。
ジェネレータを活用することで、手動で付随ドキュメントを作成するよりも遥かに効率的に作成することが可能となる。またソースコードを修正する際にコメントも併せてメンテナンスし、再度ジェネレータに処理させることで、自動的にドキュメントをアップデートすることができるようになる。
例
[編集]ドキュメンテーションジェネレータとして代表的なものに、Javadoc、Doxygen、Plain Old Documentation、Sphinxなどが挙げられる。記法にある程度の互換性があるものもあれば、そうでないものもある。
ジェネレータはソースコードを解析してコメントに対応する構文上の要素を抽出する必要があることから、静的コード解析ツールとしての機能を併せ持つものもあり、クラスの継承階層図などを生成する機能を持つものもある。
ジェネレータプログラムは通例コマンドラインツール（コンソールアプリケーション）だが、多くの統合開発環境（IDE）ではシームレスに統合されており、ドキュメンテーションコメントの書かれたプログラム要素に関する情報がコードエディター上のツールチップ（ツールヒント）として表示され、エディター上で直接クイックリファレンスとしても利用できるようになっている。クイックリファレンスの用途では、ジェネレータプログラムを明示的に実行する必要はない。
Microsoft Visual Studioでは、XMLタグ形式の特殊なドキュメンテーションコメント記法（XML documentation comment）をサポートしており、コメントの書かれたプログラム要素に関する情報がIntelliSenseとの連携によりデータベース化され、クイックリファレンスとしても利用できる[2]。C#やVB.NETのコードエディター上ではコメント開始トークン（それぞれ///あるいは'''）を入力することで一定のテンプレートを自動的に挿入してくれる自動補完機能がサポートされており、アセンブリ境界を超えた.NET言語間共通のリファレンスとしても利用できる。C++（Microsoft Visual C++）では自動補完がサポートされていないものの、XMLドキュメンテーションコメントの形式に沿って手動で記述してドキュメントを生成することは可能である[3]。
同様に、EclipseやIntelliJ IDEAのようなJavaをサポートするIDEでは、Javadoc形式で書かれたドキュメンテーションコメントをクイックリファレンスとしても利用でき、またJavadoc形式のドキュメンテーションコメントの自動補完がサポートされている。
脚注
[編集]注釈
[編集]出典
[編集]関連項目
[編集] | この項目は、コンピュータに関連した書きかけの項目です。この項目を加筆・訂正などしてくださる協力者を求めています（PJ:コンピュータ/P:コンピュータ）。 |