Qt (B3) Qt と doxygen

公開日| 2009年07月09日 | コメントはまだありません。

カテゴリー:Qt |

概要 :
　今回は、Qtのドキュメント管理について、記述したいと思います。
ドキュメント管理と言っても、Qtで作成したソフトウェア（ライブラリ）の詳細な設計書の意味でのドキュメント管理のことです。

　ソフトウェア（ライブラリ）の詳細な設計書のようなドキュメント管理として、Freeで最も有名なところで、doxygenがあります。
このdoxygenは、もともとQtのドキュメント管理をすることを目的に作成されています。（筆者は、最近まで、そんなこと知りませんでした。）

　そのため、doxygenは、Qtとの親和性が強いとされています。（当然、signals,slotsなどもちゃんと認識して、ドキュメントへ出力します。）

　今回は、そのdoxygenを使って、簡単なドキュメント作成について記述したいと思います。

doxygen: http://www.stack.nl/~dimitri/doxygen/
ダウンロード : http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc

graphviz: http://www.graphviz.org/
ダウンロード : http://www.graphviz.org/Download..php

ここで使用したサンプルソースコード：

QtサンプルB3

まずは、doxygenをインストール

doxygenを上記のダウンロードサイトから最新をダウンロードします。
また、継承関係やUMLなどの図が必要なら、graphvizも同じようにダウンロードします。

いずれも、Windows版は、インストーラですので、画面に従いインストールするだけです。

以下に簡単な画面のみを記載しておきます。

[doxygen]

ここで、同意するを選択する。

ここで、インストール先を変更する場合のみ、上記に設定する。

ここは、インストール対象を指定しますが、特別、GUIツールやサンプルが不要でない限り全てチェックで良いと思います。

ここで、スタートメニューに追加する名前を指定する。
スタートメニューに追加したくない場合は、"Don't create start menu folder"にチェックを入れる。

特に問題なければ、"Install"をクリックしてインストールを実行する。

特に問題なく、インストールできたら、上記の画面が表示され、"Next"をクリックする。
この画面は、最新版のチェックやフォローアップのリンク先などが記載されています。

この画面で終了です。"Finish"をクリックして完了。

[graphviz]

ここで、インストール先を変更する場合のみ、上記に設定する。

特に問題なければ、"Next"をクリックしてインストールを実行する。

特に問題なく、インストールできたら、上記の画面が表示され、終了です。"Close"をクリックして完了。

インストールを終えたら、正しくパスが設定されているか確認しましょう。
DOSプロンプト画面を表示します。
[スタート]-[プログラム]-[アクセサリ]-[コマンドプロンプト]

以下の２つのコマンドを入力してみましょう。

C:\> doxygen -h
Doxygen version 1.5.9
Copyright Dimitri van Heesch 1997-2008

You can use doxygen in a number of ways:

1) Use doxygen to generate a template configuration file:
    doxygen [-s] -g [configName]

    If - is used for configName doxygen will write to standard output.

2) Use doxygen to update an old configuration file:
    doxygen [-s] -u [configName]

3) Use doxygen to generate documentation using an existing configuration file:
    doxygen [configName]

    If - is used for configName doxygen will read from standard input.

4) Use doxygen to generate a template file controlling the layout of the
   generated documentation:
    doxygen -l layoutFileName.xml

5) Use doxygen to generate a template style sheet file for RTF, HTML or Latex.
    RTF:   doxygen -w rtf styleSheetFile
    HTML:  doxygen -w html headerFile footerFile styleSheetFile [configFile]
    LaTeX: doxygen -w latex headerFile styleSheetFile [configFile]

6) Use doxygen to generate an rtf extensions file
    RTF:   doxygen -e rtf extensionsFile

If -s is specified the comments in the config file will be omitted.
If configName is omitted Doxyfile' will be used as a default.

C:\> dot -?
Usage: dot [-Vv?] [-(GNE)name=val] [-(KTlso)<val>] <dot files>
(additional options for neato)    [-x] [-n<v>]
(additional options for fdp)      [-L(gO)] [-L(nUCT)<val>]
(additional options for memtest)  [-m]
(additional options for config)  [-cv]

 -V          - Print version and exit
 -v          - Enable verbose mode
 -Gname=val  - Set graph attribute 'name' to 'val'
 -Nname=val  - Set node attribute 'name' to 'val'
 -Ename=val  - Set edge attribute 'name' to 'val'
 -Tv         - Set output format to 'v'
 -Kv         - Set layout engine to 'v' (overrides default based on command name)
 -lv         - Use external library 'v'
 -ofile      - Write output to 'file'
 -O          - Automatically generate an output filename based on the input 
            filename with a .'format' appended. (Causes all -ofile options to be ignored.)
 -P          - Internally generate a graph of the current plugins.
 -q[l]       - Set level of message suppression (=1)
 -s[v]       - Scale input by 'v' (=72)
 -y          - Invert y coordinate in output

 -n[v]       - No layout mode 'v' (=1)
 -x          - Reduce graph

 -Lg         - Don't use grid
 -LO         - Use old attractive force
 -Ln<i>      - Set number of iterations to i
 -LU<i>      - Set unscaled factor to i
 -LC<v>      - Set overlap expansion factor to v
 -LT[*]<v>   - Set temperature (temperature factor) to v

 -m          - Memory test (Observe no growth with top. Kill when done.)

 -c          - Configure plugins (Writes $prefix/lib/graphviz/config
               with available plugin information.  Needs write privilege.)
 -v          - Enable verbose mode

C:\>

上記のようにヘルプテキストが表示されればOKです。
そうでない場合は、自身で、環境変数のPATHに、以下のディレクトリを追加します。

