上野家のホームページ - 資料室バックアップ : 開発/doxygenのソース

[ 差分 | バックアップ | リロード ]
差分を表示
開発/doxygen へ行く。
*Doxygenって [#oa22b027]
プログラムのソースコードを解析して，ドキュメントを作ってくれる便利なツール~
ダウンロードは，http://www.doxygen.jp/から。

Doxygenには，次のような特徴がある。
-文書化されたソースファイルのセットから，オンライン・ドキュメント・ブラウザ (HTML形式) やオフラインのリファレンス・マニュアル (LATEX形式) を生成することが出来る。RTF (MS-Word)，PostScript，ハイパーリンクPDF，圧縮HTML，Unix manページ形式，WindowsのHTML HELPの出力もサポートされている。ドキュメントは，ソースから直接抽出される。
-文書化されていないソースファイルから，コードの構造を抽出するように設定することができます。 これにより，大規模で分散化されたソースの中を探ることが多少容易になる。様々な要素間の関係が，内包・依存図，継承図，およびコラボレーション図により視覚化することが出来る。
-通常のドキュメントを作成することも出来る。（Doxygenのサイト）

**あると便利なツール [#z8507943]
-Graphviz~
Doxygenは，クラスダイアグラムを生成する機能を持っているのだが，そこでGraphvizを利用する。DoxygenとGraphvizを使えば，クラス相関図を自動的に作ってくれる。~
Doxygenをインストールする前に，これを入れておいたほうが良い。~
http://www.graphviz.org/ の[[Download:http://www.graphviz.org/Download.php]]にある，Stable and development Windows Install packages（Windowsの場合）を選ぶ。（現在の安定版は， 	graphviz-2.28.0.msi）~
ダウンロードしたファイルをクリックしてインストールする。
-HTML Help Workshop~
MS製の，Doxygenが出力するドキュメントから，WindowsのHTML HELP（.chm)に変換するツール。~
ここの[[MSのサイト>http://www.microsoft.com/downloads/en/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en]]からダウンロード出来る。これがあれば自動的にWindows Helpファイルを作成できるようになる。
--Doxygenでchmファイルを作る時，追加する設定
 GENERATE_HTMLHELP      = YES
 CHM_FILE               = ../xxxxx.chm
 HHC_LOCATION           = "\"C:\Program Files\HTML Help Workshop\hhc.exe\""
 GENERATE_CHI           = YES
 CHM_INDEX_ENCODING     = CP932

**Doxygenのインストール [#f87012af]
Doxygenのサイトの右側にある[[Downloadするところ:http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc]]から，Windows用インストーラーをダウンロードする。（doxygen-1.8.2-setup.exe）~
これもクリックしてインストールする。~
PATHを通しておく必要があるので，短めのディレクトリのほうが良い。

**doxygenの設定ファイル「Doxyfile」での設定 [#c7197462]
Doxygenを実行する時に，動作を設定するためのdoxyfileをそのプロジェクト・ディレクトリに用意しておく。サンプルDoxyfile: &ref(Doxyfile); ~
設定ファイルはDoxywizardっていうGUIツールで作成できる。一度作るとほとんど変更することはないんでエディターで編集して使っている。最初はDoxywizardを使ったほうがいいと思う。実行は，スタートメニューまたはコマンドプロンプト上でdoxywizardを実行すれば，そのディレクトリに作成される。
|Wizard|簡易設定。ウィザード形式で Project ～ Diagrams まで設定してゆく。|
|Expert|高度な設定。Wizard より細かな設定をおこなえる。|
|Run|ドキュメント生成などを実行できる|

設定はWizardタブを開いて行う。~
''Project''
|Project name|プロジェクト名の設定。ドキュメントのタイトルなど，いろいろなところで使われる。|
|Project synopsis|プロジェクト概要。出力形式がHTMLの場合，タイトル直下に説明文として添えられる。|
|Project version or id|プロジェクトのバージョン情報，または識別子。出力形式がHTMLの場合，タイトル右側に添えられる。|
|Project logo|プロジェクトのロゴとなる画像ファイル。出力形式がHTMLの場合，タイトル左側に画像として挿入される。|
|Select code directory|解析対象とするソースコードを格納したフォルダの場所。相対パスも指定できる。|
|Scan recursively|ソースコードのフォルダが階層化されており，それらも解析する場合はチェックする。|
|Destination directory|ドキュメントの出力先。未指定なら作業フォルダが選ばれる。|

''Mode''
|Select the desired extraction mode|解析対象。Documented entities onlyはドキュメント化されたファイルのみ。All Entitiesならすべて。Include cross-referencedはソース間で相互参照がある場合，それらも含む。|
|Select programming language to optimize the result for|最適化するプログラミング言語。プロジェクトのメイン言語を選ぶ。|

''Output''
|HTML|plain HTML|標準のHTMLを出力する。|
||with navigation panel|ページの左側にナビゲーションパネルを持つHTMLを出力する。|
||prepare for compressed HTML(.chm)|MS Compiled HTML Help（CHM）形式で出力する。|
||With search function|PHPの稼働しているWeb サーバーに配置したとき，検索機能を有効にする。|
||Change color…|HTML出力する際の全体的な色を変更できる。既定のデザインを踏襲しつつ，色のみを調整するようになっている。|
|LaTeX|as intermediate format for hyperlinked PDF|LaTeX用の中間形式としてハイパーリンク形式のPDFを出力する。|
||as intermediate format for PDF|LaTeX用の中間形式として単一のPDFを出力する。|
||as intermediate format for PostScript|LaTeX用の中間形式としてポストスクリプトファイルを出力する。|
|Man pages||UNIXのman（マニュアル）コマンド用ファイルを出力する。|
|Rich Text Format(RTF)||リッチテキスト形式のファイルを出力する。|
|XML||XML 形式のファイルを出力する。独自の出力形式が欲しい場合，このファイルから変換するのがいいと思う。|

''Diagrams''
|Diagram to generate|No diagrams|ダイアグラムを出力しない。|
||Use built-in class diagram generator|Doxygenに内蔵されてるジェネレータを利用してダイアグラムを出力する。|
||Use dot tool from the GraphViz package to generate|GraphVizを利用してダイアグラムを出力する。詳細設定は Dot graphs to generate 欄でおこなう。|
|Dot graphs to generate|Class diagrams|クラス図を作成する。|
||Collaboration diagrams|コラボレーション図を作成する。|
||Include dependency graphs|インクルード依存グラフを作成する。|
||Include by dependency graphs|インクルード依存グラフを作成する。ヘッダの間接インクルードによって生じた依存関係も含むみたい。|
||Call graphs|呼び出しグラフを作成する。これをチェックすると関数やメソッドの呼び出し解析が実行されるので，ドキュメント生成の時間がとても長くなる。|
||Called by graphs|間接的な呼び出しフラグを作成する。この設定もCall graphs同様，チェックすると時間がかかる。|

''Expert''タブ
|Doxyfile Encodeing|設定ファイルDoxyfileのコードを設定する。''UTF-8''にしておく。|
|OUTPUT_LANGUAGE|日本語で出力させるために，''Japanese''に設定する。|
|OPTIMIZE_OUTPUT_FOR_C|Cソースのみの場合は，YESにしておく。|
|INPUT_ENCODING|入力ファイルの言語ローケールの設定。S-JISの場合は「''CP932''」にする。ソースコードに合わせる。|
|EXTRACT_PRIVATE|''YES''にすると，プライベートメンバーを文書に入れる。|
|EXTRACT_LOCAL_CLASSES|''YES''で，ローカルクラスを文書に入れる。|
|SHOW_INCLUDE_FILES|''YES''で，インクルードファイルのリストを文書に入れる。|

すべての設定が完了したら，Runタブを開き，Run doxygenボタンを押す。しばらく待つとドキュメント作成が完了する。

''CHMファイル作成''
|GENERATE_HTMLHELP|チェックすることで，CHMファイルの出力が有効になる。|
|CHM_FILE|出力するファイル名。プロジェクト名.chm とするのが分かりやすくてよい。|
|HHC_LOCATION|HTML Help Workshopの実行ファイルへのフルパス。直接入れるかファイルダイアログでhhc.exeを開いて設定する。|
|CHM_INDEX_ENCODING|CHMファイルを開いた時，目次タブに表示される項目のテキストエンコーディング。日本語が含まれるなら「''CP932''」を設定する。そうしないと文字化けする。|

 DOXYFILE_ENCODING      = UTF-8                   # SJISの場合は，CP932にする
 PROJECT_NAME           = "XXXXXX PCB Firmware"   # 適当に
 PROJECT_NUMBER         = 1.1.0                   # 適当に
 OUTPUT_LANGUAGE        = Japanese                # やっぱり日本語で
 HAVE_DOT               = YES                     # Graphvizで図を入れる
 OUTPUT_DIRECTORY       =                         # 出力ディレクトリ（デフォルトはHTML）
 TAB_SIZE               = 8                       # TAB幅
 FILE_PATTERNS          = *.cpp *.c *.h           # 対象ファイルを指定
 EXTRACT_PRIVATE        = YES                     # privateメンバも出力するとき

その他，いっぱいオプションがある。''doxygen -g''とするとコメント付きのDoxyfileを作成するんでそれを見て設定する。

*Doxygenでの書き方と主なタグ [#c0b24825]

**2種のコメント [#l6533730]
doxygenコメントには，「概要記述」と「詳細記述」の2つのコメントがあります。それぞれの違いは以下のとおり。
|doxygenコメント|内容|書き方|h
|概要記述（brief description）|	詳細解説およびサマリーに利用されるコメント|主に1行のコメントで記載|
|詳細記述（detailed description）|詳細解説の個所のみで利用されるコメント|複数行のコメントで記載|
どちらもファイルの先頭，対象となる関数，構造体，C++のクラス，メンバ変数，メソッドなどの宣言や定義の前に記述する。

図は，doxygenが出力するファイルのコメントの例です。doxygenが出力するドキュメントは，「サマリー」と「詳細説明」に分かれる。サマリーには，概要記述で記載した内容が，詳細説明には概要記述と詳細記述で記載した内容が反映されるみたい。サマリーにも反映させたい内容については，概要記述に書くようにする。
#ref(サマリーと詳細.jpg)

**書き方 [#ma5192b9]
-サマリーの書き方~
 /// サマリーだよ
とか，
 //! サマリーだよ
''注意：サマリーを複数行に書いてしまうと，詳細説明になってしまう。''
-詳細説明の書き方
QTスタイル
 /*
  * 詳細記述
  * 詳細記述
 */
 
  /*
   詳細記述
   詳細記述
  */
JavaDocスタイル~
 /**
  * 詳細記述
  * 詳細記述
  */
 
 /** 詳細記述 */
-詳細説明の中でサマリーを記述しちゃう方法~
詳細説明中にサマリーを書きたい場合は，「''@brief''」というセクションコマンドを利用して記述する。~
''@brief''を利用すると，空のコメント行までがサマリーとして扱われる。~
 /*!
  * 詳細説明
  * @brief     サマリー説明
  *             概要説明
  *
  * 詳細説明
 */
 
 /*!
 @brief	文字列の文字数を返す
 
 @param [in] s 文字列
 @return 文字数
 */
 
 /*!
 @brief	文字列での文字の位置を返す
  
 @param [in] s 文字列
 @retval 0  見つからなかった
 @retval 0以外 文字の位置
 */
-補足説明を付けたい変数や関数の定義前に通常コメントを書く~
補足説明を付けたい変数や関数の定義前に通常コメントを書きますが，enum型や変数などの場合は定義の後にコメントを付けるケースもある。
doxygenのコメントは，このような後方コメントにも対応しており，以下のように記述することで前の宣言を修飾出来る。
 変数定義  /*!< 詳細説明 */
とか
 変数定義  /*!< 詳細説明 */
や，
 変数定義  ///< サマリーだよ
 int globBase = 10;  ///< 足し算用のパラメータ 
とか
 変数定義  //!< サマリーだよ
とかにします。

**文章の飾り付けとセクションコマンド [#xf412808]
コメントの中では"スペシャルコマンド"や"HTMLコマンド"と呼ぶ書き方で細かな指定が可能。第す。代表的なものを以下に上げてみる。
|書き方|説明|h
|@bほげほげ|''ほげほげ''|
|＜b＞ほげほげ＜/b＞|''ほげほげ''|
|@emほげほげ|'''ほげほげ'''|
|<em>ほげほげ</em>|'''ほげほげ'''|
|@code～@endcode|コードブロック|
|@verbatim～@endverbatim|直接表記|
-@および\で始まる語は，doxygenコマンドとして解釈しようとする。コマンドにしない場合は，'\n'や'\0'の様にquoteする。~
<>&#%もHTMLで特殊な意味を持ちますので，エスケープする必要がある。コマンドや特殊文字を含む文を書く場合には，特殊文字を解釈しないブロックを作るコマンドがある。
-空白行は，ブロック終了コマンドの無いブロックを終了させるという意味がある。
-コメントされている識別子を文中に書くと，自動でリンクが張られる。
-コマンドには引数がある場合がある。コマンドの後ろに何か記述している場合と，コマンドだけの行は出力結果が違うことがある。
-HTMLタグを使用すると出力に反映されるけど，プログラムのソースとしては見づらくなるから，なるべく使わないようにする。
-単に改行しても出力されないので，ソース上の整形で単に改行するのは問題ない。

|セクションコマンド|説明|h
|@mainpage|doxygenで作成されるドキュメントの最初のページの説明文になる。|
|@author|開発者名を記載する。|
|@deprecated|廃止されたクラスやメソッドであることを，記載する。|
|@param|関数の引数名と引数の概要（引数の数だけ記述）なんかを記載する。|
|@return|戻り値を記載する（戻り値がvoidの時は不要）|
|@retval|戻り値を記載する（戻り値がいくつかの値をとる場合）|
|@arg / @li|箇条書き。- (インデントした行頭ハイフン) の場合，全て番号無しリストとして出力される。引数のリストとして@arg，文中の箇条書きとして - がいいかも。-だけはインデントの深さを変えるとネストになる。インデントを合わせて.だけの行を置くと，リストを終了しパラグラフを続けることが出来ます。 -# とすると順序付きリストになります。|
|@par|段落の開始。引数は，パラグラフタイトルになる。タイトルが無しの時はコマンドのみの改行にする。|
|@see / @sa|参照すべき箇所や関連するクラスなんかを記載する。文中にも使える。|
|@code / @endcode|コードブロックの指定。この間のテキストはコマンドが全て無効になって，そのまま出力される。コードサンプルなんかを書く時に使う。@verbatin～@endverbatimもほぼ同じだけど，これだとリンクが張られます。|
|@since|導入された日付なんかを記載する|
|@throw|関数なんかの例外を記載する|
|@version|バージョンを記載する|
|@note|覚書のような，メモなんかを記載する|
|@attention|注意書き。現在の使用時なんかでの注意点を記載する|
|@warnning|警告書き。開発者なんかに，動作仕様からは判らない重要な注意事項なんかを記載する|
|@date|日付をつけて履歴なんかを記載するときに使う。複数書いても連結されてしまう。|
|@bug|バグ情報。リストとして一覧が出るので，@dateの代りに履歴として使うという使い方もある。複数書いた場合にパラグラフ結合されないという違いがある。|

-PHPだとこんな感じ~
 /**
  * @brief  etcクラスはその他のデータを表します。
  *
  * @author yuji
  * @see    labeledETC
  * @date   2007/04/09
  */
 class etc{
 
   /**
    * その他のデータを表す
    * @note       private String name
    * @deprecated この値を直接操作することは推奨されません。
    */
   var $name;
 
   /**
    * 名前を設定
    * @param      name 名前を指定
    * @note       void setName(String name)
    */
   function setName($name){
     $this->name = $name;
   }
 
   /**
    * 名前の取得
    * @return     String
    * @note       String getName()
    */
   function getName(){
     return $this->name;
   }
 }
« Prev
開発/doxygen のバックアップ一覧
開発/doxygen のバックアップソース(No. All)
- 1: 2010-08-05 (木) 00:39:13 yuji
- 現: 2020-12-26 (土) 16:07:41 yuji
  - Attached file: doxyfile, Deleted an attach file: doxyfile at 2012-11-21 (水) 13:40:32, Attached file: Doxyfile, Deleted an attach file: Doxyfile at 2012-11-21 (水) 13:40:53, Attached file: サマリーと詳細.jpg
Counter: 2601, today: 1, yesterday: 1
ログイン
パスワード紛失
メインメニュー
開発​/doxygen のソース

開発/doxygen のソース
