得不會的代碼注釋工具——doxygen

下載

官網(wǎng)下載二進(jìn)制或者直接用yum或apt工具下載。

使用流程

• 進(jìn)入項目目錄生成doxygen配置文件
• doxygen -g
• 修改doxygen配置文件
• # 程序文檔輸出目錄 OUTPUT_DIRECTORY = doc/ # 程序文檔語言環(huán)境 OUTPUT_LANGUAGE = Chinese # 如果是制作 C 程序文檔，該選項必須設(shè)為 YES，否則默認(rèn)生成 C++ 文檔格式 OPTIMIZE_OUTPUT_FOR_C = YES # 對于使用 typedef 定義的結(jié)構(gòu)體、枚舉、聯(lián)合等數(shù)據(jù)類型，只按照 typedef 定義的類型名進(jìn)行文檔化 TYPEDEF_HIDES_STRUCT = YES # 在 C++ 程序文檔中，該值可以設(shè)置為 NO，而在 C 程序文檔中，由于 C 語言沒有所謂的域/名字空間這樣的概念，所以此處設(shè)置為 YES HIDE_SCOPE_NAMES = YES # 讓 doxygen 靜悄悄地為你生成文檔，只有出現(xiàn)警告或錯誤時，才在終端輸出提示信息 QUIET = YES # 只對頭文件中的文檔化信息生成程序文檔 FILE_PATTERNS = *.h # 遞歸遍歷當(dāng)前目錄的子目錄，尋找被文檔化的程序源文件 RECURSIVE = YES # 示例程序目錄 EXAMPLE_PATH = example/ # 示例程序的頭文檔 (.h 文件) 與實現(xiàn)文檔 (.c 文件) 都作為程序文檔化對象 EXAMPLE_PATTERNS = *.c \ *.h # 遞歸遍歷示例程序目錄的子目錄，尋找被文檔化的程序源文件 EXAMPLE_RECURSIVE = YES # 允許程序文檔中顯示本文檔化的函數(shù)相互調(diào)用關(guān)系 REFERENCED_BY_RELATION = YES REFERENCES_RELATION = YES REFERENCES_LINK_SOURCE = YES # 不生成 latex 格式的程序文檔 GENERATE_LATEX = NO # 在程序文檔中允許以圖例形式顯示函數(shù)調(diào)用關(guān)系，前提是你已經(jīng)安裝了 graphviz 軟件包 HAVE_DOT = YES CALL_GRAPH = YES CALLER_GRAPH = YES #讓doxygen從配置文件所在的文件夾開始，遞歸地搜索所有的子目錄及源文件 RECURSIVE = YES #在最后生成的文檔中，把所有的源代碼包含在其中 SOURCE BROWSER = YES $這會在HTML文檔中，添加一個側(cè)邊欄，并以樹狀結(jié)構(gòu)顯示包、類、接口等的關(guān)系 GENERATE TREEVIEW ＝ ALL EXTRACT_ALL：這個標(biāo)記告訴 doxygen，即使各個類或函數(shù)沒有文檔，也要提取信息。必須把這個標(biāo)記設(shè)置為 Yes。 EXTRACT_PRIVATE：把這個標(biāo)記設(shè)置為 Yes。否則，文檔不包含類的私有數(shù)據(jù)成員。 EXTRACT_STATIC：把這個標(biāo)記設(shè)置為 Yes。否則，文檔不包含文件的靜態(tài)成員（函數(shù)和變量）。
• 生成文檔
• doxygen ./Doxyfile

注釋規(guī)則

項目注釋

項目注釋塊用于對項目進(jìn)行描述，每個項目只出現(xiàn)一次，一般可以放在main.c主函數(shù)文件頭部。對于其它類型的項目，置于定義項目入口函數(shù)的文件中。對于無入口函數(shù)的項目，比如靜態(tài)庫項目，置于較關(guān)鍵且不會被外部項目引用的文件中。 項目注釋塊以“/** @mainpage”開頭，以“*/”結(jié)束。包含項目描述、及功能描述、用法描述、注意事項4個描述章節(jié)。 項目描述章節(jié)描述項目名稱、作者、代碼庫目錄、項目詳細(xì)描述4項內(nèi)容，建議采用HTML的表格語法進(jìn)行對齊描述。 功能描述章節(jié)列舉該項目的主要功能。 用法描述章節(jié)列舉該項目的主要使用方法，主要針對動態(tài)庫、靜態(tài)庫等會被其它項目使用的項目。對于其它類型的項目，該章節(jié)可省略。 注意事項章節(jié)描述該項目的注意事項、依賴項目等相關(guān)信息

/**@mainpage  
* @section   項目詳細(xì)描述
*
* @section   功能描述  
* 
* @section   用法描述 
* 

**********************************************************************************
*/

項目注釋也可以使用markdown文件作為主頁，通過指定md文件路徑來配置。

USE_MDFILE_AS_MAINPAGE = doc/readme.md

