リンクの自動生成

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

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

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

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

クラスへのリンク

ドキュメント内の単語で、ドキュメント付けされたクラスに対応するものはすべて、 そのクラスのドキュメントを格納するページへのリンクで自動的に置換されます。 そのようを置換を抑制したい単語があれば、その単語の前に % を置きます。

ファイルへリンク

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

関数へのリンク

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

1. <関数名> "(" <引数リスト> ")"
2. <関数名> "()"
3. "::" <関数名>
4. (<クラス名> "::")n <関数名> "(" <引数リスト> ")"
5. (<クラス名> "::")n <関数名> "()"
6. (<クラス名> "::")n <関数名>

ただし、n > 0。

注 1:

上記パターンは、空白、タブあるいは改行を含んではいけません。

注 2:

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

注 3:

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

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

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

メンバー関数に対しては、以下の条件を満たせば、 クラススコープ (パターン 4 〜 6) は省略できます。

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

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

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

例:

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

---