目次

• Web ページおよびメールアドレスへのリンク
• クラスへのリンク
• ファイルへのリンク
• 関数へのリンク
• 他のメンバーへのリンク

リンクの自動生成

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

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

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

Doxygen は、ドキュメント内で発見した URL やメールアドレスを、 自動的にリンクで置換します。手動でリンクテキストを指定するには、 次のように、HTML 'a' タグを使ってください。

<a href="linkURL">リンクテキスト</a> 

doxygenがこれを自動的に他の出力フォーマットに翻訳します。

クラスへのリンク

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

ファイルへのリンク

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

関数へのリンク

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

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

ただし、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で使われているように) は省略できます。

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

他のメンバーへのリンク

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

例:

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

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

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

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

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

  Links to the destructor are: #~Autolink_Test and ~Autolink_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 Autolink_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, ~Autolink_Test and member will be replaced by links in HTML.
*/

class Autolink_Test
{
  public:
    Autolink_Test();               //!< constructor 
   ~Autolink_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. */
Autolink_Test::Autolink_Test() { }

/*! details. */
Autolink_Test::~Autolink_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 Autolink_Test B;

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

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