Doxygen latest release v1.5.9 - last update 14 Feb 2011

特殊コマンド

はじめに

ドキュメント内のすべてのコマンドは、バックスラッシュ (\)、 またはアットマーク (@) で始まります。 お望みであれば、以下のバックスラッシュで始まるすべてのコマンドを、 それに対応したアットマークで始まるものに置き換えることができます。

いくつかのコマンドは、1つまたはそれ以上の引数を取ります。 各引数には、ある決まった範囲があります:

  • <山> 括弧が使われている場合、引数は 1単語からなります。
  • (丸) 括弧が使われている場合、引数は、コマンドのある場所からその行の終わりまでとなります。
  • {波} 括弧が使われている場合、引数は、次のパラグラフの頭までとなります。 パラグラフは、空行かセクション指示子で区切られます。

[角] 括弧が使われている場合、引数は省略可能です。

以下は、全コマンドをアルファベット順に整列したリストです (説明への参照付き)。

以下のサブセクションでは、doxygen が認識する全コマンドのリストを説明します。 コマンドとして認識しないものは、通常のテキストとして扱います。

--- 構造指示子 (Structural indicators) ---

\addtogroup <名前> [(タイトル)]

\defgroup と同様グループを定義しますが、それとは対照的に、 同じ <名前> を2回以上使用しても警告は発せられず、 マージされたドキュメントとコマンドの引数として最初に見つかったタイトルを持つ 1つのグループが作成されます。

タイトルはオプションです。そこで、このコマンドを使うと、 以下のように @{ と @} を用いて、 既存のグループにいくつかの要素を追加することもできます。

  /*! \addtogroup mygrp
   *  グループ `mygrp' に追加するドキュメント
   *  @{
   */

  /*!
   *  関数
   */
  void func1()
  {
  }

  /*! 他の関数 */
  void func2()
  {
  }

  /*! @} */
参照:
ページ グループ化、セクション \defgroup\ingroup および \weakgroup

\callgraph

このコマンドが関数またはメソッドのコメント・ブロックに指定され、 HAVE_DOTYES ならば、(関数やメソッドの実装において、 他のドキュメント付けされた関数を呼び出していれば) 関数の呼び出しグラフを生成します。 呼び出しグラフは、CALL_GRAPH の値に関わらず生成されます。

覚え書き:
呼び出しグラフの完全性 (と正確性) は、doxygenの(完全でない)コード構文解析に依存します。

\callergraph

このコマンドが関数またはメソッドのコメント・ブロックに指定され、 HAVE_DOTYES ならば、(関数やメソッドの実装において、 他のドキュメント付けされた関数を呼び出していれば) 関数の呼び出し元グラフを生成します。 呼び出し元グラフは、CALLER_GRAPH の値に関わらず生成されます。

覚え書き:
呼び出しグラフの完全性 (と正確性) は、doxygenの(完全でない)コード構文解析に依存します。

\category <名前> [<ヘッダーファイル>] [<ヘッダー名>]

Objective-C 専用: コメント・ブロックが名前 <名前> によってクラスカテゴリーに対するドキュメントを保持していることを示します。 引数は \class コマンドと同じです。

参照:
セクション \class.

\class <名前> [<ヘッダーファイル>] [<ヘッダー名>]

<名前> というクラスのドキュメントがコメントブロックに含まれることを指示します。 オプション引数として、ヘッダーファイルとヘッダー名を指定することができます。 ヘッダーファイルが指定されると、その字句通りのコピーへのリンクが HTML ドキュメントに埋め込まれます。 <ヘッダー名> 引数を使用すれば、クラスのドキュメントで用いられているリンクの名前を、<ヘッダーファイル> 以外のもので上書きすることができます。 これは、インクルード名が、デフォルトのインクルードパス(<X11/X.h> など) 上にないような場合に役立ちます。 <ヘッダー名> 引数を使って、インクルード文の見え方を指定することもできます。 それには、名前の囲りに引用符か山括弧を付加します。名前だけの場合は山括弧を使います。後の2つの引数は、\headerfileコマンドでも指定できます。

例:
/* A dummy class */

class Test
{
};

/*! \class Test class.h "inc/class.h"
 *  \brief This is a test class.
 *
 * Some details about the Test class
 */
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

\def <名前>

コメント・ブロックが、#define マクロに対するドキュメントを保持していることを指示します。

例:
/*! \file define.h
    \brief testing defines
    
    This is to test the documentation of defines.
*/

/*!
  \def MAX(x,y)
  Computes the maximum of \a x and \a y.
*/

/*! 
   Computes the absolute value of its argument \a x.
*/
#define ABS(x) (((x)>0)?(x):-(x))
#define MAX(x,y) ((x)>(y)?(x):(y))
#define MIN(x,y) ((x)>(y)?(y):(x)) 
        /*!< Computes the minimum of \a x and \a y. */
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

\defgroup <名前> (グループタイトル)

コメント・ブロックが、クラス、ファイル、または名前空間の グループ に対するドキュメントを保持していることを指示します。 これを使うと、クラス、ファイル、または名前空間をいくつかのカテゴリに分類した上で、 それらのカテゴリにドキュメント付けをすることができます。 また、グループは、他のグループのメンバーとしても使うことができるので、 グループの階層を構築することができます。

<名前> 引数は、単一語の識別子でなければなりません。

参照:
ページ グループ化、セクション \ingroup\addtogroup\weakgroup

\dir [<パス>]

ディレクトリについての記述がコメントブロック内にあることを示します。 引数"パス"には、ディレクトリ名と、プロジェクトで他のディレクトリと 区別のつくユニークなパスを指定してください。SHOW_DIRECTORIES は、ディレクトリ情報の可視・不可視を決定します。 STRIP_FROM_PATH はフルパスのうち省略する部分を決定します。


\enum <名前>

<名前> という列挙型データに対するドキュメントがコメントブロックに含まれることを 示します。 列挙型データがクラスのメンバーなのにそのドキュメントブロックはクラス定義の外側に あるような場合は、クラスのスコープも指定する必要があります。 コメント・ブロックが列挙型データ宣言の直前にある場合は、\enum コメントを省略できます。

メモ:
名前のない列挙型データの型はドキュメント付けできませんが、 値にはドキュメント付けできます。
例:
class Test
{
  public:
    enum TEnum { Val1, Val2 };

    /*! Another enum, with inline docs */
    enum AnotherEnum 
    { 
      V1, /*!< value 1 */
      V2  /*!< value 2 */
    };
};

/*! \class Test
 * The class description.
 */

/*! \enum Test::TEnum
 * A description of the enum type.
 */

/*! \var Test::TEnum Test::Val1
 * The description of the first enum value.
 */
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

\example <ファイル名>

ソースコード例に対するドキュメントが、コメントブロックに含まれることを示します。 ソースファイルの名前は <ファイル名> です。 ファイルのテキストは、コメントブロックに含まれるドキュメントの直後に取り込まれます。 例のすべてがリスト化されます。 ソースコードから、解説つきのメンバーやクラスを見つけます。見つかればその名前は ドキュメントでクロスリファレンスされます。 doxygen の設定ファイルの EXAMPLE_PATH タグを用いると、 複数のソースファイルまたはディレクトリを指定することができます。

EXAMPLE_PATH タグによって指定された例ファイルの集合に対して、 <ファイル名> だけでは一意にファイルを決定できない場合、 それを解消するために、絶対パスの一部を含めることができます。

例として、2つ以上のソースファイルが必要な場合は、 \include コマンドを使用することができます。

例:
/** A Test class.
 *  More details about this class.
 */

class Test
{
  public:
    /** An example member function.
     *  More details about this function.
     */
    void example();
};

void Test::example() {}

/** \example example_test.cpp
 * This is an example of how to use the Test class.
 * More details about this example.
 */
ここで、実例ファイル example_test.cpp の内容は、以下のようなものです:
void main()
{
  Test t;
  t.example();
}
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。
参照:
セクション \include

\extends [<名前>]

cmdextendsは、もともと継承関係の概念をサポートしないプログラミング言語(Cなど)の場合に使えます。

exampleディレクトリの manual.cを見れば、このコマンドの使い方がわかります。

ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。
参照:
セクション \implements とセクション \memberof

