導入
ドキュメント ジェネレーターは、プログラマ (これは API ドキュメント)、エンド ユーザー (これはユーザー ガイド)、またはその両方を対象としたドキュメントを作成するプログラミング ツールです。これらのドキュメントを管理するために、ジェネレーターは通常、特定の方法でコメントされたソース コードに依存し、場合によってはバイナリ ファイルにも依存します。
生成されるドキュメントは高度に技術的なものになる可能性があり、主にプログラミングインターフェイス (API)、データ構造、アルゴリズムを定義および説明するために使用されます。たとえば、このドキュメントを使用して、変数m_name が人の姓名を参照していることを説明できます。コードドキュメントは正確であることが重要ですが、保守が困難になるほど冗長でないことも重要です。
doxygenや javadoc などのドキュメント ジェネレーターは、ソース コードからドキュメントを自動的に生成します。ソース コードからコメントを抽出し、テキスト、HTML、PDF、DocBook、または RTF ファイルなどの形式でリファレンス マニュアルを作成します。コード ドキュメントは多くの場合、リファレンス ガイドのスタイルで編成されており、プログラマは関数やクラスをすぐに見つけることができます。
ソース コードからのドキュメント ジェネレーターの利点は、ソース コードがコメント形式のエンコードされたドキュメントに近いことです。プログラマーはコードを参照してコードを作成し、ソース コードの開発に使用したのと同じツールを使用してドキュメントを作成できます。これにより、ドキュメントの更新がはるかに簡単になります。
もちろん、欠点は、この種のドキュメントを編集できるのはプログラマだけであり、出力を更新するかどうかはプログラマ次第であることです (たとえば、夜間にcrontab を実行してドキュメントを更新するなど)。これをデメリットではなくメリットとして捉える人もいるかもしれません。
例
以下は、javadoc で抽出できる Java ソース コード ドキュメントの例です。
/** * チェスのゲームの手を検証します。 * * @param columnDepart 移動する駒の列 * @param linepayment 移動する駒の行 * @param columnArrival 移動先ボックスの列 * @param lineArrival 移動先ボックスの行 * @return true(true) 移動失敗の場合は有効、または無効な場合は false (false) */ boolean isAValidMove ( int columnStart, int rowStart, int columnArrival, intlineArrival ) { ... }
ソフトウェア
- Doxygen (多言語、特に C ファミリの言語)
- javadoc (Java)
- MakeDoc (リボル2000)
- MakeDoc (多言語、1994 年) は、MakeDoc、MakeDocu などの新しいソフトウェアと同名であるため、 1990 年のmkdから元の名前を取り戻しました。
- ポッド (Perl)
- RDoc (ルビー)
- ROBODoc (最も一般的な言語を含む多言語ですが、拡張も可能)
- TwinText (最も一般的な言語を含む多言語ですが、拡張することもできます)
