doxygen的特定命令

摘要：本文給出doxygen所支援的全部的一個列表，同時對其進行逐一解釋與說明，對於使用doxygen來有重要參考價值。本文主要來自對doxygen官方文件的翻譯。

概述

所有在文件中的命令都開始於一個反斜槓(\)或者是一個at-符號(@)。如果你喜歡，可以把所有的以反斜槓開頭的命令都換成以at-符號開頭的命令。

有些命令有一個或多個引數，每一個引數都其確定的範圍：

如果使用 <尖>括號說明引數是一個單獨單詞。
如果使用(圓)括號說明引數一直到命令所在的結束。
如果使用{大}括號說明引數一直延伸到本段結束。一個段落的結束以一個空行來標識，或者是一個段落標記。
如果使用[中]括號說明引數是可選的。

下面是一個以字母順序的列表，列表給出了所有可用的命令：

下一節我們將具體介紹所有doxygen認識的命令，對於不認識的命令doxygen把它當作一般的文字。

命令的具體介紹

\addtogroup <name> [(title)]

本命令就像\defgroup定義一個組，但它不會因為多次使用相同的名字而收到一個警告。這些組會在最後合併到一起，形成一個邏輯上的大組。

標題是可選的，所以本命令也可以把一些物件加入一個已經存在的組中，使用@{ 和 @}的形式，如下：

/*!\addtogroup mygrp

 *  Additional documentation for group `mygrp'

 *  @{

 */



/*! *  A function 

 */

void func1()

{

}



/*!Another function */

void func2()

{

}



/*[email protected]} */.

\callgraph

當這個命令在一個函式或方法的註釋裡，並且設定檔案中的HAVE_DOT被設定為“YES”，那麼doxygen會產生出一個函式呼叫圖。此時不會理會設定檔案中的CALL_GRAPH選項的值。

注意：: 這個呼叫圖的完整性與正確性依賴於doxygen的解析，目前它還不是完美的。

\callergraph

當這個命令在一個函式或方法的註釋裡，並且設定檔案中的HAVE_DOT被設定為“YES”，那麼doxygen會產生出一個函式呼叫者圖。此時不會理會設定檔案中的CALLER_GRAPH選項的值。

注意：: 這個呼叫者圖的完整性與正確性依賴於doxygen的解析，目前它還不是完美的。

\category <name> [<header-file>] [<header-name>]

僅針對於帶類的C：說明這個文件塊屬於一個類，它的名字叫<name>。這個命令的引數意義與命令class一樣。

\class <name> [<header-file>] [<header-name>]

指明一個文件塊屬於一個類，它的名字叫<name>，header-file與header-name是可選的。如果header-file被指定，那麼會產生一個指定該標頭檔案複本的一個連結。如果header-name被指定，那麼就可以覆蓋該連結的標題，以及文件中其它使用這標頭檔案的情況，當一個頭檔案存在於一個非標準的搜尋目錄時很有用（比如<X11/X.h>）。通過header-name你可以指定這個“include”的指令顯示的效果，是在名字周圍加雙引號或是加尖括號。當沒有指定時，尖括號是預設的效果。請注意，這兩個引數可以通過命令\headerfile單獨指定。

示例：

/* A dummy class */

class Test

{

};



/*!\class Test class.h "inc/class.h"

 *  \brief This is a test class.

 *

 * Some details about the Test class

 */

點選這裡看看這段程式碼的產生的文件。

\def <name>

指出這塊註釋屬於一個#define巨集。

示例：

/*!\file define.h

    \brief testing defines

    

    This is to test the documentation of defines.

*/



/*!  \def MAX(x,y)

  Computes the maximum of \a x and \a y.

*/



/*!   Computes the absolute value of its argument \a x.

*/

#define ABS(x) (((x)&gt;0)?(x):-(x))

#define MAX(x,y) ((x)&gt;(y)?(x):(y))

#define MIN(x,y) ((x)&gt;(y)?(y):(x)) 

