Doxygen 使用説明書

Doxygenの紹介

Doxygenは、オープンソースのクロスプラットフォーム , ドキュメントシステムのJavaDocの説明と同様のスタイルで , 完全にC、C、Java、Objective-CとIDL言語 , PHP、C＃のサポートの一部をサポートします。注釈の構文は、Qt-Doc、KDocとJavaDocと互換性があります。Doxgenは、アーカイブされたソースファイルから、HTML形式のオンラインクラスブラウザや、LATEX、RTF形式のオフラインリファレンスマニュアルを生成することができます。

Doxygenは、プログラム中の特定の注釈を記述ファイルに変換する、プログラムのファイル生成ツールです。通常、私たちは大なり小なり注釈を付けてプログラムを書きますが、それ以外の人にとっては、プログラム中の注釈を直接探るのはタイタニック号のサルベージ並みの作業となります。有用な注釈のほとんどは、関数やカテゴリなどに対するものです。そこで、プログラム自体の構造に基づいてコメントを純粋なリファレンスマニュアルに再編成できれば、後であなたのコードを使う人の負担はかなり軽減されるでしょう。しかし、その反面、ドキュメントを整理する作業は、あなたにとって重い負担となります。

　　アーカイブされていないソースファイルの場合、Doxygenの設定によりコード構造を抽出することも可能です。また、自動生成される依存関係グラフ、継承図、コラボレーション図により、ドキュメント間の関係を可視化することができます。PostScript、PDF、HTML、Unixmanページ。

　　優れたプログラム設計者は、適材適所の注釈を付けてプログラムを書きます。注釈を少しでも収まるように書けば、あとはツールを使ってプログラムの構造と注釈を元に美しいドキュメントを作ることができます。これで、多くの働き者のプログラマーが、コーヒーを何杯かおかわりする時間を作ることができるだろう。

　　Doxygenはそのようなツールの一つです。注釈を書く際には、Doxygenが定めたいくつかのルールに従いましょう。そうすれば、美しいファイルを作ることができるようになります。つまり、Doxygenの使い方は大きく2つに分けられる。1つは特定のフォーマットで注釈を書くこと、もう1つはDoxygenのツールを使ってファイルを生成することです。





コードのコメントからhtmlやchmやpdfのドキュメントを生成することです。

わぁ、私のコードのドキュメントを生成してくれるなんて、何を待っているんだ・・・。待てよ．まだそんなに賢くないよ．

ドキュメントを生成するためには、その仕様に沿ったコメントを書かなければなりません。なんだこのクソめんどくさいのは。

まずは、その一般的なアノテーションの仕様についてお伝えします。これ以上深入りするのはどうかと思うので-_-!

一般的な書式は、@の後にキーワードがあることです。このキーワードには、何をアノテーションするのかが書かれています。パラメータです。戻り値です。....

ヘッダーファイルのテンプレート :

/** @brief ここに要約を書きます。

 * @file ファイル名

 * @author これは誰がやったんだ？

 * バージョンアップ

 * @date いつ入手しましたか？

 * @note アノテーション。例えば このドキュメントは具体的にどのような機能を持ち、使用する際にどのような点に注意すればよいか .........。

 * @since 例えば。このファイルは、2012年に地球が爆発して以来、消えてしまいました。

 */

名言の数々

 欠点は、履歴が修正されないことです。とりあえず@sinceに置き換えてみるしかないですね。

 最初と最後を除いて、@の前の*は必要ありません、美観のためだけです。

関数に対するコメントです。

/* この関数は何のためにあるのか、ここに書いてください

 param[in] 入力パラメータ1

 入力パラメータ2

 @param[out] 出力パラメータ1

 @return 返り値の説明

 警告 警告: 例: パラメータは空にできない、メモリは外部で解放する必要がある、その他無意味なもの。

 備考 アノテート 何でもいい。

 見る                これに相当するのは、xxoo関数などを参照することです

*/

料金の言葉

これらは、どれを書くかは決まっていません。

戻り値については、こんなこともできます

