コードのドキュメント化

目次

• 特殊コメントブロック
  • C系言語（C/C++/C#/Objective-C/PHP/Java）のコメントブロック
    • メンバの後ろにドキュメントを配置する
    • 例
    • その他の場所でのドキュメント化
  • Pythonのコメントブロック
  • VHDLのコメントブロック
  • Fortranのコメントブロック
• コメントブロックの構造

この章では2つのトピックについて説明します

1. Doxygenが生成するドキュメントにコメントを組み込む方法。これについては次のセクションで詳しく説明します。
2. 出力が見栄え良くなるようにコメントブロックの内容を構造化する方法。コメントブロックの構造のセクションで説明されています。

特殊コメントブロック

特殊コメントブロックとは、Doxygenが生成されるドキュメントに含める必要がある構造化されたテキストであることを認識できるように、追加のマークが付いたCまたはC++形式のコメントブロックです。次のセクションでは、Doxygenがサポートする様々なスタイルを紹介します。

Python、VHDL、Fortranのコードには異なるコメント規約があり、それぞれPythonのコメントブロック、VHDLのコメントブロック、Fortranのコメントブロックのセクションに記載されています。

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

コード内の各エンティティには、そのエンティティのドキュメントを形成する2種類（場合によっては3種類）の説明があります。それぞれ簡潔な説明と詳細な説明で、どちらもオプションです。メソッドと関数には、いわゆるin body説明という3種類目の説明もあり、これはメソッドまたは関数の本体内で見つかったすべてのコメントブロックの連結で構成されます。

複数の簡潔な説明や詳細な説明を持つことは許可されています（ただし、説明が表示される順序は指定されていないため、推奨されません）。

名前が示すように、簡潔な説明は短い1行のもので、詳細な説明はより長く、詳細なドキュメントを提供します。「in body」説明は、詳細な説明として機能したり、実装の詳細の集合を説明したりすることもできます。HTML出力では、項目が参照されている場所でツールチップを提供するためにも簡潔な説明が使用されます。

コメントブロックを詳細な説明としてマークする方法はいくつかあります

1. Javadocスタイルを使用できます。これは、2つのアスタリスクで始まるCスタイルのコメントブロックで、例えば次のようになります

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

2. あるいはQtスタイルを使用し、Cスタイルのコメントブロックの開始記号の後に感嘆符（!）を追加することもできます。この例に示されています

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

   どちらの場合も、中間のアスタリスクはオプションであるため、

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

   も有効です。

3. 3つ目の方法は、少なくとも2行のC++コメント行のブロックを使用することです。各行は追加のスラッシュまたは感嘆符で始まります。これら2つのケースの例を次に示します

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

   または

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

   この場合、空行でドキュメントブロックが終了することに注意してください。

4. コメントブロックをドキュメントでより目立たせたい人もいます。この目的のために、以下を使用できます

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

   注: 通常のコメントブロックを終了し、特殊コメントブロックを開始するための2つのスラッシュ。

   注: clang-formatのようなリフォーマッターを使用する際は注意してください。この種のコメントを2つの別々のコメントと見なし、それらの間に空白を挿入する可能性があります。

   または

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

   または

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

   JAVADOC_BANNERがYESに設定されている限り。

   /**
   * JavaDocスタイル（Cスタイル）コメントの簡単な歴史。
    *
   * これは典型的なJavaDocスタイルCスタイルコメントです。2つの
   * アスタリスクで始まります。
    *
   * @param theory 唯一可能な統一理論があったとしても、それは単なる
   * 一連の規則と方程式です。
    */
   void cstyle( int theory );
    
   /******************************************************************************
   * JavaDocスタイル（Cスタイル）バナーコメントの簡単な歴史。
    *
   * これは典型的なJavaDocスタイルCスタイル「バナー」コメントです。これは
   * スラッシュの後にいくつかのn個のアスタリスクが続き（n > 2）、
   * ソースコードを読む開発者にとってより「視覚的に」目立つように書かれています。
   * ソースコード。
    *
   * 多くの場合、開発者はこれが（デフォルトでは）有効なDoxygen
   * コメントブロックではないことに気づいていません！
    *
   * しかし、JAVADOC_BANNER = YES がDoxyfileに追加されている限り、これは
   * 期待通りに機能します。
    *
   * このコメントスタイルはclang-formatと相性が良いです。
    *
   * @param theory 唯一可能な統一理論があったとしても、それは単なる
   * 一連の規則と方程式です。
    ******************************************************************************/
   void javadocBanner( int theory );
    
   /**************************************************************************//**
   * Doxygenスタイルバナーコメントの簡単な歴史。
    *
   * これはDoxygenスタイルのCスタイル「バナー」コメントです。「通常の」コメントから始まり、
   * 最初の行の終わり近くで「特殊な」コメントブロックに変換されます。
   * これは、開発者にとってより「視覚的に」目立つように書かれています。
   * ソースコードを読んでいる人。
   * このコメントスタイルはclang-formatと相性が悪いです。
    *
   * @param theory 唯一可能な統一理論があったとしても、それは単なる
   * 一連の規則と方程式です。
    ******************************************************************************/
   void doxygenBanner( int theory );

   Doxygenによって生成された対応するHTMLドキュメントはこちらをクリックしてください。

