對(duì)于有紀(jì)律的嵌入式開(kāi)發(fā)人員來(lái)說(shuō)，Doxygen 是一個(gè)了不起的工具，他們希望快速生成與他們的代碼保持同步的軟件手冊(cè)。它掃描您的代碼，解析出開(kāi)發(fā)人員的注釋，并將注釋與軟件對(duì)象和功能相關(guān)聯(lián)。結(jié)果輸出可以是鏈接的HTML、rtf或LaTex文件，然后作為應(yīng)用程序的知識(shí)主體。然而，為了充分利用Doxygen，開(kāi)發(fā)人員在使用該工具時(shí)應(yīng)該記住這七個(gè)關(guān)鍵技巧。

　　技巧1——優(yōu)化C語(yǔ)言的輸出

　　Doxygen支持許多不同的編程語(yǔ)言，它的默認(rèn)值不一定能為C語(yǔ)言提供最好的輸出。當(dāng)使用Doxygen配置工具Doxywizard時(shí)，開(kāi)發(fā)人員應(yīng)該選擇“為C優(yōu)化輸出”選項(xiàng)。選擇按鈕位于mode選項(xiàng)卡下。

　　技巧2——使用模塊模板以獲得一致的文檔

　　Doxygen掃描代碼庫(kù)，尋找以/**開(kāi)頭的注釋塊，嵌入式開(kāi)發(fā)人員可以通過(guò)在代碼塊中使用Doxygen標(biāo)記來(lái)指定特定注釋的特殊處理。(標(biāo)簽很容易被發(fā)現(xiàn)，因?yàn)樗鼈円訞開(kāi)頭。)例如,@file標(biāo)簽將通知Doxygen后面的注釋提供了模塊的文件名。圖2展示了一個(gè)帶有Doxygen標(biāo)簽的注釋塊的例子。

　　但是Doxygen支持100多種不同的標(biāo)簽，這意味著使用Doxygen編寫軟件文檔可能會(huì)很快變得混亂。在嵌入式軟件中使用Doxygen的最佳建議之一是為頭文件和源文件創(chuàng)建一個(gè)模板。模板文件應(yīng)該包含示例代碼塊和頭文件，以便在實(shí)現(xiàn)階段使用。

　　技巧3——?jiǎng)?chuàng)建主頁(yè)

　　Doxygen將從配置文件中掃描嵌入式開(kāi)發(fā)人員告訴它的任何文件類型，并能夠解析一種稱為主頁(yè)的特殊類型的文件。主頁(yè)是一個(gè)用戶可配置的頁(yè)面，默認(rèn)情況下在加載HTML文檔時(shí)顯示，或者出現(xiàn)在生成的RTF文件的開(kāi)頭。對(duì)于開(kāi)發(fā)人員來(lái)說(shuō)，主頁(yè)是描述項(xiàng)目、背景和任何可能對(duì)手冊(cè)讀者有用的編碼約定的最佳地方。

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

　　項(xiàng)目是什么，目的是什么

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

　　鏈接到項(xiàng)目的C風(fēng)格指南

　　代碼庫(kù)中使用的任何縮寫的概述

　　版本日志

　　使用的一般Doxygen慣例

　　可能有用的項(xiàng)目文檔的鏈接

　　有用的工具以及它們?nèi)绾卧陧?xiàng)目中使用

　　技巧4——使用GraphViz的點(diǎn)工具

　　從GraphViz包中啟用點(diǎn)工具為Doxygen提供了一個(gè)非常強(qiáng)大的圖形選項(xiàng)，允許嵌入式開(kāi)發(fā)人員生成如下圖形：

　　類圖

　　依賴圖

　　調(diào)用圖

　　被調(diào)用圖

　　點(diǎn)生成的圖形可以使用圖形表示向開(kāi)發(fā)人員提供對(duì)軟件的洞察力，允許快速瀏覽漂亮的圖片以提供很好的洞察力。

　　技巧5——對(duì)于HTML，生成樹形視圖

　　默認(rèn)情況下，Doxygen將在其HTML輸出中生成一個(gè)頂部菜單，開(kāi)發(fā)人員可以通過(guò)該菜單瀏覽代碼庫(kù)。頂部菜單很有幫助，但是生成樹形視圖是一種更有效的導(dǎo)航方法。可以通過(guò)expert HTML選項(xiàng)卡啟用GENERATE_TREEVIEW選項(xiàng)來(lái)創(chuàng)建樹視圖。

　　技巧6——不將Doxygen添加到編譯器命令行

　　一旦嵌入式開(kāi)發(fā)人員開(kāi)始使用Doxygen，每次編譯代碼庫(kù)時(shí)，通過(guò)編譯器命令行調(diào)用Doxygen會(huì)很有誘惑力。但是，每次編譯時(shí)都解析文檔的代碼庫(kù)是一個(gè)很大的錯(cuò)誤，因?yàn)镈oxygen可能需要“很長(zhǎng)”時(shí)間來(lái)解析文件和生成文檔。時(shí)間的沖擊會(huì)大大降低開(kāi)發(fā)速度。相反，開(kāi)發(fā)人員應(yīng)該在將任何新開(kāi)發(fā)的軟件添加到版本控制系統(tǒng)之前創(chuàng)建文檔。

　　技巧7——做將Doxygen注釋添加到C風(fēng)格指南中

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