リンクの自動生成

ドキュメンテーションシステムの多くは、「参照」という特別なセクションがあり、他のドキュメント断片へのリンクを挿入することができます。 Doxygen にもそのようなセクションを開始するコマンド (セクション \sa を参照) がありますが、ドキュメントのどこにでもこの種のリンクを張ることも可能になっています。 $\mbox{\LaTeX}$ のドキュメントに対しては、リンクの替わりにページ番号への参照が出力されます。さらには、ドキュメントの末尾にある索引を利用することで、メンバー、クラス、名前空間、あるいはファイルをすばやく見つけることができます。 man ページに対しては、参照情報は何も生成されません。

以下のセクションでは、ソースファイルの中のドキュメント付けられた様々な要素へのリンクがどのように生成されるかを説明します。

Web ページおよびメールアドレスへのリンク

Doxygen は、ドキュメント内で発見した URL やメールアドレスを、自動的にリンクで置換します。

クラスへのリンク

ドキュメント付けされたクラスに対応するドキュメントの単語のうち、大文字が含まれるものは、自動的に、そのクラスのドキュメントを格納するページへのリンクで置換されます。置換を抑制するには、その単語の前に % を置いてください。

ファイルへリンク

末尾以外のところにドット (.) を含むような単語は、すべてファイル名とみなされます。その単語が本当にドキュメント付けされた入力ファイルの名前であれば、そのファイルのドキュメントへのリンクが自動的に生成されます。

関数へのリンク

関数へのリンクは、以下のパターンのうちどれかに遭遇した場合に生成されます:

<関数名> "(" <引数リスト> ")"
<関数名> "()"
"::" <関数名>
(<クラス名> "::")ⁿ <関数名> "(" <引数リスト> ")"
(<クラス名> "::")ⁿ <関数名> "(" <引数リスト> ")"<修飾子>
(<クラス名> "::")ⁿ <関数名> "()"
(<クラス名> "::")ⁿ <関数名>

ただし、n > 0。

メモ 1:: 関数の引数は正しい型 (すなわち、'fun(const std::string&,bool)' や '()') を指定しなければなりません。

メモ 2:: ターゲットを識別するために、'const' や 'volatile' のようなメンバ関数の修飾子が要求されます。すなわち、func(int) と func(int) const では異なるメンバ関数がターゲットとなります。

メモ 3:: JavaDoc との互換性のために、上記パターンでは :: のかわりに # が使われていても構いません。

メモ 4:: foo というメンバーを持つクラスのドキュメントでは、 foo を使うとグローバル変数への参照になりますが、 #foo はメンバーへのリンクになります。

オーバーロードされていないメンバーについては引数リストが省略されていても構いません。

関数がオーバーロードされていて引数リストが指定されていない (すなわち、パターン2 または 6が使われている) 場合は、オーバーロードされているメンバーのうちの一つのドキュメントに対してリンクが生成されます。

メンバー関数に対しては、以下の条件を満たせば、クラススコープ (パターン 4 縲鰀 7で使われているように) は省略できます。

パターンが、そのパターンを含むドキュメントブロックと同じクラスに属するドキュメント付けされたメンバーを指している。
パターンを含むドキュメントブロックに対応するクラスが、そのパターンにマッチするドキュメント付けされたメンバーを持つ基底クラスから派生している。

変数、typedef, enum 型, enum 値、および define へのリンク

これらの要素はすべて、直前のセクションで記述したのと同じやり方でリンクできます。明確にするために、このケースではパターン 3 と 7 だけが使われると言っておきましょう。

例:

/*! \file autolink.cpp
  Testing automatic link generation.
  
  A link to a member of the Test class: Test::member, 
  
  More specific links to the each of the overloaded members:
  Test::member(int) and Test#member(int,int)

  A link to a protected member variable of Test: Test#var, 

  A link to the global enumeration type #GlobEnum.
 
  A link to the define #ABS(x).
  
  A link to the destructor of the Test class: Test::~Test, 
  
  A link to the typedef ::B.
 
  A link to the enumeration type Test::EType
  
  A link to some enumeration values Test::Val1 and ::GVal2
*/

/*!
  Since this documentation block belongs to the class Test no link to 
  Test is generated.

  Two ways to link to a constructor are: #Test and Test().

  Links to the destructor are: #~Test and ~Test().
  
  A link to a member in this class: member().

  More specific links to the each of the overloaded members: 
  member(int) and member(int,int). 
  
  A link to the variable #var.

  A link to the global typedef ::B.

  A link to the global enumeration type #GlobEnum.
  
  A link to the define ABS(x).
  
  A link to a variable \link #var using another text\endlink as a link.
  
  A link to the enumeration type #EType.

  A link to some enumeration values: \link Test::Val1 Val1 \endlink and ::GVal1.

  And last but not least a link to a file: autolink.cpp.
  
  \sa Inside a see also section any word is checked, so EType, 
      Val1, GVal1, ~Test and member will be replaced by links in HTML.
*/

class Test
{
  public:
    Test();               //!< constructor 
   ~Test();               //!< destructor 
    void member(int);     /**< A member function. Details. */
    void member(int,int); /**< An overloaded member function. Details */

    /** An enum type. More details */
    enum EType { 
      Val1,               /**< enum value 1 */ 
      Val2                /**< enum value 2 */ 
    };                

  protected:
    int var;              /**< A member variable */
};

/*! details. */
Test::Test() { }

/*! details. */
Test::~Test() { }

/*! A global variable. */
int globVar;

/*! A global enum. */
enum GlobEnum { 
                GVal1,    /*!< global enum value 1 */ 
                GVal2     /*!< global enum value 2 */ 
              };

/*!
 *  A macro definition.
 */ 
#define ABS(x) (((x)>0)?(x):-(x))

typedef Test B;

/*! \fn typedef Test B
 *  A type definition. 
 */

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

typedefの解決

typedef struct StructName TypeName

のように class、struct あるいは union を含む typedef は、 StructName の別名を生成します。そして、StructName または TypeName に遭遇した場合は、StructName へのリンクが生成されます。

例:

/*! \file restypedef.cpp
 * An example of resolving typedefs.
 */

/*! \struct CoordStruct
 * A coordinate pair.
 */
struct CoordStruct
{
  /*! The x coordinate */
  float x;
  /*! The y coordinate */
  float y;
};

/*! Creates a type name for CoordStruct */ 
typedef CoordStruct Coord;

/*! 
 * This function returns the addition of \a c1 and \a c2, i.e:
 * (c1.x+c2.x,c1.y+c2.y)
 */
Coord add(Coord c1,Coord c2)
{
}

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

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