簡潔な説明にもいくつかの可能性があります

1. 上記のコメントブロックのいずれかと一緒に\briefコマンドを使用できます。このコマンドは段落の終わりに終了するため、詳細な説明は空行の後に続きます。

   例を次に示します

   /*! \brief Brief description.
    *         Brief description continued.
    *
    *  Detailed description starts here.
    */
   

2. 設定ファイルでJAVADOC_AUTOBRIEFがYESに設定されている場合、Javadocスタイルのコメントブロックを使用すると、最初のピリオド、疑問符、または感嘆符の後にスペースまたは改行が続くところで自動的に簡潔な説明が開始されます。例を次に示します

   /** Brief description which ends at this dot. Details follow
    *  here.
    */
   

   このオプションは、複数行の特殊C++コメントにも同じ効果があります

   /// Brief description which ends at this dot. Details follow
   /// here.
   

3. 3つ目のオプションは、1行を超えない特殊なC++スタイルコメントを使用することです。2つの例を次に示します

   /// Brief description.
   /** Detailed description. */
   

   または

   //! Brief description.
   
   //! Detailed description
   //! starts here.
   

   最後の例の空行に注意してください。これは、簡潔な説明と詳細な説明を含むブロックを区切るために必要です。この場合、JAVADOC_AUTOBRIEFもNOに設定する必要があります。

ご覧のとおり、Doxygenは非常に柔軟です。次の例のように、複数の詳細な説明がある場合、

//! Brief description, which is
//! really a detailed description since it spans multiple lines.
/*! Another detailed description!
 */

それらは結合されます。説明がコードの異なる場所にある場合も同様であることに注意してください！この場合、順序はDoxygenがコードを解析する順序に依存します。

他のほとんどのドキュメントシステムとは異なり、Doxygenではメンバ（グローバル関数を含む）のドキュメントを定義の前に配置することもできます。この方法により、ドキュメントをヘッダファイルではなくソースファイルに配置できます。これによりヘッダファイルがコンパクトに保たれ、メンバの実装者がドキュメントに直接アクセスできるようになります。妥協案として、簡潔な説明は宣言の前に、詳細な説明はメンバ定義の前に配置することができます。

メンバの後ろにドキュメントを配置する

ファイル、構造体、共用体、クラス、または列挙型のメンバをドキュメント化したい場合、ドキュメントブロックをメンバの前に置くのではなく、後に配置することが望ましい場合があります。この目的のために、コメントブロックに追加の < マーカーを配置する必要があります。これは関数のパラメータにも適用されることに注意してください。

いくつかの例を次に示します

int var; /*!< Detailed description after the member */

このブロックは、メンバの後にQtスタイルの詳細なドキュメントブロックを配置するために使用できます。同じことを行う他の方法は次のとおりです

int var; /**< Detailed description after the member */

または

int var; //!< Detailed description after the member
         //!<

または

int var; ///< Detailed description after the member
         ///<

多くの場合、メンバの後に簡潔な説明のみを配置したいと考えます。これは次のように行います

int var; //!< Brief description after the member

または

int var; ///< Brief description after the member

関数では、@paramコマンドを使用してパラメータをドキュメント化し、その後[in]、[out]、[in,out]を使用して方向をドキュメント化できます。インラインドキュメントの場合も、方向属性で開始することで可能です。例：

