Doxygen @ Blog - Linux Life

コメントを多言語で書く

2005/07/27 ( n ) < Doxygen KreetingKard KDevelop >

src/kkglobal.h を追加し、以下の内容を記述

#if defined DOXY_LANG_JA
/**
* DOXY_LANG_XX マクロは APIドキュメントのコメントの言語を切替えるスイッチです。
* DOXY_LANG_JA を定義すると、コメントが日本語になります。(Doxygen自体の言語とは関係ありません。)
* なにも定義しない場合は英語になります。
*/
#elif defined DOXY_LANG_XX
/**
* Other language
*/
#else
/**
* DOXY_LANG_XX macro is switch of language that comments API document.
* For example, DOXY_LANG_JA difinition outputs japanese comments.
* No DOXY_LANG_XX is defined, english comments is output.
*/
#endif
#define DOXY_LANG_XX

この部分は KDevelop での表示がカラフルになって、思っていたよりずっと素晴らしい感じ。

#define DOXY_LANG_JA

をこのファイルの先頭に記述するとAPIドキュメントのコメントが日本語で出力され、この定義をコメントアウトすると英語に切り替わることを確認した。

#include <kdebug.h>
#include <klocale.h>

もほとんどのファイルに記述してあるのでこのファイルに移動しよう。
//TODO 全てのヘッダファイルに kkglobal.h をインクルードする。

コメントを書く場所

2005/07/27 ( n ) < Doxygen KreetingKard >

宣言部(.h)か実装部(.cpp)のどちらにも書けるらしい。
「APIドキュメント」と言う位なので宣言部に書いた方がいい気がするが、ヘッダーファイルに記述すると、全体の８割くらいがこのコメントになってしまうので、基本的にはソースファイルの方に書くようにします。
というより、ヘッダファイルに書いておいて、実装するときにそこに移動するような感じかな？

コメントを多言語で書く方法があった

2005/07/27 ( n ) < Doxygen KreetingKard >

Doxygen 専用コマンドの \if <セクションラベル>の例２のところにあるサンプルがまさにそれでした。
#if defined DOXY_LANG_JA ... #else ... #end 作戦はナシって事でorz

APIドキュメント

2005/07/26 ( n ) < Doxygen KreetingKard >

色々調べて書いてみる。
Qt は /*! */ のスタイルだが、KDE では /** */ が多いようだ。

Doxygen は出力言語が選べるらしく、Japaneseにすると日本語でマニュアルが作成された。
ファイルのエンコードがUnicodeなので、入力フィルタ(INPUT_FILTER)に「nkf -e」が必要
Japanese-euc、Japanese-utf8、Japanese-sjisとかになってたら便利なのに。

QPROPERTY に対するコメントを以下のように記述すると Qt のドキュメントだと get/set に対してコメントが付加されているようだがそうはならなかった。

/**
* \property プロパティ名
* 説明
*/

ドキュメントを日本語と英語で書けたら(日本語だけ書いておけば後で訳してくれる人がいれば) 楽だなぁと思って色々調べたが、正式な方法では無理っぽい。
m17nのドキュメントは日本語版と英語版があり、ずるいことをして生成してるらしい。
英語と日本語のドキュメントを #if - #else - #end で分けてみるとうまく表示されたのでよいことにしよう。
日本語(゜д゜)ウザァって外国人(？)が現れたら泣く泣く削除するって事で。

ソースにコメントを書く

2005/07/21 ( n ) < KDevelop KreetingKard Doxygen >

KMyMoneyというのが気になって色々見ていたら、
KMyMoney Main Page for API documentation.なんてものが存在する。
ちゃんとコメントを書いていてとても偉いと思ったので、KreetingKardにも採り入れることにした。

/**
* 説明
* …
* @short 短い説明
* @param パラメータ名説明
*/

みたいな感じに書いておけば、KDevelopの「ビルド(I)」>「API ドキュメントをビルド」で自動的に作れるらしい。
詳しい設定は「プロジェクト(P)」>「Project Options...」>「Doxygen」でする。
「Doxyfile」というファイルが設定ファイルで、cvs には登録しない雰囲気。
とりあえず、debug フォルダは除いておいた。

詳しい書き方とかはソースとドキュメントを見比べて勉強しよう。

他にも KMyMoney は Project Handbook もちゃんと作ってるし、
その中には Appendix C. Unit Test Examples なんて項目もあって、勉強になる。