doxygen註釋語法（一）：JavaDoc註釋風格、檔案頭和類註釋
1、JavaDoc註釋風格
註釋風格有多種，本文采用JavaDoc註釋風格
Java風格如下，註釋第一行為/**,然後中間每一行註釋以*號開始，且為了方便閱讀，一般*後空一字元,最後一行以*/結束，*與上一行*對齊。
/**
*
*
*
*/2、簡要註釋和詳細註釋
註釋應寫在對應的函式或變數前面。JavaDoc風格下，自動會把第一個句號 "." 前的文字作為簡要註釋，後面的為詳細註釋。你也可以用空行把簡要註釋和詳細註釋分開。注意要設定JAVADOC_AUTOBRIEF設為YES。@brief 表面後面為簡要註釋，當然，僅僅寫下下面幾行字，在說明文件中什麼都不會出現，必須表明是對什麼的註釋，比如是對檔案還是類還是成員的註釋。
/**
* @brief 簡要註釋Brief Description.
*
* 這裡是詳細註釋Detailed Description
*/
3、註釋從高階層次到細節層次
先從檔案開始註釋，然後是所在檔案的全域性函式、結構體、列舉變數、名稱空間→名稱空間中的類→成員函式和成員變數。
4、檔案頭註釋@file
因為檔案不在任何東西里面，所以不能像類、函式等在上方放註釋，只能用@file方式定義，其格式如下
/** @file [file‐name] * @brief brief description * @author <list of authors> * [@author <authors description>] * @date <date> * @version <version number> * @note * detailed description */
[]表示可選，{}表示重複0到N次，<>表示必須引數
一般@file後我們空著，Doxygen會預設為是@file所在檔案的檔名。
@brief為建明註釋
@aothor為作者列表
@date為日期
@version為版本號
@note為註解
上面五項共同構成檔案的詳細描述，考慮如下注釋
/** @file * @brief 分頁細節層次（LOD）. * @author Archie * @date June 29,2013 * @version 1.0.0.0 * @note * 分頁細節層次（LOD）是Level Of Details */ #include "stdafx.h" #include <osgViewer/Viewer> #include <osg/Node> #include <osg/Geode> #include <osg/Group> #include <osg/PagedLOD> #include <osg/PositionAttitudeTransform> #include <osg/MatrixTransform> #include <osgDB/ReadFile> #include <osgDB/WriteFile> #include <osgGA/TrackballManipulator> #include <osgUtil/Optimizer> #include <iostream>
其中的詳細描述如圖所示
文件整體結構如下組織
- 首先是簡要說明 ，點選旁邊的“更多”可以檢視詳細描述
- 接著是包含的檔案列表
- 然後是引用關係圖
- 如果勾選了前面的原始碼選項還會附帶原始碼
- 然後是全域性函式等
- 最後是詳細描述
其中使用graphviz生成的引用關係圖如下，點選任意檔案可檢視此檔案的原始碼
5、類註釋
類註釋的格式
/**
* @class <class‐name> [header‐file] [<header‐name]
* @brief brief description
* @author <list of authors>
* @note
* detailed description
*/
header‐file是類宣告所在的標頭檔案名字，header‐name是要顯示的連結文字，一般為標頭檔案的真實路徑在include<XX>中顯示。
/**
* @class CTest PagedLOD.cpp CTest.h
* @brief 測試
* @author Archie
* @note
* 測試Doxygen的類註釋
*/
class CTest
{
public:
private:
}
以上程式碼仍是在PagedLOD.cpp中定義，為了演示方便，CTest.h為假定的路徑名（並未建立）。
點選CTest，進入類CTest介紹，其中CTest前的C表示索引字母為C，點選類索引可以根據索引字母查詢類。
------------------
類索引根據類的首字母進行索引排序
