仕様書(ドキュメント)を作ろう。
プログラミングをしていて、よくソースファイルにコメントで説明を書いておいて、あとで見たりします。また、人によっては手書きでソースの説明などを残しておく人もいると思います。このようなものはプログラムの仕様書(ドキュメント)といいますが、折角、ソースに書いたコメントをもう一度、手書きでまとめ直すというのは二度手間です。そこで
ソースファイルに書いたコメントを元に仕様書を自動生成してくれるアプリケーションを使えば、手軽に仕様書が作れます。仕様書はhtmlやlatexの状態で出力されるので、見易く一般的です。このページでは、C,C++の仕様書を自動生成するdoxygenについて解説します。また、これとは別にfortran90でこのようなものがないか、筆者は探し回っていたのですが、rdocにパッチをあてて、fortran90用の仕様書自動生成を可能にしてくれるものを開発してくださった地球流体電脳倶楽部の「RDOC Fortran90/95 ソースコード解析機能強化版」を紹介します。
doxygen-introduction
まずは、doxygenで作成したC++プログラムの
仕様書サンプルを見て下さい。このプログラムは、一つのクラスWallet(wallet.h, wallet.cpp)と利用例(main.cpp)からなる簡単なプログラムです。「構成」のところをみるとクラスの説明が見られます。適当にリンクを辿ると、PublicやPrivateなどの関数、変数が表示されています。この仕様書は、ソースファイルに書かれたコメントを元に、doxygenで生成されたものです。参考までに、元の
ソースです。
Doxyfileの作成
doxygenを使うには、まずDoxyfileというファイルを作り、そこに設定を書きます。ソースのあるディレクトリで、
doxygen -g
とすると、Doxyfileが作成されます。そこでまずこのDoxyfileの設定をするのですが、以下ぐらいを書き変えれば、まあ、満足できると思います。「」で括ってあるところは各自で、適当に入れて下さい。
1.プロジェクト名
PROJECT_NAME = 「プロジェクトの名前」
2.プロジェクトナンバー
PROJECT_NUMBER = 「好きな番号」
3.言語
OUTPUT_LANGUAGE = Japanese
4.C++で//のコメント形式を使う場合
MULTILINE_CPP_IS_BRIEF = YES
あとは適宜好きな設定にして下さい
コメントの挿入
つぎにソースファイルにコメントを挿入します。まずファイルの先頭に
/*!
\file
\brief クラスwalletの実現部
クラスwalletの実現部です。
\author itimura
\date 2006/03/17
*/
のように書いて下さい。/*!と*/で囲われたコメントがdoxygenで認識されます。C++では//!もOKです。\briefにはファイルの要約を、\authorには作者、\dateには作成日時を書きます。また、クラスや変数などの宣言の前に
//!お財布管理用のクラスです。
class Wallet {
//!財布の所有者名
char name[20];
こんな感じでコメントをいれておけば、その説明となります。
実行
最後に
doxygen
とすれば、html,latexの仕様書が作成されます。簡単ですね。doxygenのコマンドは他にも\todoや\bugなど様々にあります。下の公式ページを参照して見て下さい。
doxygenの関連リンク
Doxygenの
公式サイトです。
Fortran 90の仕様書を作りたい
Fortran 90の仕様書はdoxygenで作ることができません。ありがたいことに、地球流体電脳倶楽部というところがRDOCにたいしてパッチを作っていて、これを用いて仕様書を作成することができます。公式ページは
ここです。
インストール
RDOCはruby用のdocument作成ソフトなので、ruby, ruby-develをインストールします。yumが使えるなら、
yum install ruby
yum install ruby-devel
とします。それで、公式ページの解説を元にパッチを当てます。
コメントの書き方
!
!コメント
!
のようにコメントを書きます。そして、
rdoc --ignore-case --charset euc-jp --inline-source
とすると、ディレクトリ下./doc/に仕様書ができています。
インストールのときの?
これは一般的ではないと思いますが、インストールのときなぜかテンプレート(html.rb)がきえていたので、直接、パッケージからコピーしました。
/usr/lib/ruby/1.8/rdoc/generators/template/html/html.rb
仕様書(ドキュメント)を作ろう