ドキュメント 変更履歴 拡張機能 例  
コードのドキュメント化

目次

この章では2つのトピックを扱います

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

特別なコメントブロック

特別なコメントブロックは、C または C++ スタイルのコメントブロックにいくつかの追加マーキングを施したもので、Doxygen はそれを生成されたドキュメントに含める必要のある構造化テキストの一部として認識します。次のセクションでは、Doxygen でサポートされているさまざまなスタイルを紹介します。

Python、VHDL、および Fortran コードの場合、コメント規則が異なります。これについては、それぞれセクション Python におけるコメントブロック、VHDL におけるコメントブロック、および Fortran におけるコメントブロック を参照してください。

Cライクな言語 (C/C++/C#/Objective-C/PHP/Java) のためのコメントブロック

コード内の各エンティティには、2 つ (場合によっては 3 つ) のタイプの記述があり、それらがまとめてそのエンティティのドキュメントを構成します。短い説明と詳細な説明があり、どちらもオプションです。メソッドと関数の場合、3 番目のタイプの記述であるインボディ記述もあります。これは、メソッドまたは関数の本体内で見つかったすべてのコメントブロックの連結で構成されます。

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

名前が示すように、短い説明は短い1行の説明であり、詳細な説明はより長く、より詳細なドキュメントを提供します。「インボディ」記述は、詳細な説明として機能することも、実装の詳細のコレクションを記述することもできます。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 たとえ可能な統一理論が 1 つしかないとしても、それは単なる
    * 規則と方程式のセット。
    */
    void cstyle( int theory );
    /******************************************************************************
    * JavaDoc スタイル (C スタイル) バナー コメントの簡単な歴史。
    *
    * これは典型的な JavaDoc スタイル C スタイル「バナー」コメントです。スラッシュで始まり、その後にいくつかの数 n のアスタリスクが続きます。ここで、n > 2 です。これは、ソースコードを読んでいる開発者にとってより「目立つ」ように書かれています。
    * ソースコードを読んでいる開発者にとってより「目立つ」ように書かれています。
    * ソースコードを読んでいる開発者にとってより「目立つ」ように書かれています。
    * ソースコードを読んでいる開発者にとってより「目立つ」ように書かれています。
    *
    * 多くの場合、開発者はこれが (デフォルトでは) 有効な Doxygen コメントではないことを認識していません
    * コメントブロック!
    *
    * ただし、JAVADOC_BANNER = YES が Doxyfile に追加されている限り、
    * 期待どおりに動作します。
    *
    * このコメントスタイルは clang-format でうまく動作します。
    *
    * @param theory たとえ可能な統一理論が 1 つしかないとしても、それは単なる
    * 規則と方程式のセット。
    ******************************************************************************/
    void javadocBanner( int theory );
    /**************************************************************************//**
    * Doxygen スタイル バナー コメントの簡単な歴史。
    *
    * これは Doxygen スタイル C スタイル「バナー」コメントです。「通常」で始まります
    * コメントを作成し、最初の行の終わりに近いところで「特別な」コメントブロックに変換します。これは、ソースコードを読んでいる開発者にとってより「目立つ」ように書かれています。
    * ソースコードを読んでいる開発者にとってより「目立つ」ように書かれています。
    * ソースコードを読んでいる開発者にとってより「目立つ」ように書かれています。
    * このコメントスタイルは clang-format でうまく動作しません。
    *
    * @param theory たとえ可能な統一理論が 1 つしかないとしても、それは単なる
    * 規則と方程式のセット。
    ******************************************************************************/
    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. */);

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

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

/*! テストクラス */
class Afterdoc_Test
{
public:
/** 列挙型。
* ドキュメントブロックは列挙型の後には配置できません!
*/
enum EnumType
{
int EVal1, /**< 列挙値 1 */
int EVal2 /**< 列挙値 2 */
};
void member(); //!< メンバー関数。
protected:
int value; /*!< 整数値 */
};

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

警告
これらのブロックは、メンバーとパラメータをドキュメント化するためにのみ使用できます。ファイル、クラス、共用体、構造体、グループ、名前空間、マクロ、および列挙型自体をドキュメント化するために使用することはできません。さらに、次のセクションで説明する構造コマンド (\class など) は、これらのコメントブロック内では許可されていません。
MACRO_EXPANSION が YES に設定されている場合、マクロが適用される場所でコメントも置換され、このコメントはマクロ定義自体のドキュメントではなく、最後に検出された項目のドキュメントとして使用されるため、マクロ定義の一部としてこの構造を使用する場合は注意してください!

例

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

