JavaにはJavadoc、C#にはXML Documentation、PerlにはPOD、PHPにはPHP Documentationなど、
ソースコードに書いた特別のコメントを抜き取って文書を作るツールがあるわけです。
ところがC++にはそういうのないよなと思って調べていたのですが、
Javadoc同様に書いたら使えるツールがあるということがわかった。
Doxygenというツールです。
まずヘッダーファイルにこんな要領でコメントを書いておきます。
/**
RFC4180に沿ったCSVのストリームを解析し読み進めるパーサーです。
@author Hidemaro
*/
class CSVReader{
private:
//略
public:
/**
ストリームを受け取り初期化するコンストラクタです。
@param from ストリーム
*/
CSVReader(std::istream&);
/**
行末にたどり着いたかを返します。
@return 行末にたどり着いたらtrue
*/
//後略
Javadocは/**から始まり*/で終わるコメントで書くことになっています。それ同様に書きます。
特殊なことは@から始まる行で書くんですね。
@paramは引数について説明を書く、@returnは返り値について説明を書く。
他にもいろいろありますが、特に有益なものを挙げてみた。
こういう風に用意した上でDoxygenを使うわけですね。
Doxygenをインストールして、Doxywizardを起動します。
まず、Step1のディレクトリにソースコード・ヘッダーファイルの並んでいるディレクトリを指定します。
それでStep2のWizardで、Source code directoryになんか書いてあるけど消します。
これでStep1で指定したディレクトリから入力するようになります。
それでProject nameなどを入力。
Nextで進んで、Optimize for C++ outputを選んでおく、
Nextで進んで出力ファイルの種類を選ぶ。ここではHTMLだけ作成することを考えます。
これで基本はOKですが、詳しい設定をExpartのタブで行います。
Projectの項のOUTPUT_LANGUAGEをJapaneseに、
Inputの項のINPUT_ENCODINGをファイルのエンコーディングに合わせる。
Visual StudioではShift_JISを使うのが普通らしく、Shift_JISで作っているので僕はこれをShift_JISに変更した。
設定が終わったら、Runのタブに変えて、Run doxygenをクリック!
これでhtml以下にドキュメントができていると。index.htmlを開くと読める。
結構読みやすいですね。これを読みつつやれば便利でしょうね。
あと、コメントの中に使用例を示すのもいいかもしれませんね。
@codeから初めて@codeendまでの間にかけばいいですね。クラスの説明にでも書いておきましょう。
こういう道具は非常に重要です。
一見なんでもないようなものですが、引数は0から数えた数字だったけ、1から数えた数字だったけ?とか、
そういうときに確認するものがやっぱり欲しいんですよね。だから作ってあげましょう。
もちろんHTMLで出力できるのも便利なのですが、ヘッダファイルに書いてあるというのも便利な話です。
クラス・メソッドを作ったらすぐに書くぐらいの気持ちでいましょう。
まぁDoxygenはそのきっかけとなっただけなのかもしれません。そりゃHTMLで見れたら便利だけどね。