---
# System prepended metadata

title: Comment Format
tags: [doxygen]

---

# Comment Format

###### tags: `doxygen`

## File

### 格式

* `@file <file_name>`
    
    在每個檔案開頭加入此指令，告知doxygen要解析此檔案。若一個專案中有同名檔案，則要加入檔案路徑。

* `@brief`

    在此簡述該檔案之用途。
    
* `@details`

    在此詳述該檔案之用途。
    
### 範例

* 註解
    
    ``` cpp=1
    /// @file main.cpp
    ///
    /// @brief This is a main file.
    ///
    /// @details This file contain one class. \n
    ///          Blablablablabla.
    
    #include <iostream>
    #include <string>
    ...
    ```
    
* 預覽

    *待補*

## Namespace

### 格式

* `@namespace <namespace_name>`
    
    在命名空間之前加入此指令，`<namespace_name>`為該命名空間之名稱。

* `@brief`

    在此簡述該命名空間之用途。
    
* `@details`

    在此詳述該命名空間之用途。
    
### 範例

* 註解
    
    ``` cpp=11
    /// @namespace School
    ///
    /// @brief Namespace of %School 
    ///
    /// @details I'm a namespace. My name is %School.
    namespace School {
        ...
    ```
    
* 預覽

    *待補*

## Constant

### 格式

* `@var <constant_name>`
    
    在常數之前加入此指令，`<constant_name>`為該常數之名稱。

* `@brief`

    在此簡述該常數之用途。
    
* `@details`

    在此詳述該常數之用途。
    
* `///<`
    
    亦可使用此方式，僅為該常數加上簡述，而無詳述。見範例25行。
    
### 範例

* 註解
    
    ``` cpp=18
    /// @var SCHOOL_SIZE
    ///
    /// @brief School size.
    ///
    /// @details You need to set EXTRACT_STATIC=YES to extract static memeber.
    static const int SCHOOL_SIZE = 987;

    static const int CLASS_SIZE = 87; ///< You can just briefly describe this variable.
    ```
    
* 預覽

    *待補*

## Class

### 格式

* `@class <class_name>`
    
    在類別之前加入此指令，`<class_name>`為該類別之名稱。

* `@brief`

    在此簡述該類別之用途。
    
* `@details`

    在此詳述該類別之用途。

### 範例

* 註解
    
    ``` cpp=27
    /// @class   Student
    ///
    /// @brief   This class is about student.
    ///
    /// @details Here is the detailed description. \n
    ///          If you want a new line, you can use '\\n'
    class Student {
    ```
    
* 預覽

    *待補*

## Class Function

### 格式

* `@brief`

    在此簡述該函數之用途。
    
* `@details`

    在此詳述該函數之用途。
    
* `param[in/out/in,out] <param_name>`

    描述該函數的每個參數之用途，可指明該參數為輸入(in)、輸出(out)或同時為輸入及輸出(in,out)。`<param_name>`為該參數之名稱。

* `exception <exception_name>`

    若該函數有例外處理，可加上此指令，並描述該例外。

* `return`

    描述該函數的回傳之物為何。
    
* `sa`

    即See Also。可在此加上與此函數相關之類別、函數、變數等等，只要與此函數有關聯皆可在此加入，doxygen會自動為其加入超連結。

### 範例

* 註解
    
    ``` cpp=34
    public:
        /// @brief   Constructor for Student.
        ///
        /// @details I'm a constructor. I can construct a student...
        ///
        /// @param[in]  f_id   %Student ID. Put a % sign in front of the word to disable AUTOLINK.
        /// @param[out] f_name Student name. \n
        ///             Actually I'm an input, but just suppose I'm an output.
        ///
        /// @return Nothing returned.
        Student(std::string f_id, std::string f_name) : m_id(f_id), m_name(f_name) {
            std::cout << "Hi, I'm " << f_name << "." << std::endl;
        }

    private:
        /// @brief Think something.
        ///
        /// @details I'm a private class function. \n
        ///          If you want doxygen extract me, \n
        ///          please remember set EXTRACT_PRIVATE=YES.
        ///
        /// @param[in,out] f_something Again...suppose it is an in/out parameter. 
        ///
        /// @exception any_exception You can describe some exceptions here.
        ///
        /// @return Nothing returned.
        ///
        /// @sa Student, Student::m_name, Student::Student(). This is see also block.
        void Think(std::string f_something) {
            std::cout << m_name << " is thinking about " << f_something << std::endl;
        }
    ```
    
* 預覽

    *待補*

## Class Variable

### 格式

* `@brief`

    在此簡述該函數之用途。
    
