doxygen C++

標註總述

下載國外的源代碼，往往能看到附帶的說明文檔，文檔都有詳細的說明，大部分文檔都可以通過doxygen這個跨平臺軟件生成，doxygen並不能隨便讀取你的C++的註釋,必須按照一定的規則才能生成，所以在編寫代碼時，一定要按照標準寫註釋，否則會爲以後帶來許多麻煩

下面介紹C++的標註寫法，c++不推薦c語言式的/* */風格註釋，這裏，除了文件頭使用這種註釋外其餘到使用C++風格的註釋。

先看看總述：

文件頭：

[cpp] view plaincopy

1.   

[cpp] view plaincopy

1. /*! 

2. * \file Ctext.h 

3. * \brief 概述  

4. *  

5. *詳細概述  

6. *  

7. * \author 作者名字 

8. * \version 版本號(maj.min，主版本.分版本格式)  

9. * \date 日期  

10. */  

命名空間：

[cpp] view plaincopy

1. /// \brief 命名空間的簡單概述   

2. ///   

3. ///命名空間的詳細概述  

4. namespace text  

5. {  

6.  ……  

7. }  

類說明：

[cpp] view plaincopy

1. /// \brief Ctext的doxygen測試  

2. ///  

3. /// 作doxygen測試用  

4. class Ctext  

5. {  

6. }  

函數標註
   方法1：

[cpp] view plaincopy

1. /// \brief 函數簡要說明-測試函數  

2. /// \param n1 參數1  

3. /// \param c2 參數2  

4. /// \return 返回說明  

5. bool text(int n1,Ctext c2);  

   方法2：

[cpp] view plaincopy

1. /// \brief 函數簡要說明-測試函數  

2. ///   

3. /// 函數詳細說明，這裏寫函數的詳細說明信息，說明可以換行  

4. /// ，如這裏所示，同時需要注意的是詳細說明和簡要說明之間必須空一行  

5. /// ，詳細說明之前不需要任何標識符  

6. /// \param n1 參數1說明  

7. /// \param c2 參數2說明  

8. /// \return 返回說明  

9. /// \see text  

10. bool text2(int n1,Ctext c2);  

變量及枚舉
 

[cpp] view plaincopy

1. int m_a;     ///< 成員變量1m_a說明  

2.  double m_b; ///< 成員變量2m_b說明  

3.   

4.   

5.  /// \brief 成員變量m_c簡要說明  

6.  ///  

7.  /// 成員變量m_c的詳細說明，這裏可以對變量進行  

8.  ///詳細的說明和描述，具體方法和函數的標註是一樣的  

9.  float m_c;  

10.   

11.   

12.  /// \brief xxx枚舉變量的簡要說明  

13.  ///  

14.  /// xxx枚舉變量的詳細說明--枚舉變量的詳細說明和函數的詳細說明  

15.  ///的寫法是一致的。每個枚舉變量下可以進行單獨說明  

16.  enum{  

17.      em_1,///< 枚舉值1的說明  

18.      em_2,///< 枚舉值2的說明  

19.      em_3 ///< 枚舉值3的說明  

20.  };  

1.文件頭說明文件頭說明按照如下格式寫

[cpp] view plaincopy

1. /*! 

2. * \file Ctext.h 

3. * \brief 概述  

4. *  

5. *詳細概述  

6. *  

7. * \author 作者,包含email等  

8. * \version 版本號(maj.min，主版本.分版本格式)  

9. * \date 日期  

10. */  

上註釋等下於下面這種寫法

[cpp] view plaincopy

1. /*! 

2.  \file Ctext.h 

3. \brief 概述  

4. 詳細概述  

5. \author 作者,包含email等  

6. \version 版本號(maj.min，主版本.分版本格式)  

7. \date 日期  

8. */  

對於vs編譯器可能中間那行*號比較麻煩，可以不寫，對於Qt這種要去掉中間的*號反而是件麻煩事就不用去掉
用doxygen生成註釋如下效果

2. 命名空間

命名空間說明如下寫

[cpp] view plaincopy

1. /// \brief 命名空間的簡單概述   

2. ///   

3. ///命名空間的詳細概述  

4. namespace text  

