# 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;
}
}
```
Sign in with Wallet
Connect another wallet