Doxygen對于有紀律的嵌入式軟件開發(fā)人員來說是一個了不起的工具，他們希望快速生成與代碼保持同步的軟件手冊。它會掃描您的代碼，解析開發(fā)人員的注釋，并將注釋與軟件對象和功能相關(guān)聯(lián)。結(jié)果輸出可以是鏈接的HTML，rtf或LaTex文件，然后作為應(yīng)用程序的知識體。

Doxygen支持許多不同的編程語言，其默認值不一定能為C語言提供最佳輸出。當(dāng)使用Doxygen配置工具Doxywizard時，開發(fā)人員應(yīng)選擇“優(yōu)化C輸出”選項。選擇按鈕位于模式選項卡下，如圖1所示。如果正在使用C ++，請選擇其中一個選項來優(yōu)化C ++的輸出。

圖1 - 設(shè)置“優(yōu)化C輸出”選項

提示2 -使用模塊模板一致的文檔

Doxygen掃描代碼庫，尋找以/**開頭的注釋塊，開發(fā)人員可以通過在代碼塊中使用Doxygen標(biāo)記來指定對特定注釋的專門處理。 （標(biāo)簽很容易被發(fā)現(xiàn)，因為它們以@開頭。）例如，@ file標(biāo)簽將通知Doxygen，后面的注釋提供了模塊的文件名。圖2顯示了帶有Doxygen標(biāo)記的注釋塊的示例。

圖2 - Doxygen注釋塊

但Doxygen支持100多個不同的標(biāo)簽，這意味著使用Doxygen記錄軟件具有潛力很快就搞砸了。將Doxygen與嵌入式軟件一起使用的最佳建議之一是為頭文件和源文件創(chuàng)建模板。模板文件應(yīng)包含示例代碼塊和標(biāo)頭，然后可以在實現(xiàn)階段使用它們?？梢栽诖颂幷业侥０逋庥^的示例。

提示3 -創(chuàng)建主頁

Doxygen將掃描開發(fā)人員在配置文件中發(fā)出的任何文件類型，并具有能夠解析稱為主頁的特殊類型的文件。主頁面是一個用戶可配置的頁面，默認情況下在加載HTML文檔時顯示，或者出現(xiàn)在生成的RTF文件的開頭。主頁面是開發(fā)人員描述項目，背景和任何可能對手冊讀者有用的編碼約定的理想場所。

主頁面通常會描述以下內(nèi)容：

項目是什么以及它的目的是什么

編碼標(biāo)準(zhǔn)的鏈接

指向項目的C樣式指南的鏈接

代碼庫中使用的任何縮寫的概述

版本日志

使用的常規(guī)Doxygen約定

可能有用的項目文檔的鏈接

有用的工具以及它們在項目中的使用方式

提示4 -使用GraphViz中的點工具

從GraphViz包中啟用點工具為Doxygen提供了一個非常強大的圖形選項，允許開發(fā)人員生成如下圖形：

類圖

依賴關(guān)系圖表

調(diào)用圖表

調(diào)用圖表

點生成的圖表可以使用圖形表示為開發(fā)人員提供對軟件的深入了解，允許快速瀏覽漂亮的圖片以提供深刻見解。

提示5 -對于HTML，生成樹視圖

默認情況下，Doxygen會生成一個HTML輸出中的頂級菜單，開發(fā)人員可以從中導(dǎo)航代碼庫。頂部菜單很有用，但生成樹視圖是一種更有效的導(dǎo)航方法。可以通過專家HTML選項卡啟用選項GENERATE_TREEVIEW來創(chuàng)建樹視圖。

提示6 -不要將Doxygen添加到編譯器命令行

一旦開發(fā)人員開始使用Doxygen它就可以了每次編譯代碼庫時，都很想通過編譯器命令行調(diào)用Doxygen。但是，在每個編譯時解析文檔的代碼庫是一個很大的錯誤，因為Doxygen可能需要“很長”的時間來解析文件并生成文檔。時間的流逝可能會大大減緩開發(fā)速度。相反，開發(fā)人員應(yīng)該在將任何新開發(fā)的軟件添加到版本控制系統(tǒng)之前創(chuàng)建文檔。

提示7 -做將Doxygen評論添加到C風(fēng)格指南中

開發(fā)團隊?wèi)?yīng)使用C風(fēng)格指南它告訴工程師在開發(fā)過程中使用的樣式約定。樣式指南應(yīng)該反映Doxygen模板和約定，以便為開發(fā)人員提供有關(guān)如何在整個代碼庫中始終如一地編寫注釋的指導(dǎo)。采用Doxygen也應(yīng)該導(dǎo)致更新這個重要的開發(fā)團隊文檔。