/*!&gt; Computes the minimum of \a x and \a y. */

點選這裡檢視這這段程式碼產生的文件。

\defgroup <name> (group title)

這指明當前的註釋塊屬於一個類、檔案或名字空間分組。這被用於把類、檔案或名字空間放於一個組。你同時也可以把一個組放於另一個組裡，這樣形成一個繼承的結構。

<name> 引數應該是一個單獨的識別符號。

\dir [<path fragment>]

指明當前註釋塊包含一個目錄的文件。引數“path fragment”應該包含目錄名，並且足夠用於區分不同的目錄。選項SHOW_DIRECTORIES用於指明是否顯示一個目錄的資訊，STRIP_FROM_PATH用於指明在輸出時過慮掉的字首。

\enum <name>

指明當前註釋塊包含一個列舉型別的文件，這個列舉型別的名字是“name”。如果這個列舉是一個類的成員，並且文件不在類的裡面，那麼作用域類也應該指出。如果當前的註釋塊放在一個列舉宣告的前面，這個 \enum 命令可以省去。

注意：: 匿名的列舉型別是不能文件化的，但是匿名的列舉值是可以的。

注意：: 一個匿名的列舉型別是不能文件化的，但是它的值可以。

示例：

class Test

{

  public:

    enum TEnum { Val1, Val2 };



    /*!Another enum, with inline docs */

    enum AnotherEnum 

    { 

      V1, /*!&lt; value 1 */

      V2  /*!&lt; value 2 */

    };

};



/*!\class Test

 * The class description.

 */



/*!\enum Test::TEnum

 * A description of the enum type.

 */



/*!\var Test::TEnum Test::Val1

 * The description of the first enum value.

 */

點選這裡檢視由doxygen生成的相應的文件。

\example <file-name>

指明一個註釋塊包含的文件屬於一個原始碼示例。原始碼檔案的名字叫<file-name>。這個檔案的內容將被包含在文件中，在這本塊註釋產生的文件之後。所有的示例被放在一個列表之中。原始碼會被掃描，以發現其中已文件化的成員和類。如果發現了，會在文件產生一個交叉引用。原始碼的檔案或目錄可能通過配製選項EXAMPLE_PATH，在配製檔案中指定。

如果<file-name>不在EXAMPLE_PATH中，你可以指定一個絕對路徑來使用它。

如果這個示例存在多個原始碼，命令 \include 可以被使用。

示例：

/** A Test class.

 *  More details about this class.

 */



class Test

{

  public:

    /** An example member function.

     *  More details about this function.

     */

    void example();

};



void Test::example() {}



/** \example example_test.cpp

 * This is an example of how to use the Test class.

 * More details about this example.

 */

這裡example_test.cpp的內容如下：

void main()

{

  Test t;

  t.example();

}

點選這裡檢視由doxygen產生的相應的文件。

\extends <name>

此命令可用於手動指示一個繼承關係，當程式語言本身不支援這個概念（如C）。

在示例資料夾中的manual.c檔案展示瞭如何使用這個命令。

點選這裡檢視由doxygen生成的相應的文件。

\file [<name>]

表明一個註釋塊包含一個原始檔或標頭檔案文件，它的名稱是<name> 。這裡的名字可以包含路徑，如果檔名不唯一的。如果檔名被省略（比如，在 \file 後面是空白），\file 所產生的文件屬於命令所在的檔案的文件。

重要：: 只有檔案本身是文件化的的時候，檔案所定義的全域性變數、函式、類型別名、列舉的文件才使包含在輸出。

例如：

/** \file file.h

 * A brief file description.

 * A more elaborated file description.

 */



/**

 * A global integer value.

 * More details about this value.

 */

extern int globalValue;

點選這裡檢視由doxygen生成的相應的文件。

\fn (函式宣告)

表明一個註釋塊包含一個函式（全域性或作為一個類的成員）的文件。只有當註釋塊不在函式的宣告或定義的前面（或者後面）時才需要這個命令。

