※上記の広告は60日以上更新のないWIKIに表示されています。更新することで広告が下部へ移動します。

使い方

ここではDoxygenwizardを利用した簡易ウィザードによるHTMLドキュメント生成方法を記載します。
簡易ウィザードを利用せず、詳細設定を自身で行う場合はこちらを参照してください。

ソースにドキュメントを記載する

ソースにドキュメントを記載します。
正しい「書き方」は、「コーディングしながらドキュメントを記載する」もしくは「ドキュメントをつけてからコーディングをする」なのかもしれません。

DoxygenにおけるJavaDocスタイルの主なタグ一覧は以下の通りです
(「@」は「\」に置き換えることも可能です)
@author 開発者名を記載します
@deprecated 廃止されたクラスやメソッドであることを記載します
@param メソッドの引数名と引数の概要(引数の数だけ記述)を記載します
@return メソッドの戻り値を記載します(戻り値がvoidの時は不要)
@see 関連する他のメソッドまたはクラスを記載します
@since クラスまたはメソッドの導入された日付を記載します
@throw メソッドが投げる例外を記載します(throwsでないことに注意)
@version クラスまたはメソッドのバージョンを記載します

その他のタグについては下記を参照してください
http://www.stack.nl/~dimitri/doxygen/commands.html

PHP4を使った例は下記のとおりです。
/**
 * @brief  WorkBookクラスは問題集に関するデータを表します。
 * @author uhaku
 * @see    labeledWorkBook
 * @date   2006/05/09
 */
class WorkBook{

