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

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

特殊ドキュメント・ブロック

特殊ドキュメント・ブロックは、C または C++スタイルのコメントブロックにマークを付け加えたもので、Doxygenはこれをドキュメント断片と認識して、ドキュメントを生成します。 PythonとVHDLコードについては、別のコメント表記規則があります。セクションPython での特殊ドキュメント・ブロック と VHDL での特殊ドキュメント・ブロック で説明します。

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

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

名前からわかるように、要約説明は短い一行ですが、詳細説明はより長く、より詳しいドキュメントを提供します。"本文内"説明も詳細説明となりますが、こちらは実装の詳細をまとまって説明することができます。

HTML出力の場合、要素が参照されている箇所で要約説明を使えばツールチップを提供できます。

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

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

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

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

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

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

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

    もまた使えます。

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

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

    または

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

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

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

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

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

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

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

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

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

    以下に例を挙げます。

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

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

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

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

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

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

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

    または

    //! 要約説明

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

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

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

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

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

以下は、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 ドキュメントが開きます。

複数行のコメント・ブロックがより詳細な説明を含んでいるのに対して、1行コメントは要約説明を含んでいます。

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

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

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

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

/**
 *  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 では、(グローバルな関数も含め) メンバー定義の前のところにドキュメントを置くこともできます。 このことによって、ヘッダーファイルではなく、ソースファイルにドキュメントを置くことが可能になります。 ヘッダーファイルはコンパクトに保たれ、また、メンバーの実装者は、より直接的にドキュメントにアクセスすることができるようになるのです。 折衷案として、宣言の前に要約説明を置き、メンバー定義の前に詳細説明を置いてもよいでしょう。

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

ファイル、構造体、共用体、クラス、あるいは列挙型のメンバーをドキュメント付けしたい、しかも、これらのメンバーに対するドキュメントを複合体 (compound)の内部に置きたいという場合は、メンバーの前ではなく、メンバーの後にドキュメント・ブロックを置くことが望ましいこともあります。 この目的には、コメント・ブロックの中に < マーカーを追加してください。この機能は関数のパラメータでも使えます。

例を示します。 

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 ドキュメントが開きます。

\警告 これらブロックは、メンバーと パラメータをドキュメント付けするためにしか使えません。 これらは、ファイル、クラス、共用体、構造体、グループ、名前空間、列挙型そのものを ドキュメント付けするためには使えません。更に、次のセクションで挙げる構造化コマンド (\class のような) は、これらコメントブロック内では無視されます。

ドキュメント・ブロックの移動

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

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

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

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

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

/*! \class Test
    \brief A test class.

    A more detailed class description.
*/

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

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

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

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

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

/*! \file */

か a 

/** @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 ドキュメントが開きます。

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

Python での特殊ドキュメント・ブロック

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

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

class PyClass:
    """Documentation for a class.

    More details.
    """
   
    def __init__(self):
        """The constructor."""
        self._memVar = 0;
   
    def PyMethod(self):
        """Documentation for a method."""
        pass
ここ をクリックすると、これに対応する、doxygen で生成された HTML ドキュメントが開きます。

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

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

## @package pyexample
#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

## Documentation for a class.
#
#  More details.
class PyClass:
   
    ## The constructor.
    def __init__(self):
        self._memVar = 0;
   
    ## Documentation for a method.
    #  @param self The object pointer.
    def PyMethod(self):
        pass
     
    ## A class variable.
    classVar = 0;

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

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

VHDL での特殊ドキュメント・ブロック

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

コメントは常に、ひとつの例外でドキュメント付けされた要素の前に配置されます。ポートではコメントはアイテムの後ろにも置かれ、ポートの要約説明として扱えます。

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

-------------------------------------------------------
--! @file
--! @brief 2:1 Mux using with-select
-------------------------------------------------------

--! Use standard library
library ieee;
--! Use logic elements
    use ieee.std_logic_1164.all;

--! Mux entity brief description

--! Detailed description of this 
--! mux design element.
entity mux_using_with is
    port (
        din_0   : in  std_logic; --! Mux first input
        din_1   : in  std_logic; --! Mux Second input
        sel     : in  std_logic; --! Select input
        mux_out : out std_logic  --! Mux output
    );
end entity;

--! @brief Architure definition of the MUX
--! @details More details about this mux element.
architecture behavior of mux_using_with is
begin
    with (sel) select
    mux_out <= din_0 when '0',
               din_1 when others;
end architecture;
ここをクリックすると、Doxygenが生成したHTMLドキュメントが表示されます。

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

次 のセクションに行く / インデックス に戻る
メーリングリスト
メーリングリスト (英語)
メール書庫 (英語)
CVS tarballs
補助ツール
リンク集

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).