retval 1 成功

retval 0 失敗

時には、こんな風にサンプルコードをコメントに書くこともあります。

コメントにこのようなコードを追加します。

@par 例です。

@code 


extern IThread *pThread; 


HANDLE hEvent = pThread->GetEventHandle(); 


while(WaitForSingleObject(hEvent,0) ! = WAIT_OBJECT_0) 


{ 


//Do something 


} 


@endcode

他にもいくつか使いそうなものがありますね。

トド       //この記述アルゴリズムの方が良いと思う

@exception // 関数がどのような例外を投げるかを記述するために使用します。

@deprecated // この関数は、後のバージョンのいわゆる非推奨リストで非推奨となる可能性があります。

を例とします。

/** Constructors  


 @param[in] pConfig Pointer to the TASKCONFIG structure 


 @param[in] strWndName 
The name of the target window, if this parameter is empty then it does not interact with any window 


 @param[in] hRes the resource handle to use, or not use the resource if the parameter is empty 


 @warning pConfig cannot be empty  


 @note 
    Request pConfig memory 


 @see 
    IThread 


*/ 


CThread_Plug(TASKCONFIG *pConfig,LPCTSTR strWndName,HINSTANCE hRes);

変数や物には、1行のコメントで、それ以上にはならない。

 /**< ここに追加したいものを書いてください */

または

///< ここに追加したい内容を書いてください。

例えば

HINSTANCE m_hRes; ///< 使用するリソースハンドル

CString _strWndName; ////< メッセージを受信するターゲットのウィンドウ名

5.2.2 一般的なコマンドの紹介

ファイル「@file」の注釈付き説明。

作者（@author）に関する情報。

クラスや関数の簡単な説明のための@brief。この関数は、エラーメッセージの文字列を表示します。

paramは主に関数の説明で使われ、その後にパラメータ名、そしてパラメータの説明を記述します。

returnは、関数の戻り値を記述します。return この関数は実行結果を返し、成功した場合は TRUE、失敗した場合は FLASE を返します。

retval 返り値の型を記述します。retval NULL 空文字列。retval !NULL 空でない文字列。

注釈

注意事項

警告 警告メッセージ

enumは列挙型を参照し、Doxygenはその列挙型にリンクを生成します。enum CTest::MyEnum

varは変数を参照し、Doxygenはenumにリンクを生成します。var CTest::m_FileKey

class クラスへの参照、フォーマット。class <name> [<header-file>] [<header-name>] eg:@class CTest "inc/class.h"

exceptionで発生しうる例外の説明 例．この関数の実行により、範囲外の例外が発生する可能性があります。

@todo 何を行うかのコメント

@see 他のセクションへの参照を含むコメントで、間に他のコード項目の名前を入れ、それらへの参照へのリンクを自動生成します。

relates <name> 一般に、非メンバー関数のコメント文書をクラス説明文書に含めるために使用します。

since 通常は、この部分がどのバージョンから、いつ書かれたかを示すために使用します。

code コメントでコードのセクションを開始し、@endcodeコマンドまで継続します。

endcode コメント内のコードセグメントの終了を表します。

pre コード項目の前提条件を記述するために使用する。

post コード項目の後に使用する条件を記述するために使用します。

この関数は将来のリリースで非推奨となる可能性があります。

defaultgroup モジュール名

class クラスを宣言する 

fn 関数を宣言する

DoxyGen ソフトウェアを使用する上で注意すべき点をいくつか挙げます。

使用する中国語の場合。

まず、生成するプロジェクトディレクトリを設定します。

ウィザード->プロジェクト->ソースコードディレクトリ->選択

Expert->Project->OUTPUT_LANGUAG で english を選択します。

Expert->Input->INPUT_ENCODING に GB2312 を入力する。

Private変数のアノテーションを表示したい場合

Expert->Build->EXTRACT_PRIVATE のチェックボックスにチェックを入れます。

出力

Wizard->Output .chmを選択した場合、検索機能はありません。

その他のオプションはデフォルト