Doxygenの使い方 | php,javaのソースからドキュメントを作成するツール

目次

  1. 紹介とダウンロード
  2. DoxygenをCakePHPで使う場合の設定
  3. Doxygenに合わせたコメントの書き方
  4. Doxygenのコマンド
  5. 役立ちリンク

紹介とダウンロード

DoxgenはC/C++ソースコードのコメントからドキュメントを生成するツールである。 現在は拡張されJava,PHP,C#などに対応している。

ソースコードのコメント形式はいくつかあるが、Eclipseを使っている場合、javadoc形式を採用したほうがよい。

ダウンロードと導入

Windeowsであるならdoxygen-1.8.10-setup.exe (18.3MB)※を ダウンロード(Doxygen) する。
あとは通常のWindowsプログラムと同様にインストールするだけ。

DoxygenをCakePHPで使う場合の設定

① Wizard/Project ワークフォルダや、ソースコードフォルダ、出力先フォルダなどを設定する

  1. 「Step 1:Specify ...」の入力項目にワークフォルダのパスを入力します。作業用なので適当なフォルダで構いません。
  2. 左枠からWizardタグ→Topics→Projectと選択します。
  3. 右枠にいくつか設定します。
  4. 「Project name」にプロジェクト名を入力します。
  5. 「Project synopsis」や「Project version or id」は適当に入力します。
  6. 「Source code directory」にソースコードのフォルダを指定します。CakePHPなら「app」フォルダが適切です。
  7. 「Scan recursively」にチェックを入れます。
  8. 「Destination directory」にドキュメントの出力先フォルダを指定します。
  9. 入力が終わったら「Next」ボタンを押して、次の設定画面を開きます。

② Wizard/Mode ソースコードのプログラム言語などを設定します。

  1. 「All Entities」を選択します。
  2. 「Include cross-refernced source ...」にチェックを入れます。（ソースコードをドキュメントに表示）
  3. 「Optimize for Cor PHP output」を選択します。
  4. 入力が終わったら「Next」ボタンを押して、次の設定画面を開きます。

③ Wizard/Output　ドキュメントの形式を設定します。

  1. 「HTML」にチェックを入れます。（HTML形式のドキュメントを出力）
  2. 「plain HTML」を選択します。
  3. 「With search function」にチェックを入れます。
  4. PDFドキュメントは不要である場合、LaTeXのチェックをはずします。
  5. 入力が終わったら「Next」ボタンを押して、次の設定画面を開きます。

④ Wizard/Diagrams ダイアグラム（図解）の設定

  1. デフォルトの設定で問題ありません。デフォルトの「Use built-in class...」はクラス図の表示と思われます。
  2. 次は「Expert/input」でctpファイルやドキュメント対象外のフォルダを指定します。

⑤ Expert/input　ctpファイルやドキュメント対象外のフォルダを指定

  1. 左枠にてExpertタブ→inputを選択します。
  2. 「FILE_PATTERNS」のテキストボックスに「*.ctp」を追加して「＋」ボタンを押し、ctpファイルに対応させます。
  3. CakePHPのappフォルダ内には、Configなどドキュメント出力してはまずいフォルダがいくつか存在します。
    「EXCLUDE」に出力したくないフォルダやファイルを入力し、「＋」ボタンを押し、対象外リストに追加していきます。

⑤ ドキュメントの出力実行

  1. 左枠にて「run」を選択します。
  2. 「Run doxgen」を押すとドキュメント作成が始まります。ドキュメントは①で指定した出力先フォルダに作成されます。
  3. 終了するとき、設定を保存すると次回から再設定する必要はなくなるので便利です。（File→Save)



目次に戻る

Doxygenに合わせたコメントの書き方

基本的にjavadoc形式で記述します。（javadoc形式以外もある)
行を開けずにコメントを書くと、改行されませんが、1行空けると改行されます。
「-」をつけるとリストになります。
「-#」をつけると連番リストになります。
一行空けてから、タブのあとにコメントを書くと囲みになります。

書き方の例

	/**
	 * ネコが吠える
	 * 
	 * いろはにほへとちりぬるを
	 * わかよたれそつねならむ
	 * 
	 * 一行空けると改行されます。
	 * 
	 * ◇「-」をつけるとリストになります。
	 * - シャム
	 * - ボンベイ
	 * - 三毛
	 * - 階層1：タブを入れると階層化されます。
	 * 	- 階層2
	 * 		- 階層3
	 * 
	 * ◇「-#」をつけると連番リストになります。
	 * -# 山羊
	 * -# カニ
	 * -# 鮫
	 * 
	 * ◇囲み
	 * 
	 * 	一行空けてから、タブのあとにコメントを書くと囲みになります。
	 * 	hello world!
	 *  
	 * @param id $cat_id ネコID
	 * @param string $cat_name ネコ名
	 * 
	 * @author k-uehara
	 * @return 戻り値
	 */
	public function barkingCat($cat_id,$cat_name){
		//...略...
	}


注意

コマンド（@paramなど）を記述する際、隙間に全角スペースを入れないようにします。
全角スペースが入った場合、Eclipseのoutlineに索引が表示されなくなり、開発が不便になります。

＜例＞

× @param　nako_name←分かりにくいが@paramとnako_nameの間に全角スペースが入っている
○ @param nako_name

目次に戻る 参考サイト

Doxygenのコマンド

コマンドは@マークから始まるコードです。 説明文を項目ごとに分類するのに使います。

書き方の例

	/**
	 * 
	 * @version 0.9
	 * @date 2015-12-4
	 * @attention 注意事項を書きます。
	 * @note 覚書を書きます。
	 * @remarks 注釈を書きます。
	 * @see 参照先を書きます。  例→http://amaraimusi.sakura.ne.jp/
	 * @warning 警告を書きます。
	 * @throw 例外を記述します。
	 * @param int $id 引数を書きます。
	 * @return 返値の説明を書きます。
	 * 
	 */
	public function barkingKani($id){
		//...略...
	}


コマンドのピックアップ

コマンド説明例
@versionバージョン0.9
@date日付2015-12-4
@attention注意事項使用の注意・・
@note覚え書き
@remarks注釈
@see参照先http://amaraimusi.sakura.ne.jp/
@warning警告○○を引数に指定しないでください。
@throw例外○○Exception
@param引数int $id テストID
@return返値取得値
@attention注意
@bugバグ
@includeインクルード
@fileファイル名
目次に戻る