void foo(int v /**< [in] docs for input parameter v. */);

これらのブロックは、前のセクションの特殊コメントブロックと同じ構造と意味を持ちますが、< はメンバがブロックの後ではなく、ブロックの前に位置することを示します。

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

/*! A test class */
 
class Afterdoc_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など）は、これらのコメントブロック内では許可されません。

この構造をマクロ定義の一部として使用する際は注意してください。なぜなら、マクロが適用される場所でMACRO_EXPANSIONがYESに設定されている場合、コメントも置換され、このコメントがマクロ定義自体ではなく、最後に検出された項目のドキュメントとして使用されてしまうからです！

例

Qtスタイルを使用したドキュメント化されたC++コードの例を次に示します

//! A test class. 
/*!
A more elaborate class description.
*/
 
class QTstyle_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.
    */
QTstyle_Test();
 
//! A destructor.
    /*!
A more elaborate description of the destructor.
    */
~QTstyle_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 QTstyle_Test(), ~QTstyle_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_DESCをNOに設定することで非表示にできます）。デフォルトでは、簡潔な説明は詳細な説明の最初の文になります（ただし、REPEAT_BRIEFタグをNOに設定することで変更できます）。Qtスタイルでは、簡潔な説明と詳細な説明の両方がオプションです。

デフォルトでは、JavadocスタイルのドキュメントブロックはQtスタイルのドキュメントブロックと同じように動作します。しかし、Javadocの仕様では、ドキュメントブロックの最初の文が自動的に簡潔な説明として扱われます。この動作を有効にするには、設定ファイルでJAVADOC_AUTOBRIEFをYESに設定する必要があります。このオプションを有効にして、文の途中にピリオドを入れても文を終了させたくない場合は、その後にバックスラッシュとスペースを配置する必要があります。例を次に示します

  /** Brief description (e.g.\ using only a few words). Details follow. */

上記で示したコードと同じものが、今回はJavadocスタイルとJAVADOC_AUTOBRIEFをYESに設定してドキュメント化されています

/**
* A test class. A more elaborate class description.
 */
 
class Javadoc_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.
       */
Javadoc_Test();
 
      /**
* A destructor.
* A more elaborate description of the destructor.
       */
~Javadoc_Test();
    
      /**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Javadoc_Test()
* @see ~Javadoc_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スタイルを好む場合は）アットマーク（@）で始まり、コマンド名と1つ以上のパラメータが続きます。例えば、上記の例のクラスTestをドキュメント化したい場合、Doxygenが読み取る入力のどこかに次のドキュメントブロックを配置することもできます

/*! \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関数、typedef、enum、またはプリプロセッサ定義をドキュメント化するには、それらを含むファイルを最初にドキュメント化する必要があります（通常、これはヘッダファイルになります。そのファイルが他のソースファイルにエクスポートされる情報を含むためです）。

注意

これはよく見落とされがちなので、繰り返します。グローバルオブジェクト（関数、typedef、enum、マクロなど）をドキュメント化するには、それらが定義されているファイルを必ずドキュメント化する必要があります。言い換えれば、そのファイルには少なくとも

/*! \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コマンドが冗長であり、問題を引き起こすだけです。

コメントブロックを以下の拡張子のいずれかを持つファイル（.dox、.txt、.doc、.md、または.markdown）に配置する場合、または拡張子がEXTENSION_MAPPINGによってmdにマップされる場合、Doxygenはこのファイルをファイルリストから非表示にします。

Doxygenが解析できないが、それでもドキュメント化したいファイルがある場合、\verbincludeを使用してそのまま表示できます。例：

/*! \file myscript.sh
 *  Look at this nice script:
 *  \verbinclude myscript.sh
 */

スクリプトがINPUTに明示的にリストされているか、FILE_PATTERNSに.sh拡張子が含まれており、EXAMPLE_PATHで設定されたパスにスクリプトが見つかることを確認してください。

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の特殊コマンドはサポートされず、テキストは\verbatimのように逐語的なテキストとして表示されます。Doxygenの特殊コマンドを使用し、テキストを"""ではなく通常のドキュメントとして表示させるには、"""!を使用するか、設定ファイルでPYTHON_DOCSTRINGをNOに設定してください。