* `@details`

    在此詳述該函數之用途。

### 範例

* 註解
    
    ``` cpp=66
    public:
        std::string m_id; ///< %Student ID.

    private:
        /// @brief %Student name.
        ///
        /// @details Blablabla. \n
        ///          Don't forget to set EXTRACT_PRIVATE=YES.
        std::string m_name;
    ```
    
* 預覽

    *待補*

## Enumeration

### 格式

* `@enum <enum_name>`

    在列舉類別之前加上此指令，`enum_name`為此列舉類別之名稱。
    
* `@brief`

    在此簡述該列舉之用途。
    
* `@details`

    在此詳述該列舉之用途。
    
* `///<`
    
    簡述此列舉中的每個成員，儘量簡短。

### 範例

* 註解
    
    ``` cpp=77
    /// @enum Grade
    ///
    /// @brief I'm an enum.
    ///
    /// @details Blablablablabla.
    enum class Grade {
        ONE,  ///< One grade. Describe each enum value here. 
        TWO,  ///< Two grade.
        THREE ///< Three grade.
    };
    ```
    
* 預覽

    *待補*
    
## Structure

### 格式

* `@struct <struct_name>`

    在結構之前加上此指令，`struct_name`為此結構之名稱。
    
* `@brief`

    在此簡述該結構之用途。
    
* `@details`

    在此詳述該結構之用途。
    
* `///<`
    
    簡述此結構中的每個成員，儘量簡短。

### 範例

* 註解
    
    ``` cpp=88
    /// @struct Exam
    ///
    /// @brief I'm a struct.
    ///
    /// @details I'm used to record the scores.
    struct Exam {
        int Chinese; ///< Chinese score. Briefly describe each variable here.
        int English; ///< English score. Do not more than one line.
        int Math;    ///< Math score.
    };
    ```
    
* 預覽

    *待補*

## 完整範例

``` cpp=
/// @file main.cpp
///
/// @brief This is a main file.
///
/// @details This file contain one class. \n
///          Blablablablabla.

#include <iostream>
#include <string>

/// @namespace School
///
/// @brief Namespace of %School 
///
/// @details I'm a namespace. My name is %School.
namespace School {

/// @var SCHOOL_SIZE
///
/// @brief School size.
///
/// @details You need to set EXTRACT_STATIC=YES to extract static memeber.
static const int SCHOOL_SIZE = 987;

static const int CLASS_SIZE = 87; ///< You can just briefly describe this variable.

/// @class   Student
///
/// @brief   This class is about student.
///
/// @details Here is the detailed description. \n
///          If you want a new line, you can use '\\n'
class Student {
public:
    /// @brief   Constructor for Student.
    ///
    /// @details I'm a constructor. I can construct a student...
    ///
    /// @param[in]  f_id   %Student ID. Put a % sign in front of the word to disable AUTOLINK.
    /// @param[out] f_name Student name. \n
    ///             Actually I'm an input, but just suppose I'm an output.
    ///
    /// @return Nothing returned.
    Student(std::string f_id, std::string f_name) : m_id(f_id), m_name(f_name) {
        std::cout << "Hi, I'm " << f_name << "." << std::endl;
    }

private:
    /// @brief Think something.
    ///
    /// @details I'm a private class function. \n
    ///          If you want doxygen extract me, \n
    ///          please remember set EXTRACT_PRIVATE=YES.
    ///
    /// @param[in,out] f_something Again...suppose it is an in/out parameter. 
    ///
    /// @exception any_exception You can describe some exceptions here.
    ///
    /// @return Nothing returned.
    ///
    /// @sa Student, Student::m_name, Student::Student(). This is see also block.
    void Think(std::string f_something) {
        std::cout << m_name << " is thinking about " << f_something << std::endl;
    }

public:
    std::string m_id; ///< %Student ID.
   
private:
    /// @brief %Student name.
    ///
    /// @details Blablabla. \n
    ///          Don't forget to set EXTRACT_PRIVATE=YES.
    std::string m_name;
};

/// @enum Grade
///
/// @brief I'm an enum.
///
/// @details Blablablablabla.
enum class Grade {
    ONE,  ///< One grade. Describe each enum value here. 
    TWO,  ///< Two grade.
    THREE ///< Three grade.
};

/// @struct Exam
///
/// @brief I'm a struct.
///
/// @details I'm used to record the scores.
struct Exam {
    int Chinese; ///< Chinese score. Briefly describe each variable here.
    int English; ///< English score. Do not more than one line.
    int Math;    ///< Math score.
};

int main(int argc, char* argv[]) {
    Student alan("9487", "Alan");

    return 0;
}

}

```