//! テストクラス。
/*!
より手の込んだクラスの説明。
*/
class QTstyle_Test
{
public:
//! 列挙型。
/*! より詳細な列挙型の説明。 */
enum TEnum {
TVal1, /*!< 列挙値 TVal1。 */
TVal2, /*!< 列挙値 TVal2。 */
TVal3 /*!< 列挙値 TVal3。 */
}
//! 列挙型ポインタ。
/*! 詳細。 */
*enumPtr,
//! 列挙型変数。
/*! 詳細。 */
enumVar;
//! コンストラクタ。
/*!
コンストラクタのより手の込んだ説明。
*/
QTstyle_Test();
//! デストラクタ。
/*!
デストラクタのより手の込んだ説明。
*/
~QTstyle_Test();
//! 2 つの引数を取り、整数値を返す通常のメンバー。
/*!
\param a 整数引数。
\param s 定数文字ポインタ。
\return テスト結果
\sa QTstyle_Test(), ~QTstyle_Test(), testMeToo() および publicVar()
*/
int testMe(int a,const char *s);
//! 純粋仮想メンバー。
/*!
\sa testMe()
\param c1 最初の引数。
\param c2 2 番目の引数。
*/
virtual void testMeToo(char c1,char c2) = 0;
//! パブリック変数。
/*!
詳細。
*/
int publicVar;
//! 関数変数。
/*!
詳細。
*/
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 に設定されています

/**
* テストクラス。より手の込んだクラスの説明。
*/
class Javadoc_Test
{
public:
/**
* 列挙型。
* より詳細な列挙型の説明。
*/
enum TEnum {
TVal1, /**< 列挙値 TVal1。 */
TVal2, /**< 列挙値 TVal2。 */
TVal3 /**< 列挙値 TVal3。 */
}
*enumPtr, /**< 列挙型ポインタ。詳細。 */
enumVar; /**< 列挙型変数。詳細。 */
/**
* コンストラクタ。
* コンストラクタのより手の込んだ説明。
*/
Javadoc_Test();
/**
* デストラクタ。
* デストラクタのより手の込んだ説明。
*/
~Javadoc_Test();
/**
* 2 つの引数を取り、整数値を返す通常のメンバー。
* @param a 整数引数。
* @param s 定数文字ポインタ。
* @see Javadoc_Test()
* @see ~Javadoc_Test()
* @see testMeToo()
* @see publicVar()
* @return テスト結果
*/
int testMe(int a,const char *s);
/**
* 純粋仮想メンバー。
* @see testMe()
* @param c1 最初の引数。
* @param c2 2 番目の引数。
*/
virtual void testMeToo(char c1,char c2) = 0;
/**
* パブリック変数。
* 詳細。
*/
int publicVar;
/**
* 関数変数。
* 詳細。
*/
int (*handler)(int a,int b);
};

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

同様に、Qt スタイルのドキュメントブロックの最初の文を短い説明として自動的に処理する場合は、設定ファイルで QT_AUTOBRIEF を YES に設定できます。

他の場所でのドキュメント

前のセクションの例では、コメントブロックは常に、ファイル、クラス、または名前空間の宣言または定義の前、またはそのメンバーの 1 つの前または後に配置されていました。これは多くの場合快適ですが、ドキュメントを他の場所に配置する理由がある場合もあります。ファイルをドキュメント化する場合、ファイルの「前」のようなものがないため、これは必須です。

Doxygen では、ドキュメントブロックを実質的にどこにでも配置できます (例外は、関数の本体内または通常の C スタイル コメントブロック内です)。

アイテムの直前 (または直後) にドキュメントブロックを配置しないことの代償は、ドキュメントブロック内に構造コマンドを配置する必要があることであり、情報の重複につながります。したがって、実際には、他の要件で強制されない限り、構造コマンドの使用を避ける必要があります。

構造コマンド (他のすべてのコマンドと同様) は、バックスラッシュ (\) またはアットマーク (@) (Javadoc スタイルを好む場合) で始まり、その後にコマンド名と 1 つ以上のパラメータが続きます。たとえば、上記の例のクラス Test をドキュメント化する場合は、Doxygen が読み取る入力のどこかに次のドキュメントブロックを配置することもできます

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

