整合營銷服務(wù)商

          電腦端+手機端+微信端=數(shù)據(jù)同步管理

          免費咨詢熱線:

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

          得不會的代碼注釋工具——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)正常,有的需要絕對目錄有的需要相對目錄

          外部URL

          NAT處理

          內(nèi)部URL

          http://$wanip:9999/source/

          http://$nginxip:8081/source/

          鑒權(quán)成功 --> 打開http://$hostip:666/xxx

          http://$wanip:9999/git/xxx

          http://$nginxip:8081/git/xxx

          鑒權(quán)成功 --> 打開http://$hostip:777/git/xxx

          • $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文件:

          以上就是本次的分享,感謝閱讀!


          主站蜘蛛池模板: 亚洲日韩AV一区二区三区四区| 国内精自品线一区91| 麻豆视传媒一区二区三区| 欧美日韩精品一区二区在线视频| 日韩精品一区二区三区在线观看l| 亚洲综合在线一区二区三区| 亚洲国产欧美日韩精品一区二区三区| 无码人妻精品一区二区蜜桃网站 | 亚洲AV无码一区二区乱子伦| 国产一区二区三区无码免费| 3d动漫精品啪啪一区二区中文| 秋霞鲁丝片一区二区三区| 亚洲制服丝袜一区二区三区| 中文字幕视频一区| 日韩好片一区二区在线看| 高清一区二区三区日本久| 国产免费一区二区三区VR| 精品一区二区91| 肉色超薄丝袜脚交一区二区| 毛片一区二区三区无码| 久久亚洲中文字幕精品一区四| 精品国产一区AV天美传媒| 亚洲国产精品一区二区第四页| 无码人妻精品一区二区三区夜夜嗨| 国产成人久久一区二区不卡三区| 久久久久人妻一区精品| 美女AV一区二区三区| 美日韩一区二区三区| 亚洲av成人一区二区三区| 一区二区三区视频在线观看| 精品国产区一区二区三区在线观看| 亚洲AV综合色区无码一区爱AV| 亚洲日韩国产一区二区三区| 精品无人区一区二区三区在线| 久久精品成人一区二区三区| 岛国无码av不卡一区二区| 亚洲av日韩综合一区久热| 一本大道东京热无码一区| 精品视频在线观看一区二区三区| 亚洲一区二区三区在线| 中文字幕人妻丝袜乱一区三区|