5. {  

6.   

7. }  

doxygen的說明寫法都是類似於

[cpp] view plaincopy

1. /// \brief  

2. ///   

3. ///   

以下將會見到很多這樣的寫法
上註釋的doxygen效果如下


3. 類說明
類的註釋和函數一樣，

[cpp] view plaincopy

1. /// \brief Ctext的doxygen測試  

2. ///  

3. /// 作doxygen測試用  

4. class Ctext  

5. {  

6. }  

上註釋用doxygen生成文檔效果如下：

4.函數註釋原則

函數詳細註釋位於頭文件，cpp文件只對函數做簡明註釋
cpp文件不做///的註釋，否則會和頭文件重疊

4.1 函數簡要說明註釋方法1：

[cpp] view plaincopy

1. /// \brief 函數簡要說明-測試函數  

2. /// \param n1 參數1  

3. /// \param c2 參數2  

4. /// \return 返回說明  

5. bool text(int n1,Ctext c2);  

簡要註釋此註釋會讓doxygen生成函數簡要說明和參數說明
生成結果如：


4.2 函數簡要說明+詳細說明

[cpp] view plaincopy

1. /// \brief 函數簡要說明-測試函數  

2. ///   

3. /// 函數詳細說明，這裏寫函數的詳細說明信息，說明可以換行  

4. /// ，如這裏所示，同時需要注意的是詳細說明和簡要說明之間必須空一行  

5. /// ，詳細說明之前不需要任何標識符  

6. /// \param n1 參數1說明  

7. /// \param c2 參數2說明  

8. /// \return 返回說明  

9. bool text2(int n1,Ctext c2);  

上註釋用doxygen生成文檔效果如下：



4.3 不帶簡要說明的函數標註

[cpp] view plaincopy

1. /// 函數說明-測試函數  

2. ///   

3. /// 函數詳細說明，這裏寫函數的詳細說明信息，說明可以換行  

4. /// ，如這裏所示，同時需要注意的是詳細說明和簡要說明之間必須空一行  

5. /// ，詳細說明之前不需要任何標識符  

6. /// \param n1 參數1說明  

7. /// \param c2 參數2說明  

8. /// \return 返回說明  

9. bool text3(int n1,Ctext c2);  

上註釋用doxygen生成文檔效果如下：

這裏沒有說明



4.4 帶參見的寫法

[cpp] view plaincopy

1. /// \brief 函數說明-測試函數4  

2. /// \param n1 參數1說明  

3. /// \param c2 參數2說明  

4. /// \return 返回說明  

5. /// \see text3 text2 text  

6. bool text4(int n1,Ctext c2);  

上註釋用doxygen生成文檔效果如下：



\see 上可以帶中文等說明，doxygen會自動識別代碼裏存在的函數

5.變量註釋
變量註釋用///< 對變量進行說明，對於詳細信息可以加\brief
  

[cpp] view plaincopy

1. int m_a;     ///< 成員變量1m_a說明  

2. double m_b; ///< 成員變量2m_b說明  

3.   

4. /// \brief 成員變量m_c簡要說明  

5. ///  

6. /// 成員變量m_c的詳細說明，這裏可以對變量進行  

7. ///詳細的說明和描述，具體方法和函數的標註是一樣的  

8. float m_c;  

如果變量需要詳細說明的可已按照m_c的寫法寫，注意，m_b和m_c之間一定需要空行，否則會導致m_b的簡述消失
上註釋用doxygen生成文檔的具體效果如下





6.枚舉
枚舉變量的標註方法如下

[cpp] view plaincopy

1. /// \brief xxx枚舉變量的簡要說明  

2. ///  

3. /// xxx枚舉變量的詳細說明--枚舉變量的詳細說明和函數的詳細說明  

4. ///的寫法是一致的。每個枚舉變量下可以進行單獨說明  

5. enum{  

6.     em_1,///< 枚舉值1的說明  

7.     em_2,///< 枚舉值2的說明  

8.     em_3 ///< 枚舉值3的說明  

9. };  

枚舉的總體說明和函數的寫法一致，每個枚舉變量的說明和變量的說明寫法一致
上註釋用doxygen生成效果如下：

