【C&C++】Doxygen - C++項目的文檔生成工具

背景

在進行Amazon AVS C++ SDK的深度開發和學習時候經常會看到Amazon AVS官方的API說明文檔，第一感覺是就是一個字***“好”***

Amazon AVS C++ SDK 官方的API說明文檔部分截圖,

在初步調研後，該文檔是通過doxygen這一工具進行生成的.

是以希望能通過這篇文章能讓更多的人開始基于doxygen進行C/C++代碼的API說明文檔的自動生成.

doxygen官網連結

另外本文接下來所給出的例子都是基于Ubuntu 20.4下的.

doxygen 的安裝和常用指令介紹

doxygen 的安裝

在這裡我是直接指令行doxygen的安裝，

直接使用apt-get install指令進行安裝

sudo apt-get install doxygen
           

在成功安裝後，運作doxygen -v進行版本确認. 我這裡用的是1.8.13

➜  test doxygen -v
1.8.13
➜  test 
           

常用指令介紹

doxygen -g  //自動生成doxygen配置檔案Doxyfile
 doxygen configName //configName需要包含檔案路徑
           

預設情況執行doxygen -g 會報錯，

sh: dot: not found
           

需要安裝graphviz指令，這是因為doxygen依賴graphviz進行繪圖.

sudo apt-get install graphviz
           

如何使用doxygen進行document的生成

運作 doxygen -g

在執行doxygen -g後，該目錄下會自動生成doxygen配置檔案Doxyfile.

Doxyfile就是doxygen 所遵循的配置檔案.

然後需要對配置檔案進行一些修改,

INPUT   = or += 需要進行生成Doc的源檔案路徑

RECURSIVE 需要配置為 YES，代表需要進行子目錄的搜尋

OUTPUT_DIRECTORY  配置輸出的目錄

EXTRACT_ALL = yes
EXTRACT_PRIVATE = yes
EXTRACT_STATIC = yes

# USE_MDFILE_AS_MAINPAGE  添加MainPage的内容，可以使Markdown格式檔案

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md
           

最後在Doxyfile檔案所在的目錄運作doxygen ./Doxyfile

➜  Embedded-Linux-Utils-Library git:(master) ✗ doxygen ./Doxyfile 
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for msc files...
Searching for dia files...
...
           

然後會在OUTPUT_DIRECTORY 所指定的目錄輸出document的相關檔案

➜  Embedded-Linux-Utils-Library git:(master) ✗ ls /tmp/docs/     
html  latex

           

最後通過浏覽器打開html下的index.html這一檔案, 進行API檔案的閱讀.

示例示範

接下來會基于Ubuntu 示範下Doxygen的使用.

在D-Bus C++ Client實作後，基于該代碼倉庫輸出本示例