如果註釋塊在函式宣告或定義的前面時，這個命令可以也應該省略。

一個完整的函式宣告，包括引數在內，需要在 \fn 的單獨一行,這是因為 \fn 命令的引數在行結束時結束。

警告：: 不要使用此命令，如果不是絕對必要，因為它會導致資訊重複，從而錯誤。

例如：

class Test

{

  public:

    const char *member(char,int) throw(std::out_of_range);

};



const char *Test::member(char c,int n) throw(std::out_of_range) {}



/*!\class Test

 * \brief Test class.

 *

 * Details about Test.

 */



/*!\fn const char *Test::member(char c,int n) 

 *  \brief A member function.

 *  \param c a character.

 *  \param n an integer.

 *  \exception std::out_of_range parameter is out of range.

 *  \return a character pointer.

 */

點選這裡檢視由doxygen生成的相應的文件。

相關參考

\headerfile <header-file> [<header-name>]

用於生成class、struct、union 文件，文件應該在定義之前。這個命令的引數與命令 \cmdclass的第二、第三引數相同。<header-file> 應該是一個包含相應class、struct、union定義的檔案。該<header-name>引數可以被用來覆蓋的是在文件中使用的類的東西以外的其他連結名稱<header-file> 。這可能是有用的，如果名稱不在預設的包含路徑（如<X11/X.h> ）。

使用<header-name>引數，你可以指定 include 語句的風格，是使用雙引號還是使用尖括號。如果沒有指定，預設地，使用尖括號。

如果只給出一對雙引號，而沒有 <header-file> 或者 <header-name> 引數，此時當前檔案會使用雙引號替換。所以，如果一個 \headerfile 命令的註釋塊在檔案test.h內部，那麼下面3個方式是相同的：

\headerfile test.h "test.h"
\headerfile test.h ""
\headerfile ""

如果想使用尖括號風格的，你不需要額外指定資訊，不過你需要顯式指定使用尖括號：

\headerfile test.h <test.h>
\headerfile test.h <>
\headerfile <>

與全域性的設定相反的，你可以通過把 FORCE_LOCAL_INCLUDES 設定為 YES 來使用區域性的包含行為。

\hideinitializer

預設情況，當一個值的定義或初始化式的長度不大於30行的時候，定義或初始式會被顯示。通過把這個命令插入定義或初始式中來隱藏它們。

\implements <name>

此命令可用於手動指示一個繼承關係，當程式語言本身不支援這個概念（如C）。

在示例資料夾中的manual.c檔案展示瞭如何使用這個命令。

點選這裡檢視由doxygen生成的相應的文件。

\ingroup (<groupname> [<groupname> <groupname>])

如果 \ingroup 命令放置於一個類、檔案或名字空間的註釋塊，那麼它將會被加入這個組，或者說被分入名字為 <groupname> 的組。

\interface <name> [<header-file>] [<header-name>]

表明一個註釋塊包含一個介面的檔案，這個介面的名字是 <name>。這些引數的意義與 \class 命令相同。

\internal

這個命令在輸出中加入“僅供內部使用”的文字，並且在命令 \internal 之後直到註釋塊或小節（哪個先達到）結束的全部文字都標記為“內部使用的”。

如果命令 \internal 在一個小節內部（參看\section 示例)），那麼在這個命令之後的包括全部子小節都被認為是內部的。只有一個新的小節，並且與當前的小節是同一等級的，才會改變這個情況。

你可以在設定檔案裡設定 INTERNAL_DOCS 的值來控制內部文件的顯示或隱藏。

\mainpage [(title)]

如果 \mainpage 被放置於一個註釋塊裡，那麼這個註釋塊將被用於產生一個首頁（在HTML的輸出中）或者是第一章（在 $\mbox{\LaTeX}$ 中）。

標題引數是可選的，在doxygen生成的過程中它會替代預設的標題。如果不想有一個標題，你可以指定notitle 作為 \mainpage 的引數。

這是一個示例：