\file [<名前>]

<名前> というソースファイルまたはヘッダーファイルの解説がコメントブロックに 含まれることを示します。 ファイル名だけでは一意にならない場合、パス (の一部) を含んでも構いません。 ファイル名が省略された場合 (つまり、\file 以降行が空白の場合) は、 \file コマンドを含むドキュメントブロックは、その記述場所に属します。

重要:
グローバルな関数、変数、typedef および enum の解説は、それが記述されたファイルも ドキュメント化されている場合のみ出力されます。
例:
/** \file file.h
 * A brief file description.
 * A more elaborated file description.
 */

/**
 * A global integer value.
 * More details about this value.
 */
extern int globalValue;
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。
覚え書き:
上記の例では、設定ファイルで JAVADOC_AUTOBRIEF を YES にしています。

\fn (関数宣言)

関数(グローバルまたはクラスのメンバー)の解説がコメントブロックに含まれることを 示します。 このコマンドは、コメントブロックが関数宣言・定義の前後に置かれていない 場合のみ必要となります。

コメントブロックが関数宣言・定義の前に置かれているのであれば、 このコマンドは省略できます (冗長性を避けるためにもそうすべきです)。

\fn コマンドの後には、引数を含む完全な関数宣言を、1行で指定する必要があり、 (コマンドの) 引数は行末で終わります。

\警告 このコマンドは、必須の場合だけ使ってください。 情報の重複によりエラーが起こりかねません。

例:
class Test
{
  public:
    const char *member(char,int) throw(std::out_of_range);
};

const char *Test::member(char c,int n) throw(std::out_of_range) {}

/*! \class Test
 * \brief Test class.
 *
 * Details about Test.
 */

/*! \fn const char *Test::member(char c,int n) 
 *  \brief A member function.
 *  \param c a character.
 *  \param n an integer.
 *  \exception std::out_of_range parameter is out of range.
 *  \return a character pointer.
 */
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。
参照:
セクション \var および \typedef

\headerfile <ヘッダファイル> [<ヘッダ名>]

このコマンドは、クラス、構造体、共用体のドキュメントが定義の前にある場合に 使います。 このコマンドの引数は、\cmdclassの第2引数と第3引数と 同じです。 ヘッダファイル名は、アプリケーションがインクルードするファイルを指し、 クラス、構造体、共用体の定義を含むファイルです。 <header-name>引数は、クラスドキュメントで使っているリンクの名前を <header-file>とは別の名前で上書きしたいときに使います。 デフォルトのインクルードパス(<X11/X.h>など)にインクルード名がない場合に 有効です。 また、<header-name>でインクルード文の見え方を指定することもできます。 これには、引用符や山括弧で名前を囲みます。 名前だけしかない場合は山括弧を使います。


\hideinitializer

デフォルトでは、define の値および変数の初期化子は、 30行を超えないかぎり、表示されます。 define または変数のコメントブロックの中でこのコマンドを使うと、 初期化子は常に非表示になります。

参照:
セクション \showinitializer

\implements <名前>

cmdimplementsは、もともと継承関係の概念をサポートしないプログラミング言語(Cなど)の場合にマニュアルで指定します。

exampleディレクトリの manual.cを見れば、このコマンドの使い方がわかります。

ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。
参照:
セクション \implements とセクション \memberof

\ingroup (<グループ名> [<グループ名> <グループ名>])

\ingroup コマンドが、 クラス、関数または名前空間のコメントブロックで使われている場合、 それ (クラス、関数または名前空間) は、 <グループ名> で識別されるグループ (または複数グループ) に追加されます。

参照:
ページ グループ化、セクション \defgroup, \addtogroup\weakgroup

\interface <名前> [<ヘッダーファイル>] [<ヘッダー名>]

<名前> というインタフェースの解説が、コメントブロックに含まれることを示します。 引数は、\class コマンドのものと同じです。

参照:
セクション \class

\internal

`For internal use only' (内部用)というメッセージを出力し、\internal command の次からコメントブロックの最後またはセクションの最後 (どちらが先でも) までの テキストは "internal" (内部)とマークされます。

\internal コマンドをセクション内部に指定する ( \section の例参照) と、コマンドの後ろのすべてのサブセクション も同様に内部とみなします。同レベルの新しいセクションだけが再び可視になります。

内部記述を出すか隠すかは、設定ファイルの INTERNAL_DOCS を使ってください。


\mainpage [(タイトル)]

\mainpage コマンドをコメントブロック内に指定すると、 インデックスページ (HTML) または、最初の章 ($\mbox{\LaTeX}$) を カスタマイズするのにこのブロックが使われます。

タイトル引数が指定されると、doxygen が生成するデフォルトのタイトルを置換します。 タイトルが不要なら、\mainpage の引数に notitle を指定できます。

以下に例を挙げます:

/*! \mainpage 私の個人的なインデックスページ
 *
 * \section intro_sec 導入
 *
 * これは導入です
 *
 * \section install_sec インストール
 *
 * \subsection step1 ステップ1: ボックスを開く
 *  
 * etc...
 */

\ref index によってメインページを参照することができます。 (treeview が無効であれば、むしろ \ref main を使うべきです)

参照:
セクション \section、 セクション \subsection、 セクション \page

\memberof <名前>

このコマンドは、関数をクラスメンバーとして指示できます。\relatesに似ています。このコマンドだけで関数をクラスの実メンバーとして表示します。 メンバー関数の概念をもともとサポートしていないプログラミング言語(Cなど)で有用です。

\public, \protected, \privateと一緒に使うこともできます。

exampleディレクトリの manual.cを見れば、このコマンドの使い方がわかります。 ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

参照:
セクション \extends, \implements, \public, \protected, \private

\name (ヘッダー)

このコマンドは、コメントブロックをメンバーグループのヘッダー定義にします。 コメントブロックの後には、グループのメンバーを含む、 //@{ ... //@} ブロックが続かなければなりません。

例については、セクション メンバーグループ を参照。


\namespace <名前>

<名前> という名前空間の解説がコメントブロックに記述されていることを示します。


\nosubgrouping

このコマンドは、クラスの解説内に指定できます。 Public/Protected/Private/... セクションのサブグループとしてメンバーグループが 置かれるのを避けることができます。


\overload [(関数宣言)]

このコマンドを使うと、オーバーロードされたメンバー関数に対して、 以下のような標準的なテキストが生成されます:

`This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.'

オーバーロードされたメンバー関数に対する解説が、関数宣言・定義の前にない場合は、 オプションの引数で、正しく関数指定をする必要があります。

ドキュメントブロック内部にある他のすべてのドキュメントは、 生成されたメッセージの後に追加されます。

メモ 1:
オーバーロードされたメンバーの解説は、前においてください。 解説の順入れ替えを防ぐには、SORT_MEMBER_DOCSNO を設定します。
メモ 2:
\overload コマンドは、一行だけのコメント内では機能しません。
例:
class Test 
{
  public:
    void drawRect(int,int,int,int);
    void drawRect(const Rect &r);
};

void Test::drawRect(int x,int y,int w,int h) {}
void Test::drawRect(const Rect &r) {}

/*! \class Test
 *  \brief A short description.
 *   
 *  More text.
 */

/*! \fn void Test::drawRect(int x,int y,int w,int h)
 * This command draws a rectangle with a left upper corner at ( \a x , \a y ),
 * width \a w and height \a h. 
 */

/*!
 * \overload void Test::drawRect(const Rect &r)
 */

ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

\package <名前>

<名前> という Java パッケージの解説がコメントブロックに記述されていることを 示します。


\page <名前> (タイトル)