  /**
   * 問題集名を指定します。
   * @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;
  }
}


Doxywizardを起動する

スタートメニューから「Doxywizard」を起動します。


ワーキングディレクトリを指定する

  • Step 1: Specify the working directory from which doxygen will run
    doxygen.exeのあるフォルダを指定します
    通常は「C:\Program Files\doxygen\bin」です。

私は作業用のテンポラリフォルダを指定する項目かと思いました
しかしこのフォルダにdoxygen.exeを探しに行っているのでこれは誤りだと思います。
通常は
  1. doxygen.exeへのパスが(インストール時に)追加されている
  2. doxywizard.exeとdoxygen.exeが同一のフォルダに存在する
ことから(doxygen.exeが見つからないという)エラーに気づかなかったものと思われます。

2009/05/01追記:
Doxygen設定ファイルをまだ保存していない状態でファイルメニューからDoxygen設定ファイルを保存するとworking directoryがDoxygen設定ファイルの場所に置き換えられます。
ソースコードの場所の指定は絶対パスであれば問題ありませんが、相対パスで指定した場合Doxygen設定ファイルのある場所を基底とするようです。
となると
  • Doxygen設定ファイルの場所≠doxygen.exeの場所
の場合、ソースコードの場所が正しく読み込めないようです。
doxygenとしては
  • Doxygen設定ファイルの場所=doxygen.exeの場所
が推奨なんでしょうか?


Doxygenの設定を行う

「Wizard」タブが選択されていることを確認して以下に進んでください。
なお詳細設定を行う場合は「Expert」タブを選択し設定します。
「Expert」の設定方法についてこちらにて説明しております。

「Project」設定画面

プロジェクトの情報を指定します。
  • Project name
    プロジェクト名を指定します
    ドキュメントのタイトルページにも利用されます
  • Project version or id
    プロジェクトのリビジョン番号を指定します
    ドキュメントのタイトルページにも利用されます

ソースコードをスキャンするディレクトリ情報を入力します。
  • Source code directory
    ソースファイルもしくはソースファイルが格納されているディレクトリの場所を指定します
    • Scan recursively
      「Source code directory」のサブディレクトにもソースファイルがある場合にチェックします

ドキュメントの生成先情報を入力します。
  • Destination directory
    ドキュメントファイルを出力するディレクトリを指定します

上記を入力し「Next」を押すことで次の「Mode」設定画面へ移動します。

「Mode」設定画面

出力モードを指定します。
  • Documented entities only
    コメントがついているソースコードのみドキュメントを作成します
  • All Entities
    (コメントがついていないソースコードでも)ソースファイル内の要素は全てドキュメントを作成します
    • Include cross-refernced source code in the output
      ソースコードをドキュメント内に参照可能な形で含む場合に指定します
      関数の説明を読んでいるときに、その関数が実際に定義されているソースにジャンプして見たり、その逆ができるようになります。

出力の最適化のためにソースコードの言語を指定します。
  • Optimize for C++ output
    C++のソースである場合に指定します
  • Optimize for C++/CLI output
    C++/CLIのソースである場合に指定します
  • Optimize for Java or C# output
    JavaもしくはC#のソースである場合に指定します
  • Optimize for C or PHP output
    CもしくはPHPのソースである場合に指定します
  • Optimize for Fortran output
    Fortranのソースである場合に指定します
  • Optimize for VHDL output
    VHDLのソースである場合に指定します

上記を入力し「Next」を押すことで次の「Output」設定画面へ移動します。

「Output」設定画面

ドキュメント形式を指定します。

  • HTML
    HTML形式のドキュメントを作成する場合に指定します。
    • plain HTML
      標準的なHTML形式のドキュメントを作成する場合に指定します
    • with frames and a navigation tree
      標準的なHTML形式のドキュメントに加え、左サイドにナビゲーションを作製する場合に指定します
    • prepare for compressed HTML(.chm)
      Microsoft Compiled HTML Help(.chm)形式のドキュメントを作成する場合に指定します
      Microsoft HTML Help Workshopの事前インストールが必要です
      • with search function (requires PHP enabled web server)
        検索機能をつける場合にチェックします。
        ただしPHPが動くWebサーバ上にドキュメントを置かないと検索機能は動作しませんので注意してください。

  • LaTex
    LaTex形式のドキュメントを生成する場合に指定します。
    • as intermediate format for hyperlinked PDF
      リンク化されたPDFの中間ファイルを生成します
    • as intermediate format for PDF
      PDFの中間ファイルを生成します
    • as intermediate format for PostScript
      PostScriptの中間ファイルを生成します

  • Man pages
    man形式のドキュメントを生成する場合に指定します。

  • Rich Text Format(RTF)
    RTF形式のドキュメントを生成する場合に指定します。

  • XML
    XML形式のドキュメントを生成する場合に指定します。

上記を入力し「Next」を押すことで次の「Output」設定画面へ移動します。

「Diagrams」設定画面

図の形式を指定します。
  • No diagrams
    図表は作成しません
  • Use buit-in class diagram generator
    doxygenの標準機能で図表を作成しドキュメントに含めます
    簡素化された図です
  • Use dot tool from the GraphViz package
    GraphVizの機能で図表を生成しドキュメントに含めます
    ある程度複雑な図を生成することが出来ます
    GraphVizのdot.exeにパスが通っているか、「Expert」設定において「DOT_PATH」でdot.exeのパスを指定する必要があります

作成する図の種類を指定します。
  • Class diagrams
    クラス継承図(各クラス説明において)を作成する場合にチェックします
  • Collaboration diagrams
    コラボレーション図(各クラス説明において)を作成する場合にチェックします
    UMLのコラボレーション図とはイメージが違いました
    継承・包含・関連などの依存を表すものです
  • Overall Class hierarchy
    クラス階層図(クラス一覧において)を作成する場合にチェックします
  • Include dependency graphs
    インクルード図(各ファイル説明において)を作成する場合にチェックします
  • Call graphs
    呼出メソッド図(各メソッド説明において)を作成する場合にチェックします
    本メソッドが利用しているメソッドを表すものです
  • Called by graphs
    被呼出メソッド図(各メソッド説明において)を作成する場合にチェックします
    本メソッドを利用しているメソッドを表すものです

上記を入力すれば設定は一旦完了です。



Doxygenの設定を保存する

上部メニューの「File」から「Save」もしくは「Save as」を選んで設定を保存します。
「Save」は保存、「Save as」は名前をつけて保存です。

Doxygenを実行する

「Run」タブに移動し、「Run doxygen」を押してdoxygenを実行します。
「Run doxygen」がグレーになっていて押せない場合、上述の設定の保存が行われていないことが原因として考えられます。

実行が完了すると「Output produced by doxygen」にログが表示されます。
「*** Doxygen has finished」が表示されていれば処理が完了しています。
ログに「Error」や「Warning」が出てないか確認してください。

「Save log」を押してログをファイルに保存することが出来ます。


ドキュメントを閲覧する

上述の「Destination directory」で指定したフォルダに「html」などのフォルダが作成されています。
「Show HTML output」ボタンを押すことで作成されたドキュメントを閲覧できます。


以下コメント
  • 2009/04/12 doxygen1.5.8に対応し内容を修正 -- uhaku (2009-04-12 22:56:26)
  • 2009/05/01 doxygen1.5.9に対応し内容を修正 -- uhaku (2009-05-01 23:18:28)
  • 2010/07/14 doxygen1.7.1に対応し内容を修正 -- uhaku (2010-07-14 22:32:55)