/*!\mainpage 我的個人定製首頁

 *

 * \section intro_sec  概述

 *

 * 這是概述 *

 * \section install_sec 安裝

 *

 * \subsection step1 Step 1: Opening the box

 *  

 * 等等……

 */

你可以通過 \ref index 來引用首頁。（如果樹檢視被禁用了，你可以使用 \ref main）

\memberof <name>

這個命令指定一個函式是一個類的成員，它處理的方式與\relates 很相似，兩者唯一的區別是這個命令使得那個函式被作為一個真正的成員來處理。這是非常有用的，當程式設計記語言本身不支援成員函式的概念時（比如C語言）。

在示例資料夾中的manual.c檔案展示瞭如何使用這個命令。

點選這裡檢視由doxygen生成的相應的文件。

\name (header)

這個命令把註釋塊放到一個成員組的標頭檔案定義中。這個註釋塊應該緊跟著這樣的 //@{ ... //@} 結構，這個結構包含這個組的成員。

\namespace <name>

指明當前註釋塊包含一個名字空間的文件，這個名字空間有一個識別符號 <name>。

\nosubgrouping

這個命令可以放在一個類的文件內部。它可以與成員分組一起使用，這個命令的使用可以避免doxygen把一個成員組當作Public/Protected/Private/……等等小節的子組。

\overload [(函式宣告)]

此命令可用於生成一個過載成員函式下列標準文字：

“這是一個提供便利的過載的成員函式。它與之前函式的區別只在於它們接受的引數不同。”

如果該過載成員函式的文件不是放置在函式宣告或定義的上部，可選的引數會被使用以確定正確的函式。

在當前文件塊內的任何其它的文件都會新增在這個訊息之後。

注1：: 你需要保證確實存在一個較早文件化的成員被這個函式過載。為了阻止文件被排序，你需要把選項SORT_MEMBER_DOCS設定為NO。

注2：: \overload命令在單行註釋裡不起作用。

例如：

class Test 

{

  public:

    void drawRect(int,int,int,int);

    void drawRect(const Rect &amp;r);

};



void Test::drawRect(int x,int y,int w,int h) {}

void Test::drawRect(const Rect &amp;r) {}



/*!\class Test

 *  \brief A short description.

 *   

 *  More text.

 */



/*!\fn void Test::drawRect(int x,int y,int w,int h)

 * This command draws a rectangle with a left upper corner at ( \a x , \a y ),

 * width \a w and height \a h. 

 */



/*! * \overload void Test::drawRect(const Rect &amp;r)

 */

點選這裡檢視由doxygen生成的相應的文件。

\package <name>

指明一個註釋塊包含一個名為<name>的Java包的文件。

\page <名字> (標題)

指出一個註釋塊包含一塊文件，這些文件不是直接與一個特定的類、檔案或成員相關聯。HTML產生器將建立一個單獨的頁面來包含這個文件。 $\mbox{\LaTeX}$ 在章節裡，產生器將新建一個小節。

例如：

/*!\page page1 A documentation page

  Leading text.

  \section sec An example section

  This page contains the subsections \ref subsection1 and \ref subsection2.

  For more info see page \ref page2.

  \subsection subsection1 The first subsection

  Text.

  \subsection subsection2 The second subsection

  More text.

*/



/*!\page page2 Another page

  Even more info.

*/

點選這裡檢視由doxygen生成的相應的文件。

注意：: 引數<名字>只能包含字母和數字的組合。在<名字>引數裡，如果你想使用大寫字母（如MYPAGE1），或者混合大小寫（如MyPage1），你應該設定CASE_SENSE_NAMES的值為YES。然而這隻有當你的檔案系統是大小寫敏感才是可取。否則的話（為了更好的移植性）你應該總是使用小寫字母（如mypage1）來作為<名字>，在所有引用這個頁的地方都只要簡單地使用小寫。

\private

Indicates that the member documented in the comment block is private, i.e., should only be accessed by other members in the same class.