若markdown文件里包含圖片，可能會出現(xiàn)圖片無法顯示的情況，這個時候需先檢查圖片路徑是否正確，同時還需要在doxyfile中添加圖片路徑方可顯示。

IMAGE_PATH             = ./doc/images 

文件注釋

/**
 * @file 文件名
 * @brief 簡介
 * @details 細(xì)節(jié)
 * @mainpage 工程概覽
 * @author 作者
 * @version 版本號
 * @date 年-月-日
 */

全局常量/變量/宏定義/結(jié)構(gòu)體定義/類定義的注釋

/// 緩存大小
#define BUFSIZ 1024*4
#define BUFSIZ 1024*4 ///< 緩存大小

函數(shù)注釋

/**
 * @brief 函數(shù)簡介
 *
 * @param 形參 參數(shù)說明
 * @param 形參 參數(shù)說明
 * @return 返回值說明
*/

reference

1. https://blog.srefan.com/2020/05/doxygen-generate-docs/

述

nginx的作用不在此贅述，下面主要記錄部分簡單地使用場景。以下基于“ubuntu 18.04 server”版本驗證。

適用場景：

• 統(tǒng)一鑒權(quán)
• 目錄重定向
• 絕對相對路徑
• 服務(wù)處于NAT后（外部端口和內(nèi)部端口不一致）

非適用場景：

• 不同端口區(qū)分不同服務(wù)，參考創(chuàng)建即可

軟件

安裝軟件：需要使用apache2-utils中的htpasswd

sudo apt-get install nginx
sudo apt install apache2-utils

查看服務(wù)狀態(tài)： +號說明服務(wù)處于up狀態(tài)

service --status-all
......
[ + ] nginx
......

修改配置：具體如何修改見后面章節(jié)

sudo vi /etc/nginx/sites-enabled/default

重啟nginx服務(wù)：修改配置后，需要重啟nginx

service nginx restart

統(tǒng)一鑒權(quán) | 目錄重定向 | 絕對和相對路徑

使用要求：

1. 外網(wǎng)服務(wù)器僅開放一個端口9999，該端口需要實現(xiàn)多種web服務(wù)
2. web服務(wù)需要進(jìn)行鑒權(quán)服務(wù)

設(shè)計要求：

1. 上面的需求可以通過nginx反向代理實現(xiàn)
2. 需要配置服務(wù)器，使外部端口9999映射到nginx服務(wù)器的8081端口（8081端口可以按需自定義）
3. 通過訪問不同的url實現(xiàn)訪問不同的服務(wù)（如下表）
4. 鑒權(quán)方式可以使用htpasswd來實現(xiàn)
5. 為了跳轉(zhuǎn)正常，有的需要絕對目錄有的需要相對目錄

• $wanip: 外部IP地址
• 9999：外部端口
• $nginxip：外部映射到內(nèi)部的nginx地址（多數(shù)應(yīng)用或路由器都可以配置）
• 8081：外部映射到內(nèi)部的端口（多數(shù)應(yīng)用或路由器都可以配置）
• $hostip:內(nèi)網(wǎng)部署的服務(wù)地址，可以是在不同的服務(wù)器上
• 666或777：內(nèi)網(wǎng)部署的服務(wù)端口

nginx配置: /etc/nginx/sites-enabled/default 文件內(nèi)容

server {
        listen 8081;
        server_name localhost;
        location ^~ /source/ {
                auth_basic              "source";
                auth_basic_user_file    /home/wsk/htpasswd.conf;
                proxy_pass              http://127.0.0.1:666/;
                proxy_set_header        X-Forwarded-For $remote_addr;
                proxy_set_header        Host $host;
        }
        location ^~ /git/ {
                auth_basic              "git";
                auth_basic_user_file    /home/wsk/htpasswd.conf;
                proxy_pass              http://127.0.0.1:777;
                proxy_set_header        X-Forwarded-For $remote_addr;
                proxy_set_header        Host $host;
        }
}

注意：

1.因為條件有限，上面的配置，并不包含NAT的過程。如果服務(wù)處于NAT后，上面的配置需要做如下變更：其中9999對應(yīng)的是外部的端口

                 proxy_set_header Host $host:9999;

2.location ^~中的^~為匹配前綴路徑，詳見參考

增加賬號:

touch htpasswd.conf (首次執(zhí)行必選)
htpasswd -b htpasswd.conf $usrname $passwd

創(chuàng)建source對應(yīng)的服務(wù)：

1. 以開源代碼simple-tftp為例，通過doxygen生成html(doxygen如何使用，見我的博客), html存放路徑: wsk@wsk:~/nginx/source/simple-tftp/html
2. 通過python創(chuàng)建http服務(wù): sudo python3 -m http.server 666 (首先需要cd到上面目錄中)

創(chuàng)建git對應(yīng)的服務(wù)：

1. 以開源代碼simple-tftp為例，直接通過創(chuàng)建http服務(wù)sudo python3 -m http.server 777
2. git服務(wù)使用的相對路徑，所以創(chuàng)建http服務(wù)的路徑必須包含git目錄

