Doxygen latest release v1.8.3.1 - last update Sat Aug 24 2014

コードのドキュメント付け

この章では、2つのテーマを取り上げます。

  1. doxygen が生成するドキュメントにコメントを合体させるために、ソースコード上にコメントをどのように書くか。 次節 で細かく説明しています。
  2. コメントブロックの解剖 セクションで説明しているように、出力の見え方を良くするためにコメントブロックの内容を構造化する方法

特殊なコメントブロック

特殊コメントブロックは、C または C++スタイルのコメントブロックにマークを付け加えたもので、Doxygenはこれを構造化されたテキスト断片と認識して、ドキュメントを生成します。 セクションでは、doxygenがサポートするさまざまなスタイルを示します。

Python,VHDL,Fortran,Tcl コードについては、別のコメント表記規則があります。セクションPython でのコメント・ブロック, VHDL でのコメント・ブロック, Fortranでのコメント・ブロック, Tclでのコメントブロック で説明します。

C系統の言語のコメントブロック (C/C++/C#/Objective-C/PHP/Java)

各コード要素について、説明形式が2(3の場合も)種類あり、これらが該当要素のドキュメントを形成します。それは、要約説明詳細説明 で、どちらもオプションです。メソッドと関数については、もうひとつの形式があり、いわゆる"本文内"説明で、メソッドや関数の本体内のコメントブロックの連結からなります。

ひとつ以上の要約説明または詳細説明を指定できます。(ただし、出現順序が指定されていないためお勧めできません。)

名前からわかるように、要約説明は短い一行ですが、詳細説明はより長く、より詳しいドキュメントを提供します。"本文内"説明も詳細説明となりますが、こちらは実装の詳細をまとまって説明することができます。HTML出力の場合、要素が参照されている箇所で要約説明を使えばツールチップを提供できます。

コメント・ブロックに詳細説明のマークを付ける方法を示します。

  1. 2つの * で始まる C スタイルのコメント・ブロックからなる、JavaDoc スタイルを使うことができます。

    /**
     * ... text ...
     */
    

  2. または、Qt スタイルを使うことができ、この例が示すように、C スタイルのコメント・ブロックが開いた直後に感嘆符 (!) を追加します。

    /*!
     * ... text ...
     */
    

    どちらの場合でも、間にある * はオプションですので、

    /*!
     ... text ...
    */
    

    もまた使えます。

  3. 3番目の選択肢は、ぞれぞれの行が追加のスラッシュまたは感嘆符で始まる最低 2行のC++ コメント行からなるブロックを使うものです。 以下に 2種類の例があります:

    ///
    /// ... text ...
    ///
    

    または

    //!
    //!... text ...
    //!
    

    この場合、空行でドキュメンテーションブロックが終わっています。

  4. 人によっては、ドキュメントの中でコメント・ブロックをより目立たせることを好みます。 これは、次のようにします。

    /********************************************//**
     *  ... text
     ***********************************************/
    

    (通常のコメントブロックを終わって特殊コメントブロックをはじめるにはスラッシュを2つ入れます)

    または、次のようにします。

    /////////////////////////////////////////////////
    /// ... text ...
    /////////////////////////////////////////////////
    

要約説明にも、いくつかのやり方があります。

  1. 上記のコメント・ブロックのうちの 1つとともに、 \brief コマンドを使うことができます。 このコマンドはパラグラフの最後で終わります。 従って、詳細説明は空行の後に続きます。

    以下に例を挙げます。

    /*! \brief 要約説明.
     *         要約説明の続き.
     *
     *  詳細説明がここから始まる.
     */
    

  2. JAVADOC_AUTOBRIEF が設定ファイルで YESであれば、JavaDoc スタイルのコメント・ブロックを使うことで、要約説明が自動的に始められます。この要約説明は、スペースまたは改行が続く最初のドットで終わります。以下に例を挙げます。

    /** このドットで終わる要約説明. 詳細説明が
     *  続く.
     */
    

    別の選択肢として、複数行の特殊な C++ コメントでも同じ効果があります。

    /// このドットで終わる要約説明. 詳細説明が
    /// 続く.
    

  3. 3つ目の選択肢では、複数行にまたがらない特殊な C++ スタイルのコメントを使います。以下に 2つの例を示します。

    /// 要約説明.
    /** 詳細説明. */
    

    または

    //! 要約説明
    
    //! 詳細説明 
    //! はここから
    

    後者の空行は、詳細説明を含むブロックから要約説明を分離するために必要です。 このケースでは、JAVADOC_AUTOBRIEFNO に設定してください。

このように、Doxygenの自由度は高いです。詳細説明が次のように複数あったら

//! 要約説明でも、
//! 複数行にわたれば実際は詳細説明
/*! お、また別の詳細説明だ!
 */

これらは一緒になります。コードの中で説明が散らばっていることもありますが同じです。その場合、順序はDoxygenのコード解析の順序に依存します。

他の多くのドキュメンテーションシステムとは違い、doxygenでは、メンバー(グローバル関数を含む)のドキュメントを、定義 の前に置くことができます。この方法を使うと、ドキュメントがヘッダファイルでなく、ソースファイルに置けます。これによりヘッダファイルはコンパクトなままにでき、メンバーの作成者が直接ドキュメントにアクセスできます。妥協案として、要約説明を宣言の前に、詳細説明をメンバー定義の前に置くことができます。

メンバーの後ろにドキュメントを置く

ファイル、構造体、共用体、クラス、enumのメンバーにドキュメントをつけたい場合、メンバーの前でなく後ろにドキュメントブロックを置くほうが望ましい場合があります。そのためには、< マーカーをコメントブロックにつける必要があります。これは、関数の引数にも応用できます。

いくつか例を挙げます。

int var; /*!< メンバーの後ろの詳細説明 */

このブロックは、Qtスタイルの詳細ドキュメントブロックをメンバーの 後ろ に置く場合に使えます。同じことを他の方法ですると、

int var; /**< メンバーの後ろの詳細説明 */

または

int var; //!< メンバーの後ろの詳細説明
         //!< 

または

int var; ///< メンバーの後ろの詳細説明
         ///< 

メンバーの後ろに要約説明を置きたいこともよくあります。 これは次のようにします。

int var; //!< メンバーの後ろの要約説明

または

int var; ///< メンバーの後ろの要約説明

関数に対しては、@param コマンドを使って、引数のドキュメントを書けます。方向を示すには、[in], [out], [in,out] を使います。 インラインドキュメントの場合、次のように方向属性から始めてもかまいません。

void foo(int v /**< [in] 入力引数vのドキュメント */);

これらのブロックは、前のセクションの特殊コメントブロックと同じ構造と意味を持っています。< だけが、メンバーがブロックの後ろでなく前にあることを示しています。

これらのコメントブロックの使用例を示します。

/*! A test class */
class Test
{
public:
/** An enum type.
* The documentation block cannot be put after the enum!
*/
enum EnumType
{
int EVal1, /**< enum value 1 */
int EVal2 /**< enum value 2 */
};
void member(); //!< a member function.
protected:
int value; /*!< an integer value */
};
ここをクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。
警告
これらのブロックは、メンバーや 引数 にドキュメントをつけるためにしか使えません。 ファイルや、クラス、共用体、構造体、グループ、ネームスペース、enum などには使えません。更に、次のセクションで取り上げている構造化コマンド(\classなど)をこれらコメントブロック内で使うことは許されていません。

以下は、Qt スタイルを使った C++ コードのドキュメント付けされた断片の例です。

//! A test class.
/*!
A more elaborate class description.
*/
class Test
{
public:
//! An enum.
/*! More detailed enum description. */
enum TEnum {
TVal1, /*!< Enum value TVal1. */
TVal2, /*!< Enum value TVal2. */
TVal3 /*!< Enum value TVal3. */
}
//! Enum pointer.
/*! Details. */
*enumPtr,
//! Enum variable.
/*! Details. */
enumVar;
//! A constructor.
/*!
A more elaborate description of the constructor.
*/
Test();
//! A destructor.
/*!
A more elaborate description of the destructor.
*/
~Test();
//! A normal member taking two arguments and returning an integer value.
/*!
\param a an integer argument.
\param s a constant character pointer.
\return The test results
\sa Test(), ~Test(), testMeToo() and publicVar()
*/
int testMe(int a,const char *s);
//! A pure virtual member.
/*!
\sa testMe()
\param c1 the first argument.
\param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
//! A public variable.
/*!
Details.
*/
int publicVar;
//! A function variable.
/*!
Details.
*/
int (*handler)(int a,int b);
};
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

要約説明は、クラスや名前空間、ファイルに属するメンバー総覧で使用され、小さな斜体のフォントで表示されます(この説明は、設定ファイルで、BRIEF_MEMBER_DESCNO に設定すると表示されなくなります)。 デフォルトでは、要約説明は、詳細説明の最初の文になります(しかし、これは REPEAT_BRIEF タグを NO に設定することで変えることができます)。Qt スタイルでは、要約説明と詳細説明の両方ともがオプションです。

JavaDoc スタイルのドキュメント・ブロックは、デフォルトでは、Qt スタイルのドキュメントブロックと同じように振る舞います。 しかしながら、これは、JavaDoc の仕様に合致していません。 JavaDoc では、ドキュメントブロックの最初のセンテンスは、自動的に要約説明として扱われます。 要約説明として機能させるには、設定ファイルで、JAVADOC_AUTOBRIEFYES に設定する必要があります。 このオプションを有効にした上で、文を終わらせずに、その途中にドットを置きたい場合は、ドットの後にバックスラッシュと空白を入れる必要があります。

  /** 詳細説明 (例.\ 語は少しだけ). 詳細が続く. */

次の例は上に示したものと同じコードですが、今度は、JavaDoc スタイルで、JAVADOC_AUTOBRIEFYES に設定したものです。

/**
* A test class. A more elaborate class description.
*/
class Test
{
public:
/**
* An enum.
* More detailed enum description.
*/
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
*enumPtr, /**< enum pointer. Details. */
enumVar; /**< enum variable. Details. */
/**
* A constructor.
* A more elaborate description of the constructor.
*/
Test();
/**
* A destructor.
* A more elaborate description of the destructor.
*/
~Test();
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
/**
* A pure virtual member.
* @see testMe()
* @param c1 the first argument.
* @param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
/**
* a public variable.
* Details.
*/
int publicVar;
/**
* a function variable.
* Details.
*/
int (*handler)(int a,int b);
};
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

同様に、Qtスタイルのドキュメントブロックの最初のセンテンスを自動的に要約説明として扱うには、設定ファイルで QT_AUTOBRIEF をYESに設定します。

他の場所のドキュメント

ここまでは、ドキュメント・ブロックは常にファイル、クラス、名前空間の宣言または定義の 前に 、あるいはメンバーの 前後 にあるものとしていました。

この方が都合の良いことが多いのですが、他の場所にドキュメントを置きたいといったこともありえます。ファイルの場合、"ファイルの前に"というわけにはいかないので、この方法をとります。

Doxygen では、実際他の場所にドキュメント・ブロックを置けます。(例外:関数の本体内部、普通のCスタイルコメントブロック内部)

ドキュメント・ブロックを要素のすぐ前後に置かない場合には、構造化コマンドをドキュメント・ブロック内部に指定する必要があります。 この場合、情報が二重定義になりかねません。ですので、実際には他の理由で仕方 ない限り は、構造化コマンドの使用は 避けたい ところです。

構造化コマンドは (特殊コマンドと同様) バックスラッシュ (\) か、 JavaDocスタイルならアットマーク (@) で始まり、コマンド名とひとつ以上のパラメータを続けます。 たとえば、上の例で Test クラスにドキュメント付けしたいとすると、次のようなドキュメント・ブロックをdoxygenが読み込む入力のどこかに置くことも可能です。

/*! \class Test
    \brief test クラス

    クラスの詳細説明
*/

ここで特殊コマンド \class は、コメントブロックにクラス Test のドキュメントが含まれることを示します。 他の構造化コマンドを以下に示します。

  • \struct は C の構造体にドキュメントを付けます。
  • \union は共用体にドキュメントを付けます。
  • \enum は列挙型にドキュメントを付けます。
  • \fn は関数にドキュメントを付けます。
  • \var は変数または typedef または列挙定数にドキュメントを付けます。
  • \def は #define にドキュメントを付けます。
  • \typedef は型定義にドキュメントを付けます。
  • \file はファイルにドキュメントを付けます。
  • \namespace はネームスペースにドキュメントを付けます。
  • \package は Java のパッケージにドキュメントを付けます。
  • \interface は IDL のインタフェースにドキュメントを付けます。

これら多くのコマンドについての詳しい情報は、特殊コマンドをご覧ください。

C++ クラスのメンバーをドキュメント付けするには、クラス自体もドキュメント付けする必要があります。 名前空間にも同じことが言えます。グローバルな C 関数、型定義、列挙、プリプロセッサ定義をドキュメント付けするには、これらを内包するファイルをドキュメント付けする必要があります (普通は、ヘッダファイルが他のソースファイルに外部化する情報を内包するので、 ヘッダファイルです)。

よく見過ごされるので再度説明します。 グローバルオブジェクト (関数、型定義、列挙型、マクロなど) をドキュメント付けするには、 これらが定義されたファイルをドキュメント付けすることが 必須 です。 つまり、ファイルには、

/*! \file */ 

/** @file */ 

の行が 必須です。

構造化コマンドを使ってドキュメント付けされた structcmd.h という C ヘッダファイルを 例に挙げます。

/*! \file structcmd.h
\brief A Documented file.
Details.
*/
/*! \def MAX(a,b)
\brief A macro that returns the maximum of \a a and \a b.
Details.
*/
/*! \var typedef unsigned int UINT32
\brief A type definition for a .
Details.
*/
/*! \var int errno
\brief Contains the last error code.
\warning Not thread safe!
*/
/*! \fn int open(const char *pathname,int flags)
\brief Opens a file descriptor.
\param pathname The name of the descriptor.
\param flags Opening flags.
*/
/*! \fn int close(int fd)
\brief Closes the file descriptor \a fd.
\param fd The descriptor to close.
*/
/*! \fn size_t write(int fd,const char *buf, size_t count)
\brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
\param fd The descriptor to write to.
\param buf The data buffer to write.
\param count The number of bytes to write.
*/
/*! \fn int read(int fd,char *buf,size_t count)
\brief Read bytes from a file descriptor.
\param fd The descriptor to read from.
\param buf The buffer to read into.
\param count The number of bytes to read.
*/
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

このファイルの中のコメントブロックそれぞれに、構造化コマンドが含まれているため、 コメントブロックはすべて、生成されるドキュメントには影響を及ぼさずに、他の場所や 入力ファイル (たとえばソースファイル) に移動できます。 ただし、この方法ではプロトタイプが二重となるため、変更はすべて2回しなければならない という欠点があります。このため、先ずは本当に必要か考え、できれば構造化コマンドは避けた ほうがいいでしょう。関数の前に置かれたコメントブロックに \fn コマンドがある例をときどき 見かけます。\fn コマンドは冗長なので、問題が起こるのは明らかです。

Python でのコメント・ブロック

Python では、コードをドキュメント付けするのにいわゆるドキュメント文字列を使用する方法が標準化されています。この文字列は、doc (docstring) という形で保存され、実行時に引き出されます。 Doxygenではこれらコメントを抽出し、前整形して提示するものと解釈します。

1 """@package docstring
2 Documentation for this module.
3 
4 More details.
5 """
6 
7 def func():
8  """Documentation for a function.
9 
10  More details.
11  """
12  pass
13 
14 class PyClass:
15  """Documentation for a class.
16 
17  More details.
18  """
19 
20  def __init__(self):
21  """The constructor."""
22  self._memVar = 0;
23 
24  def PyMethod(self):
25  """Documentation for a method."""
26  pass
27 
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

このケースでは、doxygen の特殊コマンドはどれもサポートされないことに 注意してください。
他に、"##" で始まるコメントを使って Python コードをドキュメント付けする方法もあります。 この種のコメントブロックなら、doxygen がサポートする他の言語でドキュメント・ブロックが働くのと同じような役割をするので、特殊コマンドの使用もできます。

以下は、再度同じ例ですが、今度は doxygen スタイルのコメントを使っています。

1 ## @package pyexample
2 # Documentation for this module.
3 #
4 # More details.
5 
6 ## Documentation for a function.
7 #
8 # More details.
9 def func():
10  pass
11 
12 ## Documentation for a class.
13 #
14 # More details.
15 class PyClass:
16 
17  ## The constructor.
18  def __init__(self):
19  self._memVar = 0;
20 
21  ## Documentation for a method.
22  # @param self The object pointer.
23  def PyMethod(self):
24  pass
25 
26  ## A class variable.
27  classVar = 0;
28 
29  ## @var _memVar
30  # a member variable
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

Python は、見た目が C や C++ よりJava に似ているので、設定ファイルでは OPTMIZE_OUTPUT_JAVAYES に設定してください。

VHDL でのコメント・ブロック

VHDLのコメントは普通 "&ndash;"で始まります。Doxygenは"&ndash;!"で始まるコメントを抽出します。VHDLには次の2種類のコメントブロックしかありません。一行の –! コメントは要約説明を、複数の –! コメント(–! が各行で前置きされます)は詳細説明を表します。

コメントは常に、ドキュメントつき要素の前に配置されます。例外として、ポートではコメントは要素の後ろにも置くことが可能で、ポートの要約説明として扱います。

DoxygenコメントのついたVHDLファイルを示します。

1 -------------------------------------------------------
2 --! @file
3 --! @brief 2:1 Mux using with-select
4 -------------------------------------------------------
5 
6 --! Use standard library
7 library ieee;
8 --! Use logic elements
9  use ieee.std_logic_1164.all;
10 
11 --! Mux entity brief description
12 
13 --! Detailed description of this
14 --! mux design element.
15 entity mux_using_with is
16  port (
17  din_0 : in std_logic; --! Mux first input
18  din_1 : in std_logic; --! Mux Second input
19  sel : in std_logic; --! Select input
20  mux_out : out std_logic --! Mux output
21  );
22 end entity;
23 
24 --! @brief Architure definition of the MUX
25 --! @details More details about this mux element.
26 architecture behavior of mux_using_with is
27 begin
28  with (sel) select
29  mux_out <= din_0 when '0',
30  din_1 when others;
31 end architecture;
32 
ここをクリックすると、Doxygenが生成したHTMLドキュメントが表示されます。

見栄えのいい出力を得るには、設定ファイルで OPTIMIZE_OUTPUT_VHDLYES にする必要があります。これは、他の多くの設定にも影響します。これらが正しく設定されていないと、Doxygenはどの設定が間違っているか警告します。

Fortranでのコメント・ブロック

Fortranコードにdoxygenを使うときは、OPTIMIZE_FOR_FORTRANをYESに設定してください。

Fortranでは、"!>"、"!<"はコメントの始まりで、複数行に分けるには、"!!"、"!>"を使います。

次は、ドキュメントつきFortranサブルーチンの例です。

  !> 集合のために制約配列を
  !! 構築する
  !! @param aggr 集合についての情報
  !! @todo 特殊ケースを扱う
  subroutine IntRestBuild(A,aggr,Restrict,A_ghost)
    implicit none
    Type(SpMtx), intent(in) :: A !< 配列
    Type(Aggrs), intent(in) :: aggr
    Type(SpMtx), intent(out) :: Restrict !< 制約配列

あるいは、定型コードでコメントを使うこともできます。

C> 関数コメント
C> 次のコメント行
      function A(i)
C> 入力引数
        integer i
      end function A

Tclでのコメントブロック

通常のTclコメント内にdoxygenドキュメントを含めることができます。

新しいドキュメントブロックを始めるには、## で行を始めます。 続くコメント行と継続行は、このブロックに追加されます。ブロックの終端は、# で始まらない行です。

要約説明は、;#< マークで追加できます。これの終端も、# で始まらない行です。

doxygenのコメントブロック内部では、通常のdoxygenマーキングならすべてサポートされます。例外は、次の2つの段落で述べます。

doxygen コメントブロックが #\code#@code しかない行で終わる場合、#\endcode#@endcode しかない行までのすべてのコードは、コードブロックとして生成するドキュメントに追加されます。

doxygen コメントブロックが #\verbatim#@verbatim しかない行で終わる場合、#\endverbatim#@endverbatim しかない行までのすべてのコードは、そのまま生成するドキュメントに追加されます。

名前空間、クラス、関数や変数を認識させるには、次のTclコマンドを使えます。コマンドの前の行にドキュメントブロックを配置できます。

  • namespace eval .. 名前空間
  • proc .. 関数
  • variable .. 変数
  • common .. 共通変数
  • itcl::class .. クラス
  • itcl::body .. クラスメソッドの本体の定義
  • oo::class create .. クラス
  • oo::define .. OO クラスの定義
  • method .. クラスメソッドの定義
  • constructor .. クラスのコンストラクタ
  • destructor .. クラスのデストラクタ
  • public .. 保護レベルの指定
  • protected .. 保護レベルの指定
  • private .. 保護レベルの指定

doxygenスタイルのコメントを使った例です。

1 ## \file tclexample.tcl
2 # File documentation.
3 #\verbatim
4 
5 # Startup code:\
6 exec tclsh "$0" "$@"
7 #\endverbatim
8 ## Documented namespace \c ns .
9 # The code is inserted here:
10 #\code
11 namespace eval ns {
12  ## Documented proc \c ns_proc .
13  # param[in] arg some argument
14  proc ns_proc {arg} {}
15  ## Documented var \c ns_var .
16  # Some documentation.
17  variable ns_var
18  ## Documented itcl class \c itcl_class .
19  itcl::class itcl_class {
20  ## Create object.
21  constructor {args} {eval $args}
22  ## Destroy object.
23  destructor {exit}
24  ## Documented itcl method \c itcl_method_x .
25  # param[in] arg Argument
26  private method itcl_method_x {arg}{}
27  ## Documented itcl method \c itcl_method_y .
28  # param[in] arg Argument
29  protected method itcl_method_y {arg} {}
30  ## Documented itcl method \c itcl_method_z .
31  # param[in] arg Argument
32  public method itcl_method_z {arg} {}
33  ## Documented common itcl var \c itcl_Var .
34  common itcl_Var
35  ## \protectedsection
36 
37  variable itcl_var1;#< Documented itcl var \c itcl_var1 .
38  variable itcl_var2}
39  ## Documented oo class \c oo_class .
40  oo::class create oo_class {
41  ## Create object.
42  # Configure with args
43  constructor {args} {eval $args}
44  ## Destroy object.
45  # Exit.
46  destructor {exit}
47  ## Documented oo var \c oo_var .
48  # Defined inside class
49  variable oo_var
50  ## \private Documented oo method \c oo_method_x .
51  # param[in] arg Argument
52  method oo_method_x {arg} {}
53  ## \protected Documented oo method \c oo_method_y .
54  # param[in] arg Argument
55  method oo_method_y {arg} {}
56  ## \public Documented oo method \c oo_method_z .
57  # param[in] arg Argument
58  method oo_method_z {arg} {}
59  }
60 }
61 #\endcode
62 
63 itcl::body ::ns::itcl_class::itcl_method_x {argx} {
64  puts "$argx OK"
65 }
66 
67 oo::define ns::oo_class {
68  ## \public Outside defined variable \c oo_var_out .
69  # Inside oo_class
70  variable oo_var_out
71 }
72 
73 ## Documented global proc \c glob_proc .
74 # param[in] arg Argument
75 proc glob_proc {arg} {puts $arg}
76 
77 variable glob_var;#< Documented global var \c glob_var\
78  with newline
79 #< and continued line
80 
81 # end of file
ここをクリックすると、Doxygenが生成したHTMLドキュメントが表示されます。

コメントブロックの解剖

前節では、コード内のコメントをdoxygenに知らしめる方法に焦点をあてました。 要約説明と詳細説明の違い、構造化コマンドの使い方を説明しました。

当節では、コメントブロックの内容に焦点をあてます。

doxygenは、さまざまなスタイルのコメント形式をサポートします。

最も単純な形式は、プレインテキストです。出力にそのまま出現し、短い説明にぴったりです。

長めの説明には、構造が必要になることが多いでしょう。例えば、逐語テキスト、リスト、単純なテーブルなど。このため、doxygenでは、Markdown 構文をサポートします。また、Markdown Extraも部分的にサポートします。

Markdownは、設計上、読み書きが非常に容易です。 そのフォーマットは、プレインテキスト・メール形式に基づいています。 Markdownは、プロジェクトの導入ページなどにふさわしい、単純で一般的なフォーマットに効果が大きいです。doxygenでは、markdownファイルの直接読み込みをサポートします。 詳しくは、markdownを参照してください。

プログラミング言語特有のフォーマットに対応するため、doxygenは、Markdownフォーマットの上に2つの形式のマークアップを追加しました。

  1. Javadoc マークアップライク。 はじめに で、doxygenがサポートするコマンドすべてを概観してください。
  2. XML マークアップ。C# 標準で定められています。XMLコマンドで、doxygenがサポートするXMLコマンドを参照してください。

これでも充分でなければ、doxygenはHTMLマークアップ言語の サブセットのサポートもしています。

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

This page was last modified on Sat Aug 24 2014.
© 1997-2014 Dimitri van Heesch, first release 27 oct 1997.
© 2001 OKA Toshiyuki (Japanese translation).
© 2006-2014 TSUJI Takahiro (Japanese translation).
© 2006-2014 TAKAGI Nobuhisa (Japanese translation).