Note that Doxygen automatically detects the protection level of members in object-oriented languages. This command is intended for use only when the language does not support the concept of protection level natively (e.g. C, PHP 4).

For starting a section of private members, in a way similar to the "private:" class marker in C++, use \privatesection.

\property (qualified property name)

Indicates that a comment block contains documentation for a property (either global or as a member of a class). This command is equivalent to \var and \fn.

相關參考: section \fn and \var.

\protected

Indicates that the member documented in the comment block is protected, i.e., should only be accessed by other members in the same or derived classes.

For starting a section of protected members, in a way similar to the "protected:" class marker in C++, use \protectedsection.

\protocol <name> [<header-file>] [<header-name>]

Indicates that a comment block contains documentation for a protocol in Objective-C with name <name>. 這些引數的意義與 \class 命令相同。

\public

Indicates that the member documented in the comment block is public, i.e., can be accessed by any other class or function.

For starting a section of public members, in a way similar to the "public:" class marker in C++, use \publicsection.

\relates <name>

This command can be used in the documentation of a non-member function <name>. It puts the function inside the `related function' section of the class documentation. This command is useful for documenting non-friend functions that are nevertheless strongly coupled to a certain class. It prevents the need of having to document a file, but only works for functions.

例如：

/*! * A String class.

 */ 

  

class String

{

  friend int strcmp(const String &amp;,const String &amp;);

};



/*! * Compares two strings.

 */



int strcmp(const String &amp;s1,const String &amp;s2)

{

}



/*!\relates String

 * A string debug function.

 */

void stringDebug()

{

}

點選這裡檢視由doxygen生成的相應的文件。

\relatesalso <name>

This command can be used in the documentation of a non-member function <name>. It puts the function both inside the `related function' section of the class documentation as well as leaving its normal file documentation location. This command is useful for documenting non-friend functions that are nevertheless strongly coupled to a certain class. It only works for functions.

\showinitializer

By default the value of a define and the initializer of a variable are only displayed if they are less than 30 lines long. By putting this command in a comment block of a define or variable, the initializer is shown unconditionally.

\struct <name> [<header-file>] [<header-name>]

Indicates that a comment block contains documentation for a struct with name <name>. 這些引數的意義與 \class 命令相同。

\typedef (typedef declaration)

Indicates that a comment block contains documentation for a typedef (either global or as a member of a class). This command is equivalent to \var and \fn.

相關參考: section \fn and \var.

\union <name> [<header-file>] [<header-name>]

Indicates that a comment block contains documentation for a union with name <name>. 這些引數的意義與 \class 命令相同。

\var (variable declaration)

Indicates that a comment block contains documentation for a variable or enum value (either global or as a member of a class). This command is equivalent to \typedef and \fn.

相關參考: section \fn and \typedef.

\weakgroup <name> [(title)]

Can be used exactly like \addtogroup, but has a lower priority when it comes to resolving conflicting grouping definitions.

--- Section indicators ---

\attention { attention text }

Starts a paragraph where a message that needs attention may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent \attention commands will be joined into a single paragraph. The \attention command ends when a blank line or some other sectioning command is encountered.

Starts a paragraph where one or more author names may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent \author commands will be joined into a single paragraph. Each author description will start a new line. Alternatively, one \author command may mention several authors. The \author command ends when a blank line or some other sectioning command is encountered.

例如：

/*!\class WindowsNT

 *  \brief Windows Nice Try.

 *  \author Bill Gates

 *  \author Several species of small furry animals gathered together 

 *          in a cave and grooving with a pict.

 *  \version 4.0

 *  \date    1996-1998

 *  \bug It crashes a lot and requires huge amounts of memory.

 *  \bug The class introduces the more bugs, the longer it is used.

 *  \warning This class may explode in your face.

 *  \warning If you inherit anything from this class, you're doomed.

 */



class WindowsNT {};

Click here for the corresponding HTML documentation that is generated by doxygen.

\brief {brief description}