%doxygenインストール先ディレクトリ%\bin
%graphvizインストール先ディレクトリ%\bin

doxygenを使ってみましょう

サンプルソースコードを準備しましょう

doxygenを使ってみるためにサンプルのソースコードが必要です。
ここでは、doxygenのサンプルであるexamples\diagramsを、Qtらしく(signals,slotsを追加したもの)、一部、変更したものを使ってみましょう。
クラスは、以下の５つのファイルからなります。

diagrams_a.h
-- class A を定義
-- 継承元なし
diagrams_b.h
-- class B を定義
-- 継承元 QMainWindow(Qtクラス)
diagrams_c.h
-- class C を定義
-- 継承元 A
diagrams_d.h
-- class D を定義
-- 継承元 A,B
diagrams_e.h
-- class E を定義
-- 継承元 D

[diagrams_a.h]

#ifndef _DIAGRAMS_A_H
#define _DIAGRAMS_A_H
class A 
{
public: 
	A *m_self;
};
#endif

[diagrams_b.h]

#ifndef _DIAGRAMS_B_H
#define _DIAGRAMS_B_H
#include <QMainWindow>
class A;
class B : public QMainWindow
{
	Q_OBJECT
public: 
	A *m_a;
 
protected slots: 
	void slotB(int n);
 
signals: 
	void sigB(int n);
};
#endif

[diagrams_c.h]

#ifndef _DIAGRAMS_C_H
#define _DIAGRAMS_C_H
#include "diagrams_c.h"
class D;
class C : public A 
{
public:
	D *m_d;
};
#endif

[diagrams_d.h]

#ifndef _DIAGRAM_D_H
#define _DIAGRAM_D_H
#include "diagrams_a.h"
#include "diagrams_b.h"
class C;
class D : virtual protected  A, private B 
{
	Q_OBJECT
public: 
	C m_c;
 
protected slots: 
	void slotD(int n);
 
signals: 
	void sigD(int n);
};
#endif

[diagrams_e.h]

#ifndef _DIAGRAM_E_H
#define _DIAGRAM_E_H
#include "diagrams_d.h"
class E : public D 
{
	Q_OBJECT
 
private slots: 
	void slotE(int n);
 
signals: 
	void sigE(int n);
};
#endif

doxygenのconfigファイル(パラメータファイル)を作成しましょう

次に、doxygenを使ってみるためにdoxygenのパラメータを設定したファイル(configファイル)が必要です。
ここでは、doxygenのサンプルであるexamples\diagramsを、変更したものを使ってみましょう。

パラメータ名	解説
PROJECT_NAME	プロジェクト名を指定します。例）"Diagrams"
OUTPUT_DIRECTORY	出力先ディレクトリ名（論理パス）を指定します。例）diagrams
HAVE_DOT	DOTツール（図）を使うかどうかを指定します。例）YES
EXTRACT_ALL	全てのドキュメントのエンティティ（要素）を展開するか指定します。例）YES
GENERATE_LATEX	LATEXフォーマットで出力するか指定します。例）NO
GENERATE_MAN	MANフォーマットで出力するか指定します。例）NO
GENERATE_RTF	RTFフォーマット(MiscroSoft Word)で出力するか指定します。例）NO
CASE_SENSE_NAMES	Doxygenで出力するファイル名を大文字にするか指定します。(NO:小文字で出力します) 例）NO
ENABLE_PREPROCESSING	Cプリプロセッサの評価を行うか指定します。例）YES
INPUT	対象ファイルのディレクトリ（論理パス）を指定します。例）.
FILE_PATTERNS	対象ファイルのパターンを指定します。例）diagrams_*.h
QUIET	Doxygenでメッセージが常に表示するかを指定します。(NO:表示する) 例）YES
JAVADOC_AUTOBRIEF	JvaDoc形式でのコメントを有効にするか指定します。例） YES
QT_AUTOBRIEF	Qt形式でのコメントを有効にするか指定します。例） YES
EXTRACT_PRIVATE	privateメソッド、メンバーを出力するか指定します。例） YES

ざっと、これぐらいのパラメータを意識しておけば、とりあえず、ドキュメントを作成できます。
これを、diagrams.cfg のファイル名で保存します。以下は、その中身です。単純なテキストファイルです。

[diagrams.cfg]

PROJECT_NAME       = "Diagrams"
OUTPUT_DIRECTORY   = diagrams
HAVE_DOT           = YES
EXTRACT_ALL        = YES
GENERATE_LATEX     = NO
GENERATE_MAN       = NO
GENERATE_RTF       = NO
CASE_SENSE_NAMES = NO
ENABLE_PREPROCESSING       = YES
INPUT              = .
FILE_PATTERNS      = diagrams_*.h
QUIET              = YES
JAVADOC_AUTOBRIEF = YES
QT_AUTOBRIEF      = YES
EXTRACT_PRIVATE        = YES

doxygenでドキュメントを作成しましょう

ここまで準備できたら、doxygenは、コマンドから以下のように入力することでドキュメントを作成できます。

%diagrams.cfgのあるディレクトリ%> doxygen diagrams.cfg
%diagrams.cfgのあるディレクトリ%>

簡単ですね。ファイル名を指定するだけです。
完了すると、先のconfigファイルに指定したように論理パスのdiagramsへhtmlというディレクトリが作成されていると思います。
その中のindex.htmlをクリックして、表示してみましょう。

以下は、クラスBを表示した画面です。

ちゃんと、継承関係が図で表示されています。また、シグナル、スロットも正しく表示されています。

doxygenには、他に、QtAssistantで使うHELPファイルを作成することができます。
このあたりが、親和性が高いというところですね。
では、次に、QtAssistantで使うHELPファイルを作成してみましょう。