特定のクラスやファイル、メンバーに直接には関連付けられていない解説の一部が コメントブロックに含まれることを示します。 HTML ジェネレータは、その解説を含むページを作成します。 $\mbox{\LaTeX}$ ジェネレータは、`Page documentation' という章で、 新しいセクションを開始します。

例:
/*! \page page1 A documentation page
  Leading text.
  \section sec An example section
  This page contains the subsections \ref subsection1 and \ref subsection2.
  For more info see page \ref page2.
  \subsection subsection1 The first subsection
  Text.
  \subsection subsection2 The second subsection
  More text.
*/

/*! \page page2 Another page
  Even more info.
*/
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。
メモ:
<名前> 引数は、英文字と数字との組み合わせからなります。 もし、<名前> 引数で、大文字だけを使ったり (MYPAGE1 など)、 大文字と小文字をミックスして使ったり (MyPage1 など) したい場合は、 CASE_SENSE_NAMESYES に設定しておく必要があります。 ただし、これは、ファイルシステムが大文字・小文字を区別する場合にのみ 有効なアドバイスです。その他のシステムでは (また可搬性を高めるためにも)、 ページへの参照となる <名前> には、 すべて小文字 (mypage1 など) を使用するべきです。
参照:
セクション \section、 セクション \subsection、 セクション \ref

\private

このコマンドは、コメントブロックでドキュメント付けされたメンバーがprivateであることを示します。同じクラス内のメンバーからしかアクセスできないメンバーのことです。

Doxygenは、オブジェクト指向の言語では、メンバーの保護レベルを自動認識します。 このコマンドは、保護レベルの概念をもともとサポートしていない言語(C,PHP 4など)で使うことが目的です。

privateメンバーのセクションの始まりを、C++での"private:"クラスマーカー同様に示すには、\privatesectionを使います。

参照:
セクション \memberof, \public, \protected

\property (qualified property name)

プロパティ(グローバルか、クラスメンバーとして)についての記述が コメントブロックに含まれることを示します。 このコマンドは、\var and \fn と同義です。

参照:
セクション \fn\var.

\protected

このコマンドは、コメントブロックでドキュメント付けされたメンバーがprotectedであることを示します。同じクラスまたは派生クラスのメンバーからしかアクセスできないメンバーのことです。

Doxygenは、オブジェクト指向の言語では、メンバーの保護レベルを自動認識します。 このコマンドは、保護レベルの概念をもともとサポートしていない言語(C,PHP 4など)で使うことが目的です。

protectedメンバーセクションの始まりを、C++での"protected:"クラスマーカー同様に示すには、\protectedsectionを使います。

参照:
セクション \memberof, \public, \private

\protocol <名前> [<ヘッダーファイル>] [<ヘッダー名>]

名前 <name> 付きの Objective-C でのプロトコルについての記述がコメント ブロックに含まれることを示します。引数は、\class コマンドと同じです。

参照:
セクション \class.

\public

このコマンドは、コメントブロックでドキュメント付けされたメンバーがpublicであることを示します。どのクラスや関数からもアクセスできるメンバーのことです。

Doxygenは、オブジェクト指向の言語では、メンバーの保護レベルを自動認識します。 このコマンドは、保護レベルの概念をもともとサポートしていない言語(C,PHP 4など)で使うことが目的です。

publicメンバーセクションの始まりを、C++での"public:"クラスマーカー同様に示すには、\publicsectionを使います。

参照:
セクション \memberof, \protected, \private

\relates <名前>

このコマンドは、<名前> という非メンバー関数の解説で使います。 クラスドキュメントの「関連する関数」というセクションに関数を出力します。 フレンドでないにもかかわらず、特定のクラスに強く結び付いている関数に ドキュメントを付けるのに有用です。 これによりファイルにドキュメント付けをする必要性がなくなりますが、 関数にしか機能しません。

例:
/*! 
 * A String class.
 */ 
  
class String
{
  friend int strcmp(const String &,const String &);
};

/*! 
 * Compares two strings.
 */

int strcmp(const String &s1,const String &s2)
{
}

/*! \relates String
 * A string debug function.
 */
void stringDebug()
{
}
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

\relatesalso <名前>

このコマンドは、非メンバー関数 <name> の記述で使えます。これによって、 クラスドキュメントの「関連関数」セクションの中にも、普通のファイルドキュメント にも指定関数を出力します。フレンドでないにもかかわらずあるクラスとのつながりが強い 関数をドキュメント付けするのに有効です。関数にしか機能しません。


\showinitializer

デフォルトでは、define の値および変数の初期化子は、 30行未満しか表示されません。 define または変数のコメントブロックの中でこのコマンドを使うと、 初期化は無条件に表示されるようになります。

参照:
セクション \hideinitializer

\struct <名前> [<ヘッダーファイル>] [<ヘッダー名>]

<名前> という構造体の解説がコメントブロックに含まれることを示します。 引数は、\class コマンドのものと同じです。

参照:
セクション \class

\typedef (typedef 宣言)

typedef(グローバルまたはクラスメンバー)の解説がコメントブロックに含まれることを 示します。 このコマンドは、\var および \fn と等価です。

参照:
セクション \fn および \var

\union <名前> [<ヘッダーファイル>] [<ヘッダー名>]

<名前> という共用体の解説がコメントブロックに含まれることを示します。 引数は、\class コマンドのものと同じです。

参照:
セクション \class

\var (変数宣言)

変数やenum 値(グローバルまたはクラスメンバー)の解説がコメントブロックに含まれる ことを示します。 このコマンドは、\typedef および \fn と等価です。

参照:
セクション \fn および \typedef

\weakgroup <名前> [(タイトル)]

\addtogroup と全く同様に使用することができますが、 グループ化定義での衝突を解消するという用には優先度が低くなります。

参照:
ページ グループ化 および セクション \addtogroup

--- セクション指示子 (Section indicators) ---


\attention { 注意すべきテキスト }

注意が必要なメッセージを入力するパラグラフを開始します。 パラグラフはインデントされます。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数並んだ \attention コマンドは1つのパラグラフに結合されます。 \attention コマンドは、空行か他のセクション導入コマンドのところで終わりです。

\author { 作者のリスト }

ひとつ以上の作者名を入力するパラグラフを開始します。 パラグラフはインデントされます。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数並んだ \author コマンドは、1つのパラグラフに結合されます。 このコマンドは行を作ります。 1つの \author コマンドで複数の作者名を挙げることもできます。 \author コマンドは、空行か他のセクション導入コマンドのところで終わりです。

例:
/*! \class WindowsNT
 *  \brief Windows Nice Try.
 *  \author Bill Gates
 *  \author Several species of small furry animals gathered together 
 *          in a cave and grooving with a pict.
 *  \version 4.0
 *  \date    1996-1998
 *  \bug It crashes a lot and requires huge amounts of memory.
 *  \bug The class introduces the more bugs, the longer it is used.
 *  \warning This class may explode in your face.
 *  \warning If you inherit anything from this class, you're doomed.
 */

class WindowsNT {};
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

\brief {要約説明}

要約説明の役割をするパラグラフを開始します。 クラスとファイルでは、リストや、ドキュメントページの最初の部分で使われます。 クラスやファイルのメンバーでは、メンバーの宣言箇所に配置されたり、 詳細説明の前に付加されたりします。 要約説明は、複数行にできます(それでも簡潔なほうがよい)。 要約説明は、空行または他のセクション導入コマンドで終わります。 複数の \brief コマンドは結合されます。 例については、\author を参照してください。

同義語: \short


\bug { バグ記述 }

ひとつ以上のバグをリポートするパラグラフを開始します。 パラグラフはインデントされます。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \bug コマンドが並ぶと、1つのパラグラフに結合されます。 各々のバグ記述は新しい行で始まります。 別のやり方として、1つの \bug コマンドで複数のバグを挙げることもできます。 \bug コマンドは、空行または他のセクション導入コマンドで終了します。 例については、\author を参照してください。


\cond [<セクションラベル>]

条件付セクションの始まりを示し、\endcond コマンド(別のコメントブロックに指定します)で終了します。こういった コマンドの組を使う主な目的は、ファイルの一部を処理から(条件付で)除外することです。 (以前のDoxygenでは、これはCプロセッサコマンドでしかできませんでした)

\cond コマンドと \endcond コマンドの間のセクションは、 設定オプションのENABLED_SECTIONSにセクションラベルを 追加することで含めることができます。セクションラベルを省略すると、セクションは 無条件に処理から除外されます。

コメントブロック内の条件付セクションの場合は、 \if ... \endif ブロックを使ってください。

条件付セクションはネストできます。この場合ネストしたセクションを出力するには それを内包するセクションとともに含めなければなりません。

コマンド使用例を示します。

/** インターフェース */
class Intf
{
  public:
    /** メソッド */
    virtual void func() = 0;

    /// @cond TEST

    /** テストに使うメソッド */
    virtual void test() = 0;

    /// @endcond
};

/// @cond DEV
/*
 *  インターフェースの実装 
 */
class Implementation : public Intf
{
  public:
    void func();

    /// @cond TEST
    void test();
    /// @endcond

    /// @cond
    /** このメソッドは使わなくなった。
     *  ドキュメントに出ない。
     */
    void obsolete();
    /// @endcond
};

/// @endcond 

出力結果は、ENABLED_SECTIONSTEST か, DEV かによって違ってきます。


\date { 日時記述 }

ひとつ以上の日時を記入するパラグラフを開始します。 パラグラフはインデントされます。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \date コマンドが並ぶと、1つのパラグラフに結合されます。 各々の日時記述は、新しい行から始まります。 1つの \date コマンドで複数の日時を記述することもできます。 \date コマンドは、空行または他のセクション導入コマンドで終了します。 例については、\author を参照してください。


\deprecated { 記述 }

ドキュメントブロックが非推奨要素に属することを示すパラグラフの始まりです。 代替や予想有効期間などを記述します。


\details {詳細説明}

\brief は要約説明の始まりを, \detailsは詳細説明の始まりを示します。空行でパラグラフをはじめれば、\detailsは要りません。


\else

前の条件付きセクションが有効でなかった場合に 条件付きセクションを開始します。 前のセクションは、 \if, \ifnot, または \elseif コマンドで始まっていなければなりません。

参照:
\if, \ifnot, \elseif, \endif.

\elseif <セクションラベル>

前の条件付きセクションが有効でなかった場合に 条件付きドキュメント・セクションを開始します。 デフォルトで、条件付きセクションは無効になっています。 有効にするには、設定ファイルの中で ENABLED_SECTIONS タグの後に セクションラベルを置かなければなりません。 条件付きブロックはネストすることができます。 ネストされたセクションは、 その外側のセクションもすべて有効になっている場合に限り、 有効になります。

参照:
セクション \endif, \ifnot, \else, \elseif.

\endcond

\cond で始まる条件付セクションの終了を示します。

参照:
\cond.

\endif

\if または \ifnot で始まった条件付きセクションを終了させます。 各 \if または \ifnot に対して、唯一の \endif を対応させなければなりません。

参照:
\if, および \ifnot

\exception <例外オブジェクト> { 例外記述 }

<例外オブジェクト> という名の例外オブジェクトの例外記述を開始します。 後には、例外についての記述が続きます。 例外オブジェクトが存在するかどうかについては、チェックされません。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \exception コマンドが並ぶと、1つのパラグラフに結合されます。 各々の例外記述は、新しい行で始まります。 \exception コマンドは、空行または他のセクション導入コマンドで終了します。 例については、\fn を参照してください。

メモ:
\exceptions タグは、このタグの同義語です。

\if <セクションラベル>

条件付きドキュメント・セクションを開始します。 セクションは、対応する \endif コマンドで終了します。 デフォルトでは、条件付きセクションは無効です。 有効にするには、設定ファイルで、 ENABLED_SECTIONS タグの後に セクションラベルを置く必要があります。 条件付きブロックは、ネストすることができます。 ネストの内側のセクションが有効になるのは、 それを囲むすべてのセクションも有効な場合だけです。

例:
  /*! 無条件に表示されるドキュメント
   *  \if Cond1
   *    Cond1が設定されていれば含まれる
   *  \endif
   *  \if Cond2
   *    Cond2が設定されていれば含まれる
   *    \if Cond3
   *      Cond2,Cond3が設定されていれば含まれる
   *    \endif
   *    他のテキスト
   *  \endif
   *  無条件のテキスト
   */

条件付きコマンドをエイリアス内部で使うこともできます。 2つの言語でクラスにドキュメントを付けるには、たとえば、以下のように使います。

例 2:
/*! \english
 *  これは英語。
 *  \endenglish
 *  \dutch
 *  これはオランダ語。
 *  \enddutch
 */
class Example
{
};

ただし、設定ファイルで以下のようなエイリアスが定義されているものとします:

ALIASES  = "english=\if english" \
           "endenglish=\endif" \
           "dutch=\if dutch" \
           "enddutch=\endif"

そして、english または dutch のいずれかを有効にするために、 ENABLED_SECTIONS が使用されます。

参照:
セクション \endif, \ifnot, \else, and \elseif.

\ifnot <セクションラベル>

条件付きドキュメント・セクションを開始します。 セクションは、対応する \endif で終了します。 この条件付きセクションは、デフォルトで有効です。 無効にするには、設定ファイルで、 ENABLED_SECTIONS タグの後に セクションラベルを置く必要があります。

参照:
セクション \endif, \if, \else, および \elseif.

\invariant { 不変表明記述 }

実体についての不変表明を記述することのできるパラグラフを開始します。 パラグラフはインデントされます。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \invariant コマンドが並ぶと、1つのパラグラフに結合されます。 各々の不変表明は、新しい行で始まります。 1つの \invariant コマンドで複数の不変表明を記述することもできます。 \invariant コマンドは、空行または他のセクション導入コマンドで終了します。


\note { テキスト }

メモを記述するパラグラフを開始します。 パラグラフはインデントされます。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \note コマンドが並ぶと、1つのパラグラフに結合されます。 各々のメモは、新しい行で始まります。 1つの \note コマンドで複数のメモを記述することもできます。 \note コマンドは、空行または他のセクション導入コマンドで終了します。 例については、\par を参照してください。


\par [(パラグラフタイトル)] { パラグラフ }

パラグラフタイトルを指定すると、ユーザ定義の見出しを持つパラグラフを開始します。 見出しの範囲は、行の終わりまでです。 このコマンドに後続するパラグラフはインデントされます。

パラグラフタイトルがない場合、新しいパラグラフを開始します。 これは、他のパラグラフコマンド (\param や \warningなど) の内部でも機能します。その際、そのコマンドを終了させることはありません。

パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 \par コマンドは、空行または他のセクション導入コマンドで終了します。

例:
/*! \class Test
 * Normal text.
 *
 * \par User defined paragraph:
 * Contents of the paragraph.
 *
 * \par
 * New paragraph under the same heading.
 *
 * \note
 * This note consists of two paragraphs.
 * This is the first paragraph.
 *
 * \par
 * And this is the second paragraph.
 *
 * More normal text. 
 */
  
class Test {};
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

\param <引数名> { 引数説明 }

このコマンドは、<引数名> という名前の関数引数の始まりを示し、説明を記述します。 Doxygenは引数の存在をチェックします。引数の説明がなかったり関数の宣言・定義に 見つからない場合、警告を出します。

\param コマンドには、オプションの属性として、方向属性があります。 指定できる値は、"in" と "out" です。 以下は関数 memcpy の例です。

/*!
 Copies bytes from a source memory area to a destination memory area,
 where both areas may not overlap.
 @param[out] dest The memory area to copy to.
 @param[in]  src  The memory area to copy from.
 @param[in]  n    The number of bytes to copy
 */
void memcpy(void *dest, const void *src, size_t n);

引数が入力と出力の両方であれば、属性として [in,out] を使ってください。

パラメータの説明は特殊な内部構造のないパラグラフです。 視覚効果を高めるすべてのコマンドはパラグラフの中で使うことができます。

複数の \param コマンドが並ぶと、1つのパラグラフに結合されます。 各々の引数記述は、新しい行で始まります。 \param 記述は、空行他のセクション導入コマンドで終了します。 例については、\fn を参照してください。


\tparam <テンプレート引数名> { 説明 }

このコマンドは、クラスまたは関数の、<テンプレート引数名>という名のテンプレート引数の始まりを示し、引数の説明を記述します。

\cmdparamに似ています。


\post { 事後条件記述 }

実体についての事後条件を記述することのできるパラグラフを開始します。 パラグラフはインデントされます。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \post コマンドが並ぶと、1つのパラグラフに結合されます。 各々の事後条件は、新しい行で始まります。 1つの \post コマンドで複数の事後条件を記述することもできます。 \post コマンドは、空行または他のセクション導入コマンドで終了します。


\pre { 事前条件記述 }

要素の事前条件を記述することのできるパラグラフを開始します。 パラグラフはインデントされます。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \pre コマンドが並ぶと、1つのパラグラフに結合されます。 各々の事前条件は、新しい行で始まります。 1つの \pre コマンドで複数の事前条件を記述することもできます。 \pre コマンドは、空行または他のセクション導入コマンドで終了します。


\remarks { 注釈のテキスト }

1つ以上の注釈を記述するパラグラフを開始します。 パラグラフはインデントされます。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \remarks コマンドが並ぶと、1つのパラグラフに結合されます。 各々の注釈は、新しい行で始まります。 1つの \remarks コマンドで複数の注釈を記述することもできます。 \remarks コマンドは、空行または他のセクション導入コマンドで終了します。


\return { 戻り値の記述 }

関数の戻り値についての記述を開始します。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \return コマンドが並ぶと、1つのパラグラフに結合されます。 \returnコマンドは、空行または他のセクション導入コマンドで終了します。 例については、\fn を参照してください。


\retval <戻り値> { 記述 }

関数の戻り値で、<戻り値> という名前のものについての記述を開始します。 後には、戻り値についての記述が続きます。 記述を構成するパラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \retval コマンドが並ぶと、1つのパラグラフに結合されます。 各々の戻り値の記述は、新しい行で始まります。 \retval コマンドは、空行または他のセクション導入コマンドで終了します。


\sa { 参照先 }

クラス、関数、メソッド、変数、ファイルまたは URL へのクロスリファレンスを 指定するパラグラフを開始します。 2つの名前が :: または # で結合されていると、 クラスとそのメンバーを参照すると解釈されます。 メソッド名の後に、カッコで囲まれた引数型リストを付加することで、 オーバーロードされた複数のメソッドやコンストラクタの 1つを選択することができます。

同義語: \see

参照:
オブジェクトへのリンクをどのように生成するかということについては、 セクション autolink を参照

\see { 参照先 }

\sa と同じ。JavaDoc との互換性のために用意しています。


\since { テキスト }

このタグは、実体が利用可能になった時期 (バージョンや日時) を指定するのに使われます。 \since に続くパラグラフには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 \since コマンドは、空行または他のセクション導入コマンドで終了します。


\test { テストケースを記述するパラグラフ }

テストケースを記述できるパラグラフを開始します。 この記述により、テストケースは別のテストリストにも追加されます。 記述の2つのインスタンスは、クロスリファレンスされます。 テストリスト内の各テストケースには、そのテストケースの出自を示すヘッダーが付加されます。


\throw <例外オブジェクト> { 例外記述 }

同義語: \exception (セクション \exception を参照)

メモ:
\throws タグは、このタグの同義語です。

\todo { TODO を記述するパラグラフ }

TODO 項目を記述するパラグラフを開始します。 この記述により、別の TODO リストにも項目が追加されます。 記述の2つの例は、クロスリファレンスされます。 TODO リスト内の各項目には、その項目の出自を示すヘッダーが付加されます。


\version { バージョン番号 }

1つ以上のバージョン文字列を記述することのできるパラグラフを開始します。 パラグラフはインデントされます。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \version コマンドが並ぶと、1つのパラグラフに結合されます。 各々のバージョン記述は、新しい行で始まります。 1つの \version コマンドで複数のバージョン文字列を記述することもできます。 \version コマンドは、空行または他のセクション導入コマンドで終了します。 例については、\author を参照してください。


\warning { 警告メッセージ }

1つ以上の警告メッセージを記述することのできるパラグラフを開始します パラグラフはインデントされます。 パラグラフのテキストには、特別な内部構造はありません。 すべての視覚的強調コマンドが、パラグラフ内で使用可能です。 複数の \warning コマンドが並ぶと、1つのパラグラフに結合されます。 各々の警告記述は、新しい行で始まります。 1つの \warning コマンドで複数の警告を記述することもできます。 \warning コマンドは、空行または他のセクション導入コマンドで終了します。 例については、\author を参照してください。

\xrefitem <key> "(ヘディング)" "(リストタイトル)" {テキスト}

このコマンドは \todo\bugなどのコマンドの 一般化です。 このコマンドを使って、発生場所と生成される関連ページの間で自動的に 相互参照される、ユーザ定義のテキストを作れます。 関連ページでは、同種のセクションすべてが集められます。

最初の引数 <key> はセクションのタイプをユニークに代表するIDです。 第2引数は、セクションのヘディング(4つ目の引数に与えられるテキスト) を代表する引用文字列です。第3引数(リストタイトル)は、同じキーですべての 要素を内包する関連ページのタイトルとなります。キーには、"todo", "test", "bug", and "deprecated"が既に定義されています。

\xrefitem コマンドの使い方と効果を知るには、todoリストについて考えてみてください。 todoリストは、(英語の出力では)次のコマンドのエイリアスとなります。

各セクションについてコマンドの3引数を繰り返すと、とても冗長でエラーを 起こしやすくなるので、設定ファイルに ALIASES を指定して それとの組み合わせで使うようにしてください。 たとえば新しいコマンド\reminder を定義するには、設定ファイルに次の行を 追加してください。

ALIASES += "reminder=\xrefitem reminders \"Reminder\" \"Reminders\"" 

\xrefitem コマンドの第2,3引数にはエスケープ引用符を使います。


--- リンク生成コマンド ---

\addindex (テキスト)

このコマンドは、$\mbox{\LaTeX}$ インデックスに (テキスト) を追加します。


\anchor <単語>

このコマンドは、\ref コマンドで参照することができるドキュメントに 不可視な名前付きアンカーを埋め込みます。

覚え書き:
アンカーは今のところ、\pageによりページとして、 あるいは\mainpageによりメインページとしてマークされた コメントブロックにしか指定できません。
参照:
セクション \ref

\endlink

このコマンドは、\link コマンドによって開始されたリンクを終了させます。

参照:
セクション \link

\link <リンクオブジェクト>

doxygen によって自動的に生成されるリンクは、 それが指示しているオブジェクトの名前を、 リンクテキストとして、常に保持しています。

\link コマンドを使用すると、ユーザが指定したリンクテキストを持った、 (ファイル、クラス、メンバーなどの) オブジェクトへのリンクを生成することができます。 \link コマンドは、\endlink コマンドによって終了します。 \link と \endlink の間にあるすべてのテキストは、 \link の最初の引数で指定された <リンクオブジェクト> へのリンクについてのテキストとして扱われます。

自動的に生成されてリンクおよび妥当なリンクオブジェクトについて、 より詳しくは、セクション autolink を参照。


\ref <名前> ["(テキスト)"]

名前の付いたセクション、サブセクション、ページ、またはアンカーへの 参照を生成します。 HTML ドキュメントでは、参照コマンドはセクションへのリンクを生成します。 セクションやサブセクションに対しては、セクションのタイトルは、 リンクのテキストとして使用されます。 アンカーに対しては、グォートに囲まれたオプションのテキストか、 それが指定されていなければ、<名前> が使用されます。 $\mbox{\LaTeX}$ ドキュメントでは、参照コマンドは、 セクションに対してセクション番号を生成します。あるいは、 <名前> がアンカーを指示している場合には、 テキストとそれに後続するページ番号を生成します。

参照:
\ref コマンドの例については、セクション \page を参照

\subpage <名前> ["(テキスト)"]

このコマンドを使って、ページの階層を作ることができます。同じ構造が、 \defgroup\ingroupコマンドを 使って作れますが、ページには\subpage コマンドの方が便利なことが多いです。 メインページ(\mainpageを参照)は階層のルートです。

このコマンドは、\ref に似た振る舞いをします。 <名前>というラベルのページへのリファレンスができ、第2引数を指定すれば リンクテキストが付きます。

これは、ページだけに有効で、ページ間で親子関係を作るというところが \ref コマンドと違います。ここで子のページ(つまりサブページ)には<name> というラベルがつきます。

複数ページを作らずに構造を追加したいときは、 \section コマンドと \subsection コマンドを見てください。

覚え書き:
各ページは、1ページだけのサブページになりえます。また、連鎖はゆるされず、 階層は木構造になっていなければなりません。

例をあげます。

/*! \mainpage A simple manual

一般情報
  
このマニュアルは次のセクションに分かれています。
- \subpage intro 
- \subpage advanced "Advanced usage"
*/

//-----------------------------------------------------------

/*! \page intro 導入
このページは主題への導入です。
次に、\ref advanced "advanced section"へ進んでください。
*/

//-----------------------------------------------------------

/*! \page advanced Advanced Usage
このページは、上級者向けです。
最初に \ref intro "the introduction"を読んでください。
*/

\section <セクション名> (セクションタイトル)

<セクション名> という名前のセクションを生成します。 \section コマンドの第2引数として、 セクションのタイトルを指定する必要があります。

\警告 このコマンドは、関連するページドキュメントの内部でのみ機能します。 その他のドキュメントブロックでは機能しません


\subsection <サブセクション名> (サブセクションタイトル)

<サブセクション名> という名前のサブセクションを生成します。 \subsection コマンドの第2引数として、 サブセクションのタイトルを指定する必要があります。

\警告 このコマンドは、関連するページドキュメントの内部でのみ機能します。 その他のドキュメントブロックでは機能しません

参照:
\subsection コマンドの例については、 セクション \page を参照

\subsubsection <サブサブセクション名> (サブサブセクションタイトル)

<サブサブセクション名> という名前のサブサブセクションを生成します。 \subsection コマンドの第2引数として、 サブサブセクションのタイトルを指定する必要があります。

\警告 このコマンドは、関連するページドキュメントの内部でのみ機能します。 その他のドキュメントブロックでは機能しません

参照:
\subsubsection コマンドの例については、 セクション \page を参照

\paragraph <パラグラフ名> (パラグラフタイトル)

<パラグラフ名>という名のパラグラフを作ります。パラグラフのタイトルは、 第2引数に指定してください。

\警告 このコマンドは、関連ページのドキュメントブロックのサブセクション内で のみ有効で、他のドキュメントブロックでは無効です。

参照:
\paragraph コマンドの例は、 \pageのセクションを参照してください。

--- 実例を表示するためのコマンド ---

\dontinclude <ファイル名>

このコマンドは、ソースファイルを解析するのに使われます。 その際、(\include コマンドが行うように) ドキュメントにファイルを一字一句正確に取り込むようなことはしません。 これは、ソースファイルをいくつかの小部分に分割し、 それらの間にドキュメントを追加したいような場合に、役立ちます。 ソースファイルやディレクトリは、doxygen の設定ファイルで、 EXAMPLE_PATH タグを使うことによって指定できます。

コード断片内にあるクラスおよびメンバーの宣言・定義は、 \dontinclude コマンドを含んでいるコメントブロックの解析で取り出してきます。

ソースファイルの一行ごとの記述に対しては、 \line、\skip、\skipline および \until コマンドを使うことによって、 実例の1行またはそれ以上の行が表示されます。 これらのコマンドに対しては、内部的なポインタが使用されます。 \dontinclude コマンドは、実例の最初の行にポインタをセットします。

例:
/*! A test class. */

class Test
{
  public:
    /// a member function
    void example();
};

/*! \page example
 *  \dontinclude example_test.cpp
 *  Our main function starts like this:
 *  \skip main
 *  \until {
 *  First we create a object \c t of the Test class.
 *  \skipline Test
 *  Then we call the example member function 
 *  \line example
 *  After that our little test routine ends.
 *  \line }
 */
ここで、実例ファイル example_test.cpp の内容は、以下のようなものです:
void main()
{
  Test t;
  t.example();
}
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。
参照:
セクション \line\skip\skipline および \until

\include <ファイル名>

このコマンドを使うと、ソースファイルをコードの塊としてインクルードすることができます。 インクルードファイルの名前を引数にとります。 ソースファイルやディレクトリは、doxygen の設定ファイルで、 EXAMPLE_PATH タグを使うことによって指定できます。

EXAMPLE_PATH タグで指定された実例ファイルの集合に対して、 <ファイル名> だけでは一意にファイルを決定できない場合、 それを解決するために、絶対パスの一部を含めることができます。

\include コマンドを使用することは、ファイルをドキュメントブロックに挿入して、 それを \code\endcode コマンドで囲むことと 等価です。

\include コマンドの主な目的は、 実例ブロックが複数のソースおよびヘッダーファイルから構成されているような場合に、 コードの重複を避けることにあります。

ソースファイルの一行ごとの記述に対しては、 \line\skip\skipline、 および \until コマンドと共に、\dontinclude コマンドを使用します。

覚え書き:
Doxygenの特殊コマンドは、コードブロック内では働きません。 しかし、コードブロック内部にCスタイルのコメントをネストすることはできます。
参照:
セクション \example\dontinclude、および セクション \verbatim

\includelineno <ファイル名>

このコマンドは、\include と同様の働きをしますが、インクルードファイルに 行番号を追加します。

参照:
セクション \include.

\line ( パターン )

このコマンドは、\include または \dontinclude によって最後にインクルードされた実例を、 非空白行が見つかるまで、一行ずつ検索していきます。 見つかった行が指定のパターンを含んでいる場合、それは出力に書き出されます。

実例の中の現在行を追跡するのに使われる内部的なポインタは、 見つかった非空白行の次の行の先頭 (あるいは、そのような行が見つからない場合は、 実例の末尾) に設定されます。

例については、セクション \dontinclude を参照してください。


\skip ( パターン )

このコマンドは、\include または \dontinclude によって最後にインクルードされた実例を、 指定のパターンを含む行が見つかるまで、一行ずつ検索していきます。

実例の中の現在行を追跡するのに使われる内部的なポインタは、 指定パターンを含む行の先頭 (あるいは、パターンが見つからなかった場合は、 実例の末尾) に設定されます。

例については、セクション \dontinclude を参照してください。


\skipline ( パターン )

このコマンドは、\include または \dontinclude によって最後にインクルードされた実例を、 指定のパターンを含む行が見つかるまで、一行ずつ検索していきます。 見つかった行は、出力に書き出されます。

実例の中の現在行を追跡するのに使われる内部的なポインタは、 書き出された行の次の行の先頭 (あるいは、パターンが見つからなかった場合は、 実例の末尾) に設定されます。

注:
コマンド:
\skipline pattern
は、次のものと等価です:
\skip pattern
\line pattern

例については、セクション \dontinclude を参照してください。


\until ( パターン )

このコマンドは、指定のパターンを含む行が見つかるまで、 \include または \dontinclude によって最後にインクルードされた実例の 全ての行を出力に書き出します。パターンを含む行も書き出されます。

実例の中の現在行を追跡するのに使われる内部的なポインタは、 最後に書き出された行の次の行の先頭 (あるいは、パターンが見つからなかった場合は、 実例の末尾) に設定されます。

例については、セクション \dontinclude を参照してください。


\verbinclude <ファイル名>

このコマンドは、ファイル <ファイル名> の字句通りのコピーを、 ドキュメントに取り込みます。 このコマンドは、ファイルをドキュメントにペーストして、 \verbatim と \endverbatim コマンドで囲むことと等価です。

doxygen が検索の対象とするファイルやディレクトリは、 設定ファイルの EXAMPLE_PATH タグによって指定できます。


\htmlinclude <ファイル名>

このコマンドは、HTMLドキュメントの中になるように、 ファイル <ファイル名> を取り込みます。 このコマンドは、ファイルをドキュメントにペーストして、 \htmlonly と \endhtmlonly コマンドで囲むことと等価です。

doxygen が検索の対象とするファイルやディレクトリは、 設定ファイルの EXAMPLE_PATH タグによって指定できます。


--- 視覚的強調のためのコマンド ---

\a <単語>

特別なファントを使用して、引数 <単語> を表示します。 実行中のテキスト内のメンバー引数を参照するには、このコマンドを使用してください。

例:
  ... the \a x and \a y coordinates are used to ...
  
これは、次のテキストのような結果となります:

... the x and y coordinates are used to ...

\arg { 項目記述 }

このコマンドは、一つの引数を取ります。引数は、空行または別の \arg に 遭遇するまで続きます。 このコマンドを使用すると、単純でネストされない引数リストが生成できます。 各引数は、\arg コマンドで始まる必要があります。

例:
以下のようにタイブすると:
  \arg \c AlignLeft 左揃え
  \arg \c AlignCenter 中央揃え
  \arg \c AlignRight 右揃え
  
  他の揃え方はサポートしていません。
  
次のテキストのような結果となります:

  • AlignLeft 左揃え
  • AlignCenter 中央揃え
  • AlignRight 右揃え

他の揃え方はサポートしていません。
メモ:
ネストされたリストには、HTMLコマンドを使う必要があります。

\li に等価。


\b <単語>

ボールドフォントを使用して、引数 <語> を表示します。 <b>word</b> に等価。 複数単語をボールドにしたい場合は、<b>複数単語</b> とします。


\c <単語>

タイプライタフォントを使用して、引数 <単語> を表示します。 コードとなる語を参照するために使用します。 <tt>単語</tt> に等価。

例:
次のように入力すると:
     ... This function returns \c void and not \c int ...
  
次のような結果となります:

... This function returns void and not int ...

\p に等価。 複数単語をタイプライタフォントにしたい場合は、<tt>複数単語</tt> とします。


\code

コードブロックを開始します。 コードブロックは、通常のテキストとは区別して扱われ、 C/C++ のコードとして解釈されます。 ドキュメント化されるクラスとメンバーの名前は、 ドキュメントへのリンクで自動的に置換されます。

参照:
セクション \endcode、セクション \verbatim

\copydoc <link-object>

<link-object> で指定されたオブジェクトの説明ブロックをコピーして、コマンドの位置に貼り付けます。 このコマンドは、説明を手でコピーしたくない場合や、 継承したメンバーの説明を拡張するために使えます。

link-objectにはクラスやファイル、グループのメンバー、クラス、名前空間、 グループ、ページ、ファイルが指定でき、この順に優先されます。 関数、変数、typedefなどのメンバーや、それらを含むクラス、ファイル、グループにも、 当然説明がなければなりません。

たとえばクラスメンバーの説明をコピーするとき、次のように説明を入れることができます。

  /*! @copydoc MyClass::myfunction() 
   *  More documentation.
   */

メンバーがオーバーロードされているとき、下記のように引数の型も明示的に(空白なし) 指定してください。

  /*! @copydoc MyClass::myfunction(type1,type2) */

修飾名が必要かどうかは、説明ブロックが見つかった箇所の内容によります。

copydocコマンドは再帰的に使用できますが、copydoc関係で循環が行われるとエラーになります。

要約説明、詳細説明どちらもコピーされます。コメントブロックの中の要約か詳細か一方だけをコピーするには、\cmdcopybrief\cmdcopydetailsを見てください。


\copybrief <link-object>

このコマンドは、\copydoc に似ていますが、要約説明だけをコピーします。


\copydetails <link-object>

このコマンドは、\copydoc に似ていますが、詳細説明だけをコピーします。


\dot

dot グラフの有効な説明を含むテキスト要素の始まりを示します。 テキスト要素の終わりは、\enddotで示します。 Doxygen は、テキストをdot に渡し、その結果のイメージ (及びイメージマップ) を出力に含めます。 グラフのノードは、URL属性を使えばクリック可にできます。 URL値の中で\ref コマンドを使えば、doxygen内の要素にリンクできます。 例を示します。

/*! class B */
class B {};

/*! class C */
class C {};

/*! \mainpage

  インラインのdotグラフを使って表現されたクラス関係
  \dot
  digraph example {
      node [shape=record, fontname=Helvetica, fontsize=10];
      b [ label="class B" URL="\ref B"];
      c [ label="class C" URL="\ref C"];
      b -> c [ arrowhead="open", style="dashed" ];
  }
  \enddot
  上のグラフに表示されているクラスはクリックできる(HTML出力で) 
 */

\msc

このコマンドは、メッセージシーケンス図についての有効な説明を含むテキスト要素の始まりを示します。 http://www.mcternan.me.uk/mscgen/ で例を見てください。 テキスト要素の終わりは、\endmscで示します。

覚え書き:
テキスト要素に含めることができるのは、msc {...}の形の中にある、メッセージシーケンス図の要素だけです。
このコマンドを使うには、mscgenツールのインストールが必要です。

\mscコマンドの使用例です。

/** 送信側クラス。サーバーにコマンドを送る。
  受信側は、Ack()をコールしてコマンドを承認する。
  \msc
    Sender,Receiver;
    Sender->Receiver [label="Command()", URL="\ref Receiver::Command()"];
    Sender<-Receiver [label="Ack()", URL="\ref Ack()", ID="1"];
  \endmsc
 */
class Sender
{
  public:
    /** サーバーからの承認 */
    void Ack(bool ok);
};

/** 受信側クラス。コマンドを受信して実行する。
  コマンド実行の後、受信側は承認を送信する。
  \msc
    Receiver,Sender;
    Receiver<-Sender [label="Command()", URL="\ref Command()"];
    Receiver->Sender [label="Ack()", URL="\ref Sender::Ack()", ID="1"];
  \endmsc
 */
class Receiver
{
  public:
    /** サーバーでコマンドを実行 */
    void Command(int commandId);
};

\dotfile <ファイル> ["キャプション"]

<ファイル> から dot によって生成された画像を、ドキュメントに挿入します。

最初の引数は画像のファイル名を指定します。 doxygen は、そのファイルを、DOTFILE_DIRS タグで指定されたパス (またはファイル) の中から探します。 dot ファイルが見つかった場合、それは dot ツールへの入力ファイルとして扱われます。 出来上がった画像は正しい出力ディレクトリに出力されます。 dot ファイル名が空白文字を含む場合は、ファイル名をクォート () で囲まなければなりません。

2番目の引数はオプショナルですが、これを使用して画像の下に表示される キャプションを指定することができます。 この引数は、たとえ空白文字を含んでいなくてもクォートで囲んで記述する 必要があります。クォートはキャプションが表示されるときに除去されます。


\e <単語>

引数 <単語> をイタリック体で表示します。 このコマンドは、語を強調するために使います。

例:
以下のようにタイプすると:
  ... this is a \e really good example ... 
  
次のテキストのような結果となります:

... this is a really good example ...

\em に等価。 複数の単語を強調するには、<em>multiple words</em>のように使ってください。


\em <単語>

引数 <単語> をイタリック体で表示します。 このコマンドは、語を強調するために使います。

例:
以下のようにタイプすると:
  ... this is a \em really good example ... 
  
次のテキストのような結果となります:

... this is a really good example ...

\e に等価。


\endcode

コードブロックを終了します。

参照:
セクション \code

\enddot

\dotで始まったブロックを終了します。


\endmsc

このコマンドは、\mscで始まるブロックの終わりを示します。


\endhtmlonly

\htmlonly コマンドで始まったテキストブロックを終了します。

参照:
セクション \htmlonly

\endlatexonly

\latexonly コマンドで始まったテキストブロックを終了します。

参照:
セクション \latexonly

\endmanonly

\manonly コマンドで始まったテキストブロックを終了します。

参照:
セクション \manonly.

\endverbatim

\verbatim コマンドで始まったテキストブロックを終了します。

参照:
セクション \endcode\verbatim

\endxmlonly

\xmlonly コマンドで始まったテキストブロックを終了します。

参照:
セクション \xmlonly.

\f$

テキスト内の式の開始と終了をマークします。

参照:
例については、セクション formulas

\f[

別の行に中央揃えで表示される、長い式の開始をマークします。

参照:
セクション \f] および、セクション formulas

\f]

別の行に中央揃えで表示される、長い式の終了をマークします。

参照:
セクション \f[ および、セクション formulas

\f{環境}{

このコマンドは、特定の環境で使う公式の始まりを示します。

覚え書き:
2番目の はオプションで、Vimなどのエディターでハイライトができるように括弧の数を合わせているだけです。

\f}

このコマンドは、特定の環境で使う公式の終わりを示します。


\htmlonly

生成された HTML ドキュメントにのみ、字句通りにインクルードされるテキストブロックを開始します。 ブロックは、\endhtmlonly コマンドで終了します。

このコマンドは、doxygen にとっては複雑すぎる HTML コード (すなわち、アプレット、Javaスクリプト、属性を必要とする HTML タグ) をインクルードするために使用することができます。 適切な $\mbox{\LaTeX}$ という代替物を提供するために、 \latexonly と \endlatexonly のペアを使うことができます。

: ($(HOME) のような) 環境変数は、HTML-only なブロックの内部で解釈されます。

参照:
セクション \manonly および、 セクション \latexonly

\image <format> <file> ["caption"] [<sizeindication>=<size>]

ドキュメントに画像を挿入します。 このコマンドはフォーマットを特定します。 したがって、一つの画像を 2つ以上のフォーマットで挿入したい場合は、 各フォーマットごとにこのコマンドを繰り返さなければなりません。

最初の引数で、出力フォーマットを指定します。 現在のところ、以下の値がサポートされています: html および latex。

2番目の引数で、画像のファイル名を指定します。 doxygen は、IMAGE_PATH タグの後に指定したパス (またはファイル) の中から、ファイルを探し出します。 画像が見つかると、それは、現在の出力ディレクトリにコピーされます。 画像名が空白文字を含んでいる場合は、クォート () で囲む必要があります。 ファイル名のかわりに絶対 URL を指定することもできます。しかし、その場合、 doxygen は、画像のコピーも存在チェックもしません。

3番目の引数はオプションです。これを使うと、 画像の下に表示されるキャプションを指定することができます。 この引数は、1行に記述し、かつ空白文字を全く含まない場合であっても、 クォートで囲まなければなりません。 クォートは、キャプションが表示される前に取り除かれます。

4番目の引数もオプションです。これを使うと、 画像の幅や高さを指定することができます。 これは、$\mbox{\LaTeX}$ 出力 (すなわち、フォーマット=latex) に対してのみ、有用です。 サイズ指示 は、width または height のいずれかです。 サイズは、$\mbox{\LaTeX}$ において有効なサイズ指定である必要があります (たとえば、10cm6in\textwidth のようなシンボリックな幅指定)。

下は、コメント・ブロックの例です:

  /*! 私のアプリケーションのスナップショット
   *  \image html application.jpg
   *  \image latex application.eps "私のアプリケーション" width=10cm
   */

また、下は、設定ファイルの関連部分の例です:

  IMAGE_PATH     = my_image_dir

\警告 HTML に対する画像フォーマットは、 ユーザが使用しているブラウザがサポートしているものに制限されます。 $\mbox{\LaTeX}$ については、画像フォーマットは、 Encapsulated PostScript (eps) でなければなりません。

doxygen は、画像が正しいフォーマットであるかどうかチェックしません。 したがって、それが正しいということは、ユーザが確認しなければなりません!


\latexonly

生成された $\mbox{\LaTeX}$ ドキュメントにのみ、 字句通りにインクルードされるテキストブロックを開始します。 ブロックは、\endlatexonly コマンドで終了します。

このコマンドは、doxygen にとっては複雑すぎる $\mbox{\LaTeX}$ コード (すなわち、画像、式、特殊文字) をインクルードするために使用することができます。 適切な HTML という代替物を提供するために、 \htmlonly と \endhtmlonly のペアを使うことができます。

: ($(HOME) のような) 環境変数は、$\mbox{\LaTeX}$-only なブロックの内部で解釈されます。

参照:
セクション \latexonly および セクション \htmlonly

\manonly

テキストブロックの始まりを示し、MAN ドキュメントだけに そのまま出力されます。ブロックは、endmanonly コマンドで終わります。

このコマンドは、MAN ページに直接 groff コードを含めるのに使えます。 \htmlonly, \latexonly, \endhtmlonly, \endlatexonly を組み合わせれば、 HTML と $\mbox{\LaTeX}$ の適切な代理となりえます。

参照:
セクション \htmlonly とセクション \latexonly.

\li { 項目記述 }

このコマンドは、一つの引数を取ります。引数は、空行または別の \li に 遭遇するまで続きます。 このコマンドを使用すると、単純でネストされない引数リストが生成できます。 各引数は、\li コマンドで始まる必要があります。

例:
以下のようにタイブすると:
  \li \c AlignLeft 左揃え
  \li \c AlignCenter 中央揃え
  \li \c AlignRight 右揃え
  
  他の揃え方はサポートしていません。
  
次のテキストのような結果となります:

  • AlignLeft 左揃え
  • AlignCenter 中央揃え
  • AlignRight 右揃え

他の揃え方はサポートしていません。
注:
ネストされたリストには、HTMLコマンドを使う必要があります。

\arg に等価。


\n

強制的に改行します。<br> と等価です。


\p <単語>

タイプライタフォントを使用して、引数 <語> を表示します。 このコマンドを使用すると、 実行中のテキスト内のメンバー関数の引数を参照することができます。

例:
  ... the \p x and \p y coordinates are used to ...
  
これは、次のテキストのような結果となります:

... the x and y coordinates are used to ...

\c に等価。


\verbatim

HTML および $\mbox{\LaTeX}$ の両方のドキュメントに、 字句通りにインクルードされるテキストブロックを開始します。 ブロックは、\endverbatim コマンドで終了する必要があります。 verbatim ブロック内では、すべてのコマンドが無効となります。

警告: 各 \verbatim コマンドに対して、 確実に \endverbatim コマンドを付けてください。 さもないと、doxygen は解析で混乱してしまいます!

参照:
セクション \code, セクション \verbinclude

\xmlonly

XMLブロックの始まりを示し、XML出力だけにそのまま出力されます。 ブロックは、\endxmlonlyコマンドで終了します。

このコマンドはカスタムXMLタグを含むことができます。

参照:
セクション \htmlonly とセクション \latexonly.

\\

このコマンドは、HTML および $\mbox{\LaTeX}$ 出力に、 バックスラッシュ文字 (\) を書き出します。 doxygen は、バックスラッシュによってコマンドを検出するので、 バックスラッシュをエスケープしなければならない場合があります。


\@

このコマンドは、HTML および $\mbox{\LaTeX}$ 出力に、 アットマーク (\@) を書き出します。 doxygen は、アットマークによって JavaDoc コマンドを検出するので、 アットマークをエスケープしなければならない場合があります。


\~[LanguageId]

このコマンドは 言語特定フィルタの有効無効を指定します。 これを使えば、1コメントブロック中に違う言語での解説を入れて、 特定の言語をOUTPUT_LANGUAGE タグで除去するときに使えます。 特定の言語の出力だけをさせるには を使います。

例:

/*! \~english This is english \~dutch Dit is Nederlands \~german Dieses ist
    deutsch. \~ output for all languages.
 */

\&

このコマンドは、& 文字を書き出します。 この文字は、HTML において特別な意味を持つのでエスケープする必要があります。


\$

このコマンドは、$ 文字を書き出します。 この文字は、環境変数を展開するのに使うので、エスケープの必要な場合があります。


\#

このコマンドは、# 文字を書き出します。 この文字は、解説付きの要素を参照するのに使うので、エスケープの必要な場合があります。


\<

このコマンドは、< 文字を書き出します。 この文字は、HTML で特別な意味を持つのでエスケープが必要です。


\>

このコマンドは、> 文字を書き出します。 この文字は、HTML で特別な意味を持つのでエスケープが必要です。

\%

このコマンドは、% 文字を書き出します。 この文字は、解説付きのクラスや構造体でもあるワードへの自動リンクを避けるのに 使うので、エスケープの必要な場合があります。

--- Qt との互換性のために存在するコマンド ---


以下のコマンドは、 Qt クラスブラウザジェネレータとの互換性を維持するためにサポートされています。 これらのコマンドをユーザ自身のドキュメントでは使わないでください。

  • \annotatedclasslist
  • \classhierarchy
  • \define
  • \functionindex
  • \header
  • \headerfilelist
  • \inherit
  • \l
  • \postheader

のセクションに行く / インデックス に戻る

This page was last modified on 14 Feb 2011.
© 1997-2010 Dimitri van Heesch, first release 27 oct 1997.
© 2001 OKA Toshiyuki (Japanese translation).
© 2006-2011 TSUJI Takahiro (Japanese translation).
© 2006-2011 TAKAGI Nobuhisa (Japanese translation).