ホーム

OFF-SOFT.net

OFF-SOFT.net

ウェブやソフトウェアに関するサポート&情報サイトです。サイト構築からソフトウェアの作成、利用まであなたの助けになるかも・・・・しれません。たぶん・・。

Qt (B3) Qt と doxygen

公開日| 2009年07月09日 | コメントはまだありません。
概要 :
 今回は、Qtのドキュメント管理について、記述したいと思います。
ドキュメント管理と言っても、Qtで作成したソフトウェア(ライブラリ)の詳細な設計書の意味でのドキュメント管理のことです。

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

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

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


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

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

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

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

[doxygen]



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


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


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


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


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




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


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


[graphviz]



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


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




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


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

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

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を追加したもの)、一部、変更したものを使ってみましょう。
クラスは、以下の5つのファイルからなります。
  • 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]
1
2
3
4
5
6
7
8
#ifndef _DIAGRAMS_A_H
#define _DIAGRAMS_A_H
class A 
{
public: 
	A *m_self;
};
#endif

[diagrams_b.h]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#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]
1
2
3
4
5
6
7
8
9
10
#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]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#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]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
#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ファイルを作成してみましょう。

doxygenでHELPプロジェクトファイル(.qhp) -> .qch を作成してみましょう
doxygenで、QtAssistantで使うHELPファイルを作成するには、先のconfigファイルに以下のような情報を追加すると通常のドキュメントを作成する手順で自動的に作成できます。

パラメータ名 解説
GENERATE_QHP HELPプロジェクトファイルを作成するかを指定します。
例) YES
QHP_NAMESPACE HELPプロジェクトのネームスペースを指定します。
例) qthelpName
QHP_VIRTUAL_FOLDER HELPプロジェクト内で用いる仮想ディレクトリ名指定します。
例) qthelpFolder
QHP_CUST_FILTER_NAME HELPプロジェクトのカスタムフィルター名を指定します。
例)sample
QHP_CUST_FILTER_ATTRS HELPプロジェクトのカスタムフィルターの属性値をリストで指定します。
参照:関連記事: Qt(8)-2 QtAssistantで使うHELPファイルを作成する
QHP_SECT_FILTER_ATTRS HELPプロジェクトのセクションフィルター(フィルター定義)の属性値をリストで指定します。
参照:関連記事: Qt(8)-2 QtAssistantで使うHELPファイルを作成する
QCH_FILE HELPプロジェクトファイル名を指定します。
何も指定しない場合は、index.qhpとなります。
QHG_LOCATION Qt Help Generatorのコマンドイメージを指定します。
例) "qhelpgenerator"

上記のパラメータを意識しておけば、QtHELPファイルが作成できます。
これを、diagramsQt.cfg のファイル名で保存します。以下は、その中身です。単純なテキストファイルです。

[diagrams.cfg]
PROJECT_NAME       = "Diagrams"
OUTPUT_DIRECTORY   = diagramsQt
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
 
# GENERATE_QHP=YES --> QHP_VIRTUAL_FOLDER=xxx,QHP_NAMESPACE=yyy
GENERATE_QHP           = YES
QHP_NAMESPACE          = qthelpName
QHP_VIRTUAL_FOLDER     = qthelpFolder
QHP_CUST_FILTER_NAME   = sample
QHP_CUST_FILTER_ATTRS  = 
QHP_SECT_FILTER_ATTRS  = 
 
# need set of QHG_LOCATION
QCH_FILE               = 
QHG_LOCATION           = "qhelpgenerator"

doxygenでドキュメントを作成しましょう
先に記述したのを同じように、コマンドから以下のように入力することでドキュメントを作成できます。

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

同じですね。ファイル名を指定するだけです。
完了すると、先のconfigファイルに指定したように論理パスのdiagramsへhtmlというディレクトリが作成されていると思います。
また、今回は、html以外に、qchというディレクトリが作成されていると思います。
これが、QtHELPファイルが作成されているディレクトリです。
ここには、プロジェクト名.qch (Diagrams.qch)という名前でファイルが作成されているはずです。

もし、作成されていないようであれば、上記のパラメータに誤りがないか、また、qhelpgeneratorのパスが設定されているか確認してみましょう。

では、このDiagrams.qchの中身を確認してみましょう。
通常のQtAssistantを起動します。

%Qtインストール先ディレクトリ%\bin\assistant.exe

をダブルクリックで起動します。


QtAssistantへ、先のDiagrams.qchを追加します。


カスタムフィルターで、configファイルに"QHP_CUST_FILTER_NAME = sample"と指定しましたので、"Sample"があるはずです。切り替えてみましょう。


画面左のコンテンツツリーに"Diagrams"が表示されたと思います。クリックしてみましょう。
画面右へ、doxygenで作成された画面が表示されたと思います。



このようにdoxygenを使って、自分で作成したライブラリなどのQtヘルプをQtAssistantへ追加できるようになります。
このあたりは、VisualStudioのHTMLヘルプに追加できるのと同じ感覚ですね。
Qt Creatorでどこまで、連携するのかは、わかりませんが、ここで、追加しておけば、検索できるはずですので、判らなくなったときには、 QtAssistantで簡単に表示してくれるのでしょう。

ここでは、Qtに関連するところのみを紹介しましたが、 doxygenには、今回紹介した機能以外に、たくさんの機能があります。色々と試されるのも良いと思います。
サンプルの中には、UML(クラス)図を出力するパラメータの例(diagramsU.cfg)を同梱していますので、ご参考ください。

もっと、Qt関連について詳しく知りたい方は、以下の本なども良いと思います。
Qtに関する日本語の本が少ないですね。「入門書」は、さすがに、このページを読まれるくらいの方は不要だと思います。
やっぱり、本+ネット+試してみる!!の3本柱でやっていく以外にないように思います。


コメント

コメントをどうぞ







  • はてなブックマークへ追加する
  • Facebookでシェアする
  • twitter でつぶやく
  • Google Plusでシェアする
  • Pocketでシェアする
ページトップへ