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

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

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

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

Doxygen掃描代碼庫(kù)，尋找以/**開(kāi)頭的注釋塊，開(kāi)發(fā)人員可以通過(guò)在代碼塊中使用Doxygen標(biāo)記來(lái)指定對(duì)特定注釋的專(zhuān)門(mén)處理。 （標(biāo)簽很容易被發(fā)現(xiàn)，因?yàn)樗鼈円訞開(kāi)頭。）例如，@ file標(biāo)簽將通知Doxygen，后面的注釋提供了模塊的文件名。圖2顯示了帶有Doxygen標(biāo)記的注釋塊的示例。

圖2 - Doxygen注釋塊

但Doxygen支持100多個(gè)不同的標(biāo)簽，這意味著使用Doxygen記錄軟件具有潛力很快就搞砸了。將Doxygen與嵌入式軟件一起使用的最佳建議之一是為頭文件和源文件創(chuàng)建模板。模板文件應(yīng)包含示例代碼塊和標(biāo)頭，然后可以在實(shí)現(xiàn)階段使用它們。可以在此處找到模板外觀的示例。

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

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

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

項(xiàng)目是什么以及它的目的是什么

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

指向項(xiàng)目的C樣式指南的鏈接

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

版本日志

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

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

有用的工具以及它們?cè)陧?xiàng)目中的使用方式

提示4 -使用GraphViz中的點(diǎn)工具

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

類(lèi)圖

依賴(lài)關(guān)系圖表

調(diào)用圖表

調(diào)用圖表

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

提示5 -對(duì)于HTML，生成樹(shù)視圖

默認(rèn)情況下，Doxygen會(huì)生成一個(gè)HTML輸出中的頂級(jí)菜單，開(kāi)發(fā)人員可以從中導(dǎo)航代碼庫(kù)。頂部菜單很有用，但生成樹(shù)視圖是一種更有效的導(dǎo)航方法。可以通過(guò)專(zhuān)家HTML選項(xiàng)卡啟用選項(xiàng)GENERATE_TREEVIEW來(lái)創(chuàng)建樹(shù)視圖。

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

一旦開(kāi)發(fā)人員開(kāi)始使用Doxygen它就可以了每次編譯代碼庫(kù)時(shí)，都很想通過(guò)編譯器命令行調(diào)用Doxygen。但是，在每個(gè)編譯時(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評(píng)論添加到C風(fēng)格指南中

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