1. 程式人生 > >linux平臺使用doxygen生成專案文件

linux平臺使用doxygen生成專案文件

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  =
YES # 匯入的程式碼路徑,多個路徑使用空格隔開 INPUT = ./include # 檔案型別,如 *.c *.cpp *.h FILE_PATTERNS = *.h # 是否依次查詢子路徑 RECURSIVE = YES # 是否生成Latex,這樣不使用latex,只需要html GENERATE_LATEX = NO

更多高階用法,請參考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

開啟效果:
索引

文件