linux平臺使用doxygen生成專案文件
阿新 • • 發佈：2018-11-07
Doxygen簡介
Doxygen是一種開源跨平臺的，以類似JavaDoc風格描述的文件系統，完全支援C、C++、Java、Objective-C和IDL語言，部分支援PHP、C#。註釋的語法與Qt-Doc、KDoc和JavaDoc相容。Doxygen可以從一套歸檔原始檔開始，生成HTML格式的線上類瀏覽器，或離線的LATEX、RTF參考手冊。
更多詳細內容請檢視 Doxygen官網。
安裝Doxygen
本篇只介紹linux平臺的使用方法，Doxygen同樣支援Window和MacOS系統。
安裝方式：
-
直接命令列安裝
sudo apt-get install doxygen
sudo apt-get install graphviz -
下載Doxygen開源版本安裝包，自行解壓安裝
Doxygen開源版本
自定義Doxygen專案配置
使用Doxygen命令生成配置模板檔案
doxygen -g doc.dot
根據工程的目錄樹來配置doc.dot檔案，參考目錄樹如下：
$ tree
.
├── doc.dot
├── include
│ └── dev_sdk.h
├── logo.png
├── Readme.html
├── README.md
└── reference
include目錄存放程式碼標頭檔案，reference目錄用來存放生成的html檔案。
配置Doxygen模板檔案
只需要修改基本的欄位，即可完成配置
# 專案名稱，顯示在html首頁
PROJECT_NAME = "Device SDK APIs"
# 專案版本號，顯示在html首頁
PROJECT_NUMBER = "ver: 2.3.0"
# 專案logo圖片，顯示在html首頁
PROJECT_LOGO = logo.png
# 輸出目錄，用來存放匯出的html和配置檔案
OUTPUT_DIRECTORY = reference
# 程式碼使用的語言，這裡使用c語言
OPTIMIZE_OUTPUT_FOR_C = 更多高階用法，請參考doc.dot註釋自行研究。
生成Doxygen專案文件
程式碼註釋規範
Doxygen支援多種程式碼規範，這裡舉例一種常用規範
/**
* sdk information
**/
struct dev_sdk_info {
char *device_id; /**< device id */
char *device_key; /**< device key */
int device_type; /**< device type */
};
/**
* @fn int dev_sdk_set_volume(int volume)
* @brief set device volume
*
* @param [in] volume - input volume value
* @return On success, return 0. On error, return error code.
**/
extern int dev_sdk_set_volume(int volume);
生成html文件
修改好doc.dot配置檔案後，使用命令生成html文件：
doxygen doc.dot
執行成功後，再reference目錄下會自動生成html配置檔案，開啟reference/index.html檔案即可檢視。
為html文件增加索引檔案
方便工程的整體性功能，可以在專案主目錄增加Readme.html索引檔案，將連結指向reference/index.html，如下示例：
<!DOCTYPE html>
<html>
<head>
<title>Readme.html</title>
<style>
body {
width: 35em;
margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif;
}
</style>
</head>
<body>
<h1>Device SDK API manual</h1>
<p><a href="reference/html/index.html">API reference guide</a> (./reference/html/index.html) </p>
</body>
</html>
詳細的程式碼和配置請參考 github工程 doxygen-template。
開啟效果：
