まず、解析対象とするためにコメントにちょっとしたお約束があります。
普通のコメントでは // ～ や /* ～ */ でコメントとなりますが、doxygen用のコメントにする場合、/// @～ ～、 /** @～ ～ */ と、/ や * が１つ増え、@コマンド というのが必要になります。
とりあえずよく使うdoxygenコマンドを列挙。
- @file
- @brief
- @par
- @author
- @date
- @code
- @endcode
- @note
- @pre
- @post
- @param
- @return
- @retval
- @protected
- @private
- @todo
- @bug
- @defgroup
最初の５つはファイルヘッダに使用します。
//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/ /// @file hogehoge.mel /// @brief hogehogeの説明 /// @par 更新履歴: /// - 20??/??/??:version.1.00 /// - Release. /// @author Teruyuki Ishiko /// @date since 20??/??/?? //_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/みたいに書くと、
みたいに解析してくれます。
@note と @code、@endcode を使って
//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/ /// @file hogehoge.mel /// @brief hogehogeの説明 /// @note /// userSetup.melに /// @code /// source "hogehoge.mel"; /// @endcode /// を記述する。 /// @par 更新履歴: /// - 20??/??/??:version.1.00 /// - Release. /// @author Teruyuki Ishiko /// @date since 20??/??/?? //_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
使い方をメモれます。
続いて関数ヘッダ。グローバルプロシージャもローカルプロシージャも基本的には、説明と引数と戻り値なんかを記述しておくと便利ですが、ローカルプロシージャには、特に付けておきたいコマンドがあります。
@protected と @private です。
上のコードに下の部分を追加します。
proc _hoge1()
/**************************************************************************//**
@private
@brief テスト
******************************************************************************/
{
/** @todo
* やる事
*
*/
/** @bug
* 既知のバグ
*
*/
}
proc _hoge2()
/**************************************************************************//**
@protected
@brief テスト
******************************************************************************/
{
/** @todo
* やり残したこと
*
*/
/** @bug
* 発見したバグ
*
*/
}
すると、
こんな風に、@protected を付けた方しか表示されなくなります。
@todo や @bug は特別なコマンドで、フレームの方にも一覧で確認できるようになっています。
_hoge1()にも記述しているんですが、@private に設定したことで、まるっきり隠れてしまいました。なので、@todo と @bug を使った場合は、@protected を設定するほうが良いですね。
裏ワザとして、[Expert]タブのBuildに EXTRACT_PRIVATE にチェックを入れれば、
@privateの部分も強制的に表示してくれます。
もちろん、todo や bug にも表示されます。
ただ、EXTRACT_PRIVATE のチェックを外した状態でも、@private の関数は、フレームで見えてしまいます。
@pre,@post,@note には、@todo と @bug みたいに左にマークが付きます。ついでに、戻り値を表す @return と @retval の違いも少し。
hogehoge.melの最後の方に、こんな感じのを記入
global proc int hogehoge()
/**************************************************************************//**
@brief main procedure
@return なんかの値を返す
@retval 0 無効
@retval 1 有効
******************************************************************************/
{
/// @pre ●１つ
/// @pre ●２つ
/// @note ●１つ
/// @note ●２つ
/// @post ●１つ
/// @post ●２つ
return 0;
}
@return のほうは戻り値を文章で表現するのに向いていて、@retval は、よく見ると、色が付いている文字と、それを説明する文言みたいになっています。
@pre,@postは緑色、@noteは黄色のラインが付くので、グローバルプロシージャに設定しておくと見た目で判別しやすくなり良く使います。
同じようなコマンドで @remarks というのもありますが、色とか何もつかないので、あまり使わないですね。
最後にグローバル変数と source コマンドの表現です。
source するために、sample.mel と test.mel に @file と メインプロシージャだけ記述して、hogehoge.melの関数ヘッダの下に下のコードを書いてみます。
global string $gHogeString; ///< hogehoge の文字
global int $gIsHogehoge; ///< hogehoge であるか
/// @defgroup test in hogehoge.mel
/// @{
source "sample.mel"; /// @file sample.mel
source "test.mel"; /// @file test.mel
/// @}
これの表記がこんな感じ。
グローバル変数の説明が出ています。
この ///< を使うことで引数の説明できたりするのは、関数ヘッダも同様で、@param と同じ感じで使えます。
@defgroup と @{,@} はセットで使用します。
これを設定するとフレームに「モジュール」というのが追加され、@{と@}の間に書かれたもののリンクが作成されます。
@defgroup には「名前」と「グループタイトル」が必要で、上の例では、test が「名前」で in hogehoge.mel が「グループタイトル」になります。
ただ、最初の source するファイルが変数になってしまうのは謎です・・・。
@file を使ってリンクが張られていて、リンク先に飛ぶと、ファイル名のしたに、グループタイトルが表示されます。
いつも書くようなコマンドは大体これくらいですかね。
0 件のコメント:
コメントを投稿