帶路徑訪問

訪問source: 第一次訪問的時候，會先進(jìn)行鑒權(quán)，當(dāng)鑒權(quán)成功后才能繼續(xù)訪問重定向的網(wǎng)站

訪問git服務(wù): 如果第一次訪問source已經(jīng)輸入過密碼了，這次訪問git就不需要再次輸入。

參考

• nginx反向代理proxy_pass絕對路徑和相對路徑 - 簡書
• 一文徹底讀懂nginx中的location指令 - 知乎

提示

為了更好的閱讀體驗,建議訪問個人首發(fā)地址: nginx應(yīng)用 反向代理，統(tǒng)一鑒權(quán)，目錄重定向 - whilewell - 博客園

、前言

以前，我們學(xué)C語言的時候，多多少少都查過一些標(biāo)準(zhǔn)庫函數(shù)吧。這里介紹查找C語言的標(biāo)準(zhǔn)庫函數(shù)的兩種方法：一種方法是直接到http://www.cplusplus.com這個網(wǎng)站上去查看：

這里覆蓋了C語言標(biāo)準(zhǔn)庫中的所有函數(shù)，給出了每個函數(shù)的介紹并且都給出了具體的用法示例，比如：

只不過都是英文的說明，可見英文的重要性。

另一種方法是，找一些離線的文檔，網(wǎng)上有不少人整理了一些離線的文檔，比如.chm格式（已編譯的幫助文件）的文檔：

里面大概是這樣子的：

也可以很方便的查找每個函數(shù)的用法，但是，這里面的不是很全，所以查找C標(biāo)準(zhǔn)庫函數(shù)還是建議到http://www.cplusplus.com上面去查找。

本文分享的重點就是.chm文件的制作。最近需要對自己的一些代碼做一些整理，發(fā)現(xiàn)整理成.chm文件是個不錯的選擇，.chm文件可以根據(jù)我們的代碼生成，下面把生成.chm文件的方法分享給大家。

二、制作.chm文件的工具

需要三個工具：doxygen安裝包、graphviz安裝包、htmlhelp安裝包。其中doxygen是一種開源跨平臺的文檔系統(tǒng)，doxygen可以從一套歸檔源文件開始，生成HTML格式的在線類瀏覽器，或離線的LATEX、RTF參考手冊。

doxygen可以生成好幾種格式的文檔，要生成.chm格式的手冊就必須安裝htmlhelp，要生成關(guān)系圖必須安裝依graphviz。這個個工具的獲取方法：

1、方法一：官網(wǎng)下載

（1）doxygen安裝包：

http://www.doxygen.nl/download.html

（2）graphviz安裝包：

http://www.graphviz.org/

（3）htmlhelp安裝包：

https://www.microsoft.com/en-us/download/details.aspx?id=21138

2、方法二：百度云盤下載

鏈接：https://pan.baidu.com/s/1gsJxkGsoO0ncy0GGM6PyQw 提取碼：3754

若鏈接失效可聯(lián)系我。

下載的都是.exe格式的可執(zhí)行文件，就按平時安裝軟件的方法安裝件就可以了。但是，需要記住graphviz與htmlhelp的安裝路徑，后面使用Doxygen時需要用到。

三、Doxygen根據(jù)代碼生成.chm的機制

Doxygen可以根據(jù)固定格式的代碼注釋生成相對應(yīng)的.chm格式的手冊。支持的語言有好多種，如C/C++/C#/Objective-C/PHP/Java等。這里主要是分享C語言，Doxygen可以識別的固定格式注釋有以下幾種：

這里，我使用第一種，如：

/**
 * 函數(shù)功能：字符串逆序函數(shù)
 * @param src_str：字符串
 * @param str_len:字符串長度
 * @return 逆序之后得到的字符串
 */ 
char *Str_ReverseOrder(char *src_str,int str_len)
{
	char *dst_str = src_str;
	char temp;
	printf("Method 1!\n");
	for(int i=0;i<str_len/2;i++)
	{
		temp = src_str[i];					
		src_str[i] = src_str[str_len-i-1];  
		src_str[str_len-i-1] = temp;		
	}
	
	return (char*)dst_str;
}

所有的函數(shù)都使用這樣統(tǒng)一格式的注釋。

四、Doxygen生成.chm文件的方法

1、設(shè)置工程工作目錄

2、設(shè)置編程語言

3、設(shè)置輸出文件格式

4、設(shè)置生成的關(guān)系表

5、輸出的語言、編碼

6、設(shè)置一些構(gòu)建的選擇項

7、設(shè)置輸入文件的編碼

8、設(shè)置是否在.chm中生成源碼以供預(yù)覽

9、設(shè)置HTML選項

10、設(shè)置Dot選項

11、運行生成.chm文件

12、保存工程文件

五、最終成果效果圖

下面看一下我們生成的.chm文件：

以上就是本次的分享，感謝閱讀！