C++、Java、IDL、C 用のドキュメント生成システム。 ソースコード中のドキュメンテーションコメントから、HTML 形式などのドキュメントを生成することができる。 Graphviz を用いてクラス間の関係のグラフが生成する機能などがある。
ドキュメンテーションコメントがなくてもクラス間の関係などを解析してドキュメント化してくれるので、他人のソースコード群をもらったらとりあえずこれを書けて概略を掴むというのも手である。
C のプログラムの場合は ISO C のプロトタイプの形で関数が宣言/定義されている必要がある。 古い形式の場合、protoize 等で変換する必要あり。
doxygen task (http://www.bgw.org/projects/java/ant/) を用いて Ant から doxygen を呼び出せる。
doxygen では様々なスタイルでドキュメントを書くことができる。 以下は Naney がフォーマットを統一するためのメモ。
基本的には JavaDoc スタイルを使う。
/** * @brief 要約説明文。 * 要約説明文(続き)。 */
/// @name グループの名前 //@{ void method1(); void method2(); //@}
/** * @brief 要約説明文。 * 要約説明文(続き)。 * JAVADOC_AUTOBRIEF は NO で。 * * 上に空行を入れて詳細説明文。 * * @param[in] 入力引数名 引数の説明。 * @param[in,out] 入出力引数名 引数の説明。 * @param[out] 出力引数名 引数の説明。 * * @return 返り値の説明。 */
int var; ///< 要約説明文。
2001年6月1日より。
WiKicker のソースコードを人に説明するのにプリントアウトして説明するのに、doxygen のようなツールが欲しいのだけれど Perl 用のものはないのかな。
というのが希望。1 だけなら結構いろいろなツールがあり、1 + 2 なら perltidy で実現できる。 しかし 3、4 までしてくれるツールが見つけられない。
とりあえず perltidy の Perl::Tidy と File::Find で再帰的にまとめて HTML に変換するスクリプトだけは書いて、一気に変換だけはできるようにしておいた。
インデックスの作成までは面倒なので未着手。
ソースコードに To Do タスクを埋め込むのにどの形式が良さそげか調査。
トークンとして "TODO" が登録済み。 大文字小文字を区別する。 コメントの先頭に TODO がある必要がある。 この設定の時に @TODO と書いても認識しない。
トークンには @ 文字を設定できない。
テキストとして "TODO" が登録済み。 大文字小文字を区別する。 コメントの先頭でなくても良い。
この設定の時に @TODO と書いても認識しない。
IDE じゃないけど。 ドキュメンテーションコメント中に \todo または @todo。 \TODO や @TODO は駄目。
コメントの先頭に TODO を書くという書式で統一しておくのが良さそげ。
Visual Studio 2005 がコメントの先頭以外でも認識してくれるのなら
/** @todo TODO 説明 */
としておけば、ちょっと冗長だけれど doxygen にも認識させられるのなあと思ったり。
Naney (なにい)です。株式会社ミクシィで SNS 事業の部長をしています。
nDiki は1999年1月に始めたコンピュータ日誌を前身とする Naney の Web 日記(兼パーソナルナレッジベース)です。
#nNote タグがついている記事は他の記事に比べて、より断片的・未整理・不完全なちょっとしたノートです。まだ結論に至っていない考えなども含まれます。頻繁/大幅に更新したり削除したりすることがあります。
ナレッジベースアプリケーション Obsidian で書いているノートの一部を notes.naney.org で 公開しています。
※内容は個人的見解であり所属組織とは関係ありません。