    A more detailed class description.
*/

ここでは、特別なコマンド \class を使用して、コメントブロックにクラス Test のドキュメントが含まれていることを示しています。その他の構造コマンドは次のとおりです

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

これらのコマンドおよびその他の多くのコマンドの詳細については、セクション 特殊コマンド を参照してください。

C++ クラスのメンバーをドキュメント化するには、クラス自体もドキュメント化する必要があります。名前空間についても同様です。グローバル C 関数、typedef、列挙型、またはプリプロセッサ定義をドキュメント化するには、まずそれらを含むファイル (通常はヘッダーファイルになります。そのファイルには、他のソースファイルにエクスポートされる情報が含まれているため) をドキュメント化する必要があります。

注意
これはよく見落とされるため、繰り返しますが、グローバルオブジェクト (関数、typedef、列挙型、マクロなど) をドキュメント化するには、それらが定義されているファイルをドキュメント化する必要があります。言い換えれば、少なくとも
/*! \file */
または
/** @file */
このファイルに 1 行必要です。

構造コマンドを使用してドキュメント化された structcmd.h という名前の C ヘッダーの例を次に示します

/*! \file structcmd.h
\brief ドキュメント化されたファイル。
詳細。
*/
/*! \def MAX(a,b)
\brief \a a と \a b の最大値を返すマクロ。
詳細。
*/
/*! \var typedef unsigned int UINT32
\brief . の型定義。
詳細。
*/
/*! \var int errno
\brief 最後のエラーコードが含まれています。
\warning スレッドセーフではありません!
*/
/*! \fn int open(const char *pathname,int flags)
\brief ファイル記述子を開きます。
\param pathname 記述子の名前。
\param flags オープンフラグ。
*/
/*! \fn int close(int fd)
\brief ファイル記述子 \a fd を閉じます。
\param fd 閉じる記述子。
*/
/*! \fn size_t write(int fd,const char *buf, size_t count)
\brief \a count バイトを \a buf からファイル記述子 \a fd に書き込みます。
\param fd 書き込む記述子。
\param buf 書き込むデータバッファ。
\param count 書き込むバイト数。
*/
/*! \fn int read(int fd,char *buf,size_t count)
\brief ファイル記述子からバイトを読み取ります。
\param fd 読み取る記述子。
\param buf 読み取るバッファ。
\param count 読み取るバイト数。
*/
#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
このモジュールのドキュメント。
詳細。
"""
def func()
"""関数のドキュメント。
詳細。
"""
pass
class PyClass
"""クラスのドキュメント。
詳細。
"""
def __init__(self)
"""コンストラクタ。"""
self._memVar = 0;
def PyMethod(self)
"""メソッドのドキュメント。"""
pass

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

注
""" を使用する場合、Doxygen の 特殊コマンド はサポートされておらず、テキストはリテラルテキストとして表示されます (\verbatim を参照)。Doxygen の 特殊コマンド を使用して、テキストを """ の代わりに通常のドキュメントとして表示するには、"""! を使用するか、設定ファイルで PYTHON_DOCSTRING を NO に設定します。
""" の代わりに ''' を使用することもできます。

Python コードをドキュメント化する別の方法として、"##" または "##<" で始まるコメントを使用する方法もあります。これらのタイプのコメントブロックは、Doxygen でサポートされている他の言語のドキュメントブロックの動作方法とより一致しており、特殊コマンドの使用も可能です。

同じ例をもう一度示しますが、今度は Doxygen スタイルのコメントを使用しています

## @package pyexample
# このモジュールのドキュメント。
#
# 詳細。
## 関数のドキュメント。
#
# 詳細。
def func()
pass
## クラスのドキュメント。
#
# 詳細。
class PyClass
## コンストラクタ。
def __init__(self)
self._memVar = 0;
## メソッドのドキュメント。
# @param self オブジェクトポインタ。
def PyMethod(self)
pass
## クラス変数。
classVar = 0;
## @var _memVar
# メンバー変数

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

python は C や C++ よりも Java に似ているため、設定ファイルで OPTIMIZE_OUTPUT_JAVA を YES に設定する必要があります。

VHDL におけるコメントブロック

VHDL の場合、コメントは通常 "--" で始まります。Doxygen は "--!" で始まるコメントを抽出します。VHDL には 2 つのタイプのコメントブロックしかありません。短い説明を表す 1 行の "--!" コメントと、詳細な説明を表す複数行の "--!" コメント (各行に "--!" プレフィックスが繰り返されます)。

コメントは常に、ドキュメント化される項目の前に配置されます。ただし、ポートの場合は例外で、項目の後にコメントを配置することもでき、その場合はポートの短い説明として扱われます。

Doxygen コメントを含む VHDL ファイルの例を次に示します

-------------------------------------------------------
--! @file
--! @brief with-select を使用した 2:1 Mux
-------------------------------------------------------
--! 標準ライブラリを使用
library ieee;
--! ロジック要素を使用
use ieee.std_logic_1164.all;
--! Mux エンティティの短い説明
--! この詳細な説明
--! mux 設計要素。
entity mux_using_with is
port (
din_0 : in std_logic; --! Mux 最初の入力
din_1 : in std_logic; --! Mux 2 番目の入力
sel : in std_logic; --! 選択入力
mux_out : out std_logic --! Mux 出力
);
end entity;
--! @brief MUX のアーキテクチャ定義
--! @details この mux 要素に関する詳細。
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 サブルーチンの例を次に示します

!> 集約の制限行列を構築します
!! メソッド。
!! @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 !< 制限行列
!...
end subroutine

代替として、固定形式コードでコメントを使用することもできます

C> 関数のコメント
C> コメントの別の行
function a(i)
C> 入力パラメータ
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 コマンド のサブセット HTML マークアップ言語もサポートしています。

次の次へセクションに進むか、インデックスに戻ってください。