Starts a paragraph that serves as a brief description. For classes and files the brief description will be used in lists and at the start of the documentation page. For class and file members, the brief description will be placed at the declaration of the member and prepended to the detailed description. A brief description may span several lines (although it is advised to keep it brief!). A brief description ends when a blank line or another sectioning command is encountered. If multiple \brief commands are present they will be joined. See section\author for an example.

Synonymous to \short.

\bug { bug description }

Starts a paragraph where one or more bugs may be reported. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent \bug commands will be joined into a single paragraph. Each bug description will start on a new line. Alternatively, one \bug command may mention several bugs. The \bug command ends when a blank line or some other sectioning command is encountered. See section \author for an example.

\cond [<section-label>]

Starts a conditional section that ends with a corresponding \endcond command, which is typically found in another comment block. The main purpose of this pair of commands is to (conditionally) exclude part of a file from processing (in older version of doxygen this could only be achieved using C preprocessor commands).

The section between \cond and \endcond commands can be included by adding its section label to the ENABLED_SECTIONS configuration option. If the section label is omitted, the section will be excluded from processing unconditionally.

For conditional sections within a comment block one should use a \if ... \endif block.

Conditional sections can be nested. In this case a nested section will only be shown if it and its containing section are included.

Here is an example showing the commands in action:

/** An interface */

class Intf

{

  public:

    /** A method */

    virtual void func() = 0;



    /// @cond TEST



    /** A method used for testing */

    virtual void test() = 0;



    /// @endcond

};



/// @cond DEV

/*

 *  The implementation of the interface 

 */

class Implementation : public Intf

{

  public:

    void func();



    /// @cond TEST

    void test();

    /// @endcond



    /// @cond

    /** This method is obsolete and does

     *  not show up in the documentation.

     */

    void obsolete();

    /// @endcond

};



/// @endcond

The output will be different depending on whether or not ENABLED_SECTIONS contains TEST, or DEV

\date { date description }

Starts a paragraph where one or more dates may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent \date commands will be joined into a single paragraph. Each date description will start on a new line. Alternatively, one \date command may mention several dates. The \date command ends when a blank line or some other sectioning command is encountered. See section \author for an example.

\deprecated { description }

Starts a paragraph indicating that this documentation block belongs to a deprecated entity. Can be used to describe alternatives, expected life span, etc.

\details {detailed decription}

Just like \brief starts a brief description, \details starts the detailed description. You can also start a new paragraph (blank line) then the \details command is not needed.

\else

Apache Shiro動態設定許可權可對應訪問路徑

« 上一篇

利用@DynamicInsert和@DynamicUpdate生成動態SQL語句

命令的具體介紹

\addtogroup <name> [(title)]

\callgraph

\callergraph

\category <name> [<header-file>] [<header-name>]

\class <name> [<header-file>] [<header-name>]

\def <name>

\defgroup <name> (group title)

\dir [<path fragment>]

\enum <name>

\example <file-name>

\extends <name>

\file [<name>]

\fn (函式宣告)

\headerfile <header-file> [<header-name>]

\hideinitializer

\implements <name>

\ingroup (<groupname> [<groupname> <groupname>])

\interface <name> [<header-file>] [<header-name>]

\internal

\mainpage [(title)]

\memberof <name>

\name (header)

\namespace <name>

\nosubgrouping

\overload [(函式宣告)]

\package <name>

\page <名字> (標題)

\private

\property (qualified property name)

\protected

\protocol <name> [<header-file>] [<header-name>]

\public

\relates <name>

\relatesalso <name>

\showinitializer

\struct <name> [<header-file>] [<header-name>]

\typedef (typedef declaration)

\union <name> [<header-file>] [<header-name>]

\var (variable declaration)

\weakgroup <name> [(title)]

--- Section indicators ---

\attention { attention text }

\brief {brief description}

\bug { bug description }

\cond [<section-label>]

\date { date description }

\deprecated { description }

\details {detailed decription}

\else

相關推薦