7.doxygen的設置和中文問題
7.1 生成私有成員
如果想生成私有成員（doxygen默認不生成私有成員），可以如下設置
選擇Expert標籤的Build項，勾選EXTRACT_PRIVATE即可

7.2 中文問題中文有時候是亂碼
對於vs2010的文檔，默認是gb2312，可以設置
Expert標籤的Project項目的DOXYFILE_ENCODING 爲 GB18030
INPUT_ENCODING 爲 GB18030

另外Project項目的生成語言（OUTPUT_LANGUAGE）選擇Chinese

對於其他的代碼文件如果中文亂碼，可以用文本編輯器轉換代碼文本編碼爲UTF-8帶BOM的（注意這有可能影響代碼，所以轉換編碼時要備份），再進行導出。

8.vs2008、vs2010 及以上IDE的快速標註方法

vs2010 等編譯器並不能像Qt Creator那樣生成上述標註樣式，但是可以集成到vs的工具欄裏，集成方法如下圖所示：

這樣在標註時可以直接從工具箱拖曳了，非常方便

附：Ctext.h

[cpp] view plaincopy

1. /*! 

2. * \file Ctext.h 

3. * \brief 概述  

4. *  

5. *詳細概述  

6. *  

7. * \author 作者,包含email等  

8. * \version 版本號(maj.min，主版本.分版本格式)  

9. * \date 日期  

10. */  

11.   

12. #pragma once  

13. /// \brief 命名空間的簡單概述   

14. ///   

15. ///命名空間的詳細概述  

16. namespace text  

17. {  

18.   

19. }  

20.   

21. /// \brief Ctext的doxygen測試  

22. ///  

23. /// 作doxygen測試用  

24. class Ctext  

25. {  

26. public:  

27.     Ctext(void);  

28.     ~Ctext(void);  

29.     /// \brief 函數簡要說明-測試函數  

30.     /// \param n1 參數1說明  

31.     /// \param c2 參數2說明  

32.     ///    \return 返回說明  

33.     bool text(int n1,Ctext c2);  

34.     /// \brief 函數簡要說明-測試函數  

35.     ///   

36.     /// 函數詳細說明，這裏寫函數的詳細說明信息，說明可以換行  

37.     /// ，如這裏所示，同時需要注意的是詳細說明和簡要說明之間必須空一行  

38.     /// ，詳細說明之前不需要任何標識符  

39.     /// \param n1 參數1說明  

40.     /// \param c2 參數2說明  

41.     ///    \return 返回說明  

42.     bool text2(int n1,Ctext c2);  

43.     /// 函數說明-測試函數  

44.     ///   

45.     /// 函數詳細說明，這裏寫函數的詳細說明信息，說明可以換行  

46.     /// ，如這裏所示，同時需要注意的是詳細說明和簡要說明之間必須空一行  

47.     /// ，詳細說明之前不需要任何標識符  

48.     /// \param n1 參數1說明  

49.     /// \param c2 參數2說明  

50.     ///    \return 返回說明  

51.     bool text3(int n1,Ctext c2);  

52.     /// \brief 函數說明-測試函數4  

53.     /// \param n1 參數1說明  

54.     /// \param c2 參數2說明  

55.     ///    \return 返回說明  

56.     /// \see text3 text2 text  

57.     bool text4(int n1,Ctext c2);  

58.   

59.     int m_a;     ///< 成員變量1m_a說明  

60.     double m_b; ///< 成員變量2m_b說明  

61.   

62.     /// \brief 成員變量m_c簡要說明  

63.     ///  

64.     /// 成員變量m_c的詳細說明，這裏可以對變量進行  

65.     ///詳細的說明和描述，具體方法和函數的標註是一樣的  

66.     float m_c;  

67.   

68.     /// \brief xxx枚舉變量的簡要說明  

69.     ///  

70.     /// xxx枚舉變量的詳細說明--枚舉變量的詳細說明和函數的詳細說明  

71.     ///的寫法是一致的。每個枚舉變量下可以進行單獨說明  

72.     enum{  

73.         em_1,///< 枚舉值1的說明  

74.         em_2,///< 枚舉值2的說明  

75.         em_3 ///< 枚舉值3的說明  

76.     };  

77. };