"""の代わりに'''も使用できます。

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に似ているため、設定ファイルでOPTIMIZE_OUTPUT_JAVAをYESに設定する必要があります。

VHDLのコメントブロック

VHDLでは、コメントは通常「--」で始まります。Doxygenは「--!」で始まるコメントを抽出します。VHDLにはコメントブロックが2種類しかありません。簡潔な説明を表す1行の「--!」コメントと、詳細な説明を表す複数行の「--!」コメント（「--!」プレフィックスが各行で繰り返される）です。

コメントは常にドキュメント化される項目の前に配置されますが、1つの例外があります。ポートの場合、コメントは項目の後に配置することもでき、その場合はポートの簡潔な説明として扱われます。

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 Architecture 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ドキュメントはこちらをクリックしてください。

VHDL 2008以降では、/*形式のコメントも使用できます。
Doxygenは/* ... */を通常のコメントとして扱い、/*! ... */形式のコメントをDoxygenによって解析される特殊コメントとして扱います。

適切な出力結果を得るには、設定ファイルでOPTIMIZE_OUTPUT_VHDLをYESに設定する必要があります。これにより、他のいくつかの設定も影響を受けます。それらがすでに正しく設定されていない場合、Doxygenはどの設定が上書きされたかを警告します。

Fortranのコメントブロック

FortranコードにDoxygenを使用する場合、OPTIMIZE_FOR_FORTRANをYESに設定する必要があります。

パーサーは、ソースコードが固定フォーマットFortranか自由フォーマットFortranコードかを推測しようとします。これは常に正しいとは限りません。正しくない場合は、EXTENSION_MAPPINGを使用してこれを修正する必要があります。EXTENSION_MAPPING = f=FortranFixed f90=FortranFreeと設定することで、拡張子fのファイルは固定フォーマットFortranコードとして、拡張子f90のファイルは自由フォーマットFortranコードとして解釈されます。

Fortranでは、「!>」または「!<」がコメントを開始し、「!!」または「!>」が1行コメントを複数行コメントに継続するために使用できます。

ドキュメント化されたFortranサブルーチンの例を次に示します

!> Build the restriction matrix for the aggregation
!! method.
!! @param aggr information about the aggregates
!! @todo Handle special case
subroutine intrestbuild(A,aggr,Restrict,A_ghost)
  implicit none
  Type(SpMtx), intent(in) :: A !< our fine level matrix
  Type(Aggrs), intent(in) :: aggr
  Type(SpMtx), intent(out) :: Restrict !< Our restriction matrix
  !...
end subroutine

代替案として、固定フォーマットコードでコメントを使用することもできます

C> Function comment
C> another line of comment
      function a(i)
C> input parameter
        integer i
      end function A

コメントブロックの構造

前のセクションでは、コード内のコメントをDoxygenに認識させる方法に焦点を当て、簡潔な説明と詳細な説明の違い、および構造化コマンドの使用について説明しました。

このセクションでは、コメントブロック自体の内容について見ていきます。

Doxygenは、コメントの様々な書式設定スタイルをサポートしています。

最もシンプルな形式は、プレーンテキストを使用することです。これは出力にそのまま表示され、短い説明に最適です。

より長い説明では、逐語的なテキストブロック、リスト、シンプルな表など、より多くの構造が必要になることがよくあります。このため、DoxygenはMarkdown構文をサポートしており、Markdown Extra拡張機能の一部も含まれています。

Markdownは、非常に読み書きしやすいように設計されています。その書式設定は、プレーンテキストメールに触発されています。Markdownは、プロジェクトの紹介ページのようなシンプルで一般的な書式設定に最適です。DoxygenはMarkdownファイルの直接読み込みもサポートしています。詳細については、Markdownサポートの章を参照してください。

プログラミング言語固有の書式設定については、DoxygenはMarkdown書式設定に加えて2種類の追加マークアップを提供します。

1. Javadocのようなマークアップ。Doxygenがサポートするすべてのコマンドの完全な概要については、特殊コマンドを参照してください。
2. XMLマークアップ。C#標準で指定されています。DoxygenがサポートするXMLコマンドについては、XMLコマンドを参照してください。

これでも不十分な場合は、DoxygenはHTMLマークアップ言語のサブセットもサポートしています。

次のセクションへ進むか、インデックスに戻る。