畢業(yè)設(shè)計(jì)--javascript在線api文檔生成

1、<p>　　本科畢業(yè)設(shè)計(jì)說明書（論文）</p><p><b>　?。?012屆）</b></p><p>　　論文題目 JavaScript在線API文檔生成</p><p><b>　　摘要</b></p><p>　　JavaScript 是目前最流行的腳本語言。它起初是為網(wǎng)頁提供

2、交互能力而設(shè)計(jì)的一門基于對(duì)象的普通腳本語言。但隨著一些Web新標(biāo)準(zhǔn)的出現(xiàn)和一些像Nodejs之類的JavaScript客戶端宿主程序的流行，JavaScript的用途也越來越廣，一個(gè)JavaScript的項(xiàng)目也隨之變大。因此現(xiàn)在對(duì)JavaScript項(xiàng)目的API文檔的需求也迅速膨脹。</p><p>　　為了將作者從手動(dòng)書寫API文檔的繁瑣過程中解脫出來，必須要有一個(gè)強(qiáng)大的工具能夠提取代碼中的注釋，并自動(dòng)生成一份

3、完整的API文檔。傳統(tǒng)的一些JavaScript文檔生成項(xiàng)目，比如jsdoc，只能生成比較簡(jiǎn)單的文檔，無法很好地滿足現(xiàn)在的新需求。本文研究對(duì)JavaScript源碼中的注釋進(jìn)行解析，然后提取有用的API信息，并最后生成一個(gè)完整的文檔頁面供讀者閱讀。解析過程充分考慮了JavaScript語言的靈活特性，讓JavaScript源碼作者可以快速地為自己的代碼生成對(duì)應(yīng)的文檔。</p><p>　　同時(shí)為了方便用戶進(jìn)行文檔

4、生成操作，使用C#開發(fā)一個(gè)WinForm軟件。生成的文檔是一個(gè)普通的網(wǎng)頁，用戶可以自定義文檔界面模板。生成的文檔可以放在ASP.NET服務(wù)器上直接運(yùn)行。讀者可以在線閱讀文檔，并在文檔的任何一頁添加評(píng)論。 </p><p>　　關(guān)鍵詞：JavaScript, API, 文檔生成, WinForm</p><p><b>　　Abstract</b></p>

5、<p>　　JavaScript is the most popular script language nowadays, which is designed as a simple object-based script language to provide the ability of interaction for web pages at first. But along with the appearance

6、of new web standards and the popularity of some JavaScript clients like Nodejs, the usage of JavaScript increases soon and the JavaScript projects become more complex, which leads to new requirement of JavaScript documen

7、tation as well.</p><p>　　To avoid authors writing API Document word by word, there should be a powerful tool to export an API document from the source code automatically. The traditional related projects suc

8、h as Jsdoc show their shortcoming when meeting new requirements. This article focuses on analyzing source code of JavaScript and then generating a full API document. The analyzing program is fit for JavaScript, which can

9、 save a lot of time for JavaScript authors.</p><p>　　This article also talks about developing a program of WinForm to make it easier to operate. On the other hand, users can custom the templates of document

10、if needed. The generated API document can run on ASP.NET server directly. Readers can view the document online and leave their comments on any page.</p><p>　　Keywords：JavaScript, API, Document Generator, Wi

11、nForm</p><p><b>　　目錄</b></p><p><b>　　摘要I</b></p><p>　　AbstractI</p><p><b>　　第一章緒論3</b></p><p>　　1.1研究開發(fā)的目的3</p

12、><p>　　1.2國(guó)內(nèi)外研究發(fā)展現(xiàn)狀4</p><p>　　1.3研究開發(fā)的基本目標(biāo)4</p><p>　　1.4本文的組織結(jié)構(gòu)5</p><p>　　第二章 方法與技術(shù)6</p><p>　　2.1軟件運(yùn)行環(huán)境6</p><p>　　2.1.1客戶端環(huán)境要求6</p&

13、gt;<p>　　2.1.2服務(wù)器環(huán)境要求6</p><p>　　2.2WinForm 簡(jiǎn)介6</p><p>　　2.3ASP.NET 簡(jiǎn)介7</p><p>　　2.4AJAX 簡(jiǎn)介7</p><p>　　2.5編譯原理8</p><p>　　2.6系統(tǒng)構(gòu)架: B/S構(gòu)架8&l

14、t;/p><p>　　2.7主要開發(fā)語言9</p><p>　　2.8開發(fā)工具9</p><p>　　2.8.1Visual Studio 20109</p><p>　　2.8.2Firebug9</p><p>　　第三章 需求分析10</p><p>　　3.1軟件主體1

15、0</p><p>　　3.1.1用例圖10</p><p>　　3.1.2新建和保存項(xiàng)目10</p><p>　　3.1.3編輯項(xiàng)目10</p><p>　　3.1.4編譯項(xiàng)目11</p><p>　　3.2生成的文檔界面11</p><p>　　3.3用于在線可評(píng)論的文

16、檔12</p><p>　　3.4文檔調(diào)試工具12</p><p>　　第四章 系統(tǒng)設(shè)計(jì)實(shí)現(xiàn)13</p><p>　　4.1文檔解析核心13</p><p>　　4.1.1數(shù)據(jù)流圖13</p><p>　　4.1.2類圖14</p><p>　　4.1.3相關(guān)的實(shí)體類14

17、</p><p>　　4.1.4DocProject 類的實(shí)現(xiàn)15</p><p>　　4.1.5DocParser類的實(shí)現(xiàn)16</p><p>　　4.1.6JavaCommentParser 類的實(shí)現(xiàn)17</p><p>　　4.1.7JavaScript 語法樹構(gòu)建器的實(shí)現(xiàn)17</p><p>　

18、　4.1.8DocAstVistor 類的實(shí)現(xiàn)18</p><p>　　4.1.9DocMerger 類的實(shí)現(xiàn)18</p><p>　　4.1.10DocGenerator 類的實(shí)現(xiàn)19</p><p>　　4.2軟件主體19</p><p>　　4.2.1界面布局19</p><p>　　4.2.

19、2項(xiàng)目操作20</p><p>　　4.2.3軟件實(shí)現(xiàn)20</p><p>　　4.3文檔頁面23</p><p>　　4.4在線文檔評(píng)論24</p><p>　　4.5文檔調(diào)試工具25</p><p>　　第五章 系統(tǒng)測(cè)試27</p><p>　　5.1單元測(cè)試27&

20、lt;/p><p>　　5.2系統(tǒng)功能測(cè)試27</p><p><b>　　第六章 總結(jié)28</b></p><p>　　6.1完成的工作28</p><p>　　6.2下一步工作28</p><p><b>　　參考文獻(xiàn)29</b></p><

21、;p><b>　　致謝31</b></p><p><b>　　附錄32</b></p><p>　　附錄1 畢業(yè)設(shè)計(jì)文獻(xiàn)綜述32</p><p>　　附件2 畢業(yè)設(shè)計(jì)開題報(bào)告32</p><p>　　附件3 畢業(yè)設(shè)計(jì)外文翻譯（中文譯文與外文原文）32</p>&

22、lt;p><b>　　圖目錄</b></p><p>　　圖 11文檔注釋3</p><p>　　圖 21 Firebug 運(yùn)行界面9</p><p>　　圖 31軟件主體用例圖10</p><p>　　圖 41數(shù)據(jù)流圖13</p><p>　　圖 42類圖14</

23、p><p>　　圖 43 DocData的字段15</p><p>　　圖 44軟件主體的布局19</p><p>　　圖 45軟件主體運(yùn)行界面21</p><p>　　圖 46編輯項(xiàng)目21</p><p>　　圖 47設(shè)置項(xiàng)目屬性22</p><p>　　圖 48控制臺(tái)22

24、</p><p>　　圖 49文檔界面23</p><p>　　圖 410評(píng)論框24</p><p>　　圖 411文檔調(diào)試工具25</p><p><b>　　表目錄</b></p><p>　　表4-1接口設(shè)計(jì)24</p><p>　　表4-2數(shù)據(jù)庫設(shè)計(jì)

25、25</p><p><b>　　緒論</b></p><p><b>　　研究開發(fā)的目的</b></p><p>　　隨著軟件工程的規(guī)模越來越大，參與項(xiàng)目的人數(shù)也越來越多，因此非常需要有API文檔來描述各個(gè)模塊的功能，以讓團(tuán)隊(duì)內(nèi)的成員無需關(guān)心其它人的編碼細(xì)節(jié)就能協(xié)調(diào)開發(fā)，減少溝通成本。</p><p&

26、gt;　　API文檔可以讓作者自己書寫，但毫無疑問書寫文檔的時(shí)間是非常長(zhǎng)的，而且現(xiàn)代軟件項(xiàng)目的需求經(jīng)常改變，這就意味著每次修改需求都要重新修改源碼和對(duì)應(yīng)的文檔，其維護(hù)的成本是相當(dāng)大的。因此現(xiàn)實(shí)很少有人會(huì)花額外時(shí)間來編輯API文檔。</p><p>　　如果將文檔直接以注釋的方式寫進(jìn)代碼里，這樣源碼和文檔總是出現(xiàn)在一起，修改的時(shí)候可以一并修改，這樣就能大大減少維護(hù)文檔的時(shí)間成本了。同時(shí)也方便其他人在閱讀源碼時(shí)通過注

27、釋來更直觀地理解功能。如圖1-1就是一個(gè)典型的文檔注釋。</p><p><b>　　圖 11文檔注釋</b></p><p>　　文檔生成工具可以提取源碼中的注釋，并最后生成一個(gè)可供人直接閱讀的API文檔。使用一些工具來生成API文檔自然可以節(jié)約額外的文檔書寫時(shí)間，也可以在源碼被修改后重新生成文檔，而不需要每次都手寫文檔。因此，開發(fā)一個(gè)優(yōu)秀的文檔生成工具是非常有必

28、要的。</p><p>　　傳統(tǒng)的API文檔都是一個(gè)類似word的本地?cái)?shù)據(jù)文件，它確實(shí)完成了API文檔所應(yīng)該擁有的功能。但在 web2.0 時(shí)代，如果能讓更多人通過網(wǎng)頁參與API文檔內(nèi)容的討論，則可以幫助作者修正錯(cuò)誤，更幫助其他讀者理解。同時(shí)還能讓來自不同地區(qū)的讀者在網(wǎng)站上共同學(xué)習(xí)、共同進(jìn)步。因此生成的文檔可以讓讀者可以就某個(gè)API進(jìn)行評(píng)論。</p><p>　　在線API文檔也方便讀者瀏

29、覽文檔，讀者不需要安裝額外的軟件，只需一個(gè)瀏覽器即可直接打開文檔。</p><p><b>　　國(guó)內(nèi)外研究發(fā)展現(xiàn)狀</b></p><p>　　目前主流的編程語言都有相應(yīng)的文檔生成工具。比如Java語言可以使用javadoc來生成文檔，生成的文檔非常精確。</p><p>　　目前國(guó)外最有名的JavaScript文檔生成工具為jsdoc too

30、lkit，它的工作原理是在強(qiáng)制作者在代碼中書寫一些標(biāo)記，然后jsdoc文檔會(huì)分析這些標(biāo)記來構(gòu)建文檔，并確保最后生成的文檔是正確的。雖然使用這個(gè)方式比較容易理解和使用，但由于它只分析這些標(biāo)記，而忽略源碼本身，很多可以從源碼中得到的信息必須在標(biāo)記中重新寫明，所以讓文檔書寫的工作量倍增。此外，它還具有以下缺點(diǎn)：</p><p>　　只有命令行模式，新用戶不容易上手。</p><p>　　由于是國(guó)

31、外的項(xiàng)目，中文容易出現(xiàn)亂碼。</p><p>　　生成的文檔比較簡(jiǎn)單，信息量少。</p><p>　　因此它不是完美的解決方案。</p><p>　　目前最有名的在線API文檔系統(tǒng)為MSDN，MSDN 庫為使用 Microsoft® 工具、產(chǎn)品、技術(shù)和服務(wù)的開發(fā)人員提供必不可少的信息資源。MSDN 庫包含操作方法和參考文檔、示例代碼、技術(shù)文章和其他內(nèi)容。但

32、 MSDN 僅針對(duì)指定平臺(tái)才能使用，而且MSDN是不開源的，無法被其他用戶使用。</p><p><b>　　研究開發(fā)的基本目標(biāo)</b></p><p>　　該軟件主要分三個(gè)部分：</p><p>　　軟件主體。本程序目標(biāo)用戶為源碼作者，這些用戶可以通過這個(gè)軟件進(jìn)行文檔生成操作，同時(shí)軟件也會(huì)向它們報(bào)告解析錯(cuò)誤。</p><p

33、>　　文檔網(wǎng)站。網(wǎng)站用于展示文檔，同時(shí)網(wǎng)站允許使用不同的模板風(fēng)格，方便用戶自定義網(wǎng)站。</p><p>　　可以為最終用戶提供聯(lián)機(jī)使用幫助，包括本系統(tǒng)的說明信息、使用方法和步驟以及版權(quán)信息和聯(lián)系方式等。</p><p><b>　　本文的組織結(jié)構(gòu)</b></p><p>　　本文共分為六章，各章內(nèi)容如下：</p><p

34、>　　第一章，緒論,討論課題的研究目的和意義、研究現(xiàn)狀，研究主要內(nèi)容。</p><p>　　第二章，相關(guān)方法和技術(shù)介紹。</p><p>　　第三章，重點(diǎn)介紹了文檔生成過程的具體需求。</p><p>　　第四章，對(duì)整個(gè)系統(tǒng)進(jìn)行設(shè)計(jì)和實(shí)現(xiàn)。重點(diǎn)介紹分析算法的實(shí)現(xiàn)和最終文檔頁面的代碼設(shè)計(jì)。</p><p>　　第五章，系統(tǒng)測(cè)試與系統(tǒng)使用說

35、明。</p><p>　　第六章，對(duì)系統(tǒng)開發(fā)進(jìn)行總結(jié)并提出下一步工作。</p><p><b>　　第二章 方法與技術(shù)</b></p><p>　　本系統(tǒng)涉及了多個(gè)領(lǐng)域的知識(shí)。用戶可以通過一個(gè)本地軟件界面來生成文檔，而生成的文檔本身又是一個(gè)Web頁面，并且還需要開發(fā)一個(gè)后臺(tái)動(dòng)態(tài)網(wǎng)站才能實(shí)現(xiàn)在線評(píng)論。軟件的主要任務(wù)是生成文檔，文檔解析核心算法是本

36、系統(tǒng)開發(fā)的主要難點(diǎn)，它需要用到編譯原理相關(guān)的知識(shí)。</p><p><b>　　軟件運(yùn)行環(huán)境</b></p><p>　　本系統(tǒng)基于.Net Framework 3.5 壞境開發(fā)。.Net Framework 壞境是支持生成和運(yùn)行下一代應(yīng)用程序和XML Web Service 的內(nèi)部 Windows 組件。[1]</p><p><b&g

37、t;　　客戶端環(huán)境要求</b></p><p>　　安裝有.Net Frameworks 3.5 的 windows系統(tǒng)。</p><p><b>　　服務(wù)器環(huán)境要求</b></p><p>　　服務(wù)器: IIS(Internet Information Server) 7。</p><p>　　IIS是In

38、ternet Information Services的縮寫，是一個(gè)World Wide Web server。Gopher server和FTP server全部包容在里面。 IIS意味著你能發(fā)布網(wǎng)頁，并且有ASP（Active Server Pages）、JAVA、VBScript產(chǎn)生頁面，有著一些擴(kuò)展功能[2]。</p><p>　　數(shù)據(jù)庫：Access2007</p><p>　　

39、Access 2007是 Microsoft Office 2007 家族中專業(yè)的數(shù)據(jù)庫管理系統(tǒng)，它具有強(qiáng)大的數(shù)據(jù)管理和分析功能。作為一種新型的關(guān)系型數(shù)據(jù)庫管理系統(tǒng)，它能幫助用戶處理各種海量信息。它不僅能存儲(chǔ)數(shù)據(jù)，更重要的是能夠?qū)?shù)據(jù)進(jìn)行分析和處理，使用戶方便快捷地聚聚各種有用的數(shù)據(jù)[3]。</p><p>　　WinForm 簡(jiǎn)介</p><p>　　Windows Forms(Wind

40、ows窗體)是1個(gè)新的窗體包，它使得開發(fā)人員可以創(chuàng)建基于Windows的應(yīng)用程序，來充分利用Microsoft Windows操作系統(tǒng)中豐富的用戶界面特性。Windows Forms是新的Microsoft．NET Framework的一部分，它使用了許多新技術(shù)，包括1個(gè)公共應(yīng)用程序框架、受控的執(zhí)行環(huán)境、集成的安全性和面向?qū)ο蟮脑O(shè)計(jì)原則。此外，Windows Forms完全支持快速、容易地連接XML網(wǎng)絡(luò)服務(wù)和在ADO．NET數(shù)據(jù)模型基礎(chǔ)

41、上創(chuàng)建豐富的、數(shù)據(jù)感知(data．a(chǎn)ware)的應(yīng)用程序。利用Visual Studio．NET中新的共享開發(fā)環(huán)境，開發(fā)人員可以使用任何支持．NET平臺(tái)的語言。開發(fā)人員可以使用任何支持．NET平臺(tái)的語言。在Visual C#中構(gòu)建Windows窗體程序時(shí)需要向項(xiàng)目添加窗體，將控件拖放到窗體，然后在控件雙擊，即可編寫窗體背后的代碼。開發(fā)人員使用這種熟知的模型，來迅速地構(gòu)建桌面應(yīng)用程序。C#的Windows Forms有

42、1個(gè)重要的新特性一可視化集繼承，它將提高開發(fā)人員的生產(chǎn)力，促進(jìn)代碼的重用。C群的Windows Form</p><p>　　ASP.NET 簡(jiǎn)介</p><p>　　ASP.NET 是一個(gè)后臺(tái)動(dòng)態(tài)語言技術(shù)。它是開發(fā)人員和構(gòu)架師共同思考關(guān)于未來Web開發(fā)的發(fā)展方向而得出的結(jié)果[6]。生成的文檔本身不依賴于 ASP.NET，它僅僅需要用ASP.NET 為它提供后臺(tái)提供評(píng)論服務(wù)接口。

43、</p><p><b>　　AJAX 簡(jiǎn)介</b></p><p>　　Ajax是Asynchronous JavaScript and XML的縮寫。Ajax并不是一門新的語言或技術(shù)，它實(shí)際卜是幾項(xiàng)技術(shù)按一定方式的組合，在共同的協(xié)作中發(fā)揮各自的作用，它包括：使用XHTML和CSS標(biāo)準(zhǔn)化呈現(xiàn)：使用DOM實(shí)現(xiàn)動(dòng)態(tài)顯示和交互；使用XML和XSLT進(jìn)行數(shù)據(jù)交換與處理；使用

44、XMLHttpRequest進(jìn)行異步數(shù)據(jù)讀??；最后用JavaScript綁定和處理所有數(shù)據(jù)。其中XMLHttpRequest，JavaScript和DOM是Ajax技術(shù)的核心[7]。</p><p>　　Ajax 使得Web應(yīng)用程序的客戶端可以不斷從Web服務(wù)器更新部分頁面，用戶不必再提交表單，或者離開當(dāng)前的頁面。客戶端的腳本代碼(通常是JavaScript)可以向頁面的部分片段(Fragment)發(fā)起異步的，或

45、者非阻塞(Non-Blocking)的請(qǐng)求。這些片段可以是一些原始的數(shù)據(jù)，在客戶端再被轉(zhuǎn)成 HTML 代碼，也可以本身就是HTML代碼，直接插入到瀏覽器的文檔(Document)對(duì)象中。不管怎樣，在服務(wù)器端完成對(duì)請(qǐng)求的處理，并將響應(yīng)片段返回給客戶端瀏覽器之后，客戶端的較代碼都會(huì)使用這些數(shù)據(jù)來修改頁面中的文檔對(duì)象模型(Document Object Model, DOM)。這種方法不僅能夠滿足我們對(duì)快速、平滑更新的要求，更重要的是能夠以異

46、步的形式發(fā)送請(qǐng)求，因此，即使在請(qǐng)求的處理過程中，用戶也可以繼續(xù)使用應(yīng)用程序[8]。</p><p>　　生成的文檔的所有數(shù)據(jù)都是通過AJAX動(dòng)態(tài)載入然后轉(zhuǎn)成HTML代碼后顯示的。這樣可以加速文檔初始化，還可以保證最佳的用戶體驗(yàn)。</p><p><b>　　編譯原理</b></p><p>　　編譯原理起初用于將源代碼編譯成可執(zhí)行文件。本系統(tǒng)的

47、重點(diǎn)是將源代碼翻譯成文檔，因此只需要編譯原理中詞法分析、語法分析的技術(shù)。</p><p>　　使用語法分析的方式來分析源碼是本軟件和jsdoc的最大的區(qū)別。Jsdoc 只以文本方式去分析注釋，它忽略了代碼本身所展示的信息。而如果先解析語法，然后進(jìn)行文檔分析，就可以充分獲取語法樹種提供的信息來補(bǔ)全文檔。</p><p>　　這樣可以大大提高分析的正確性。</p><p&g

48、t;　　系統(tǒng)構(gòu)架: B/S構(gòu)架</p><p>　　B/S（Browser/Server）結(jié)構(gòu)即瀏覽器和服務(wù)器結(jié)構(gòu)，隨著互聯(lián)網(wǎng)的快速發(fā)展，越來越多的應(yīng)用選擇了B/S構(gòu)架。相對(duì)于C/S結(jié)構(gòu)屬于“胖”客戶端，需要在使用者電腦上安裝相應(yīng)的操作軟件來說，B/S結(jié)構(gòu)是屬于一種“瘦”客戶端，大多數(shù)或主要的業(yè)務(wù)邏輯都存在于服務(wù)器端[9]。</p><p><b>　　主要開發(fā)語言</b&

49、gt;</p><p>　　本系統(tǒng)采用C# 開發(fā)。C# 是一門間的、現(xiàn)代化、面向?qū)ο蠛皖愋桶踩木幊陶Z言。C#提供一些特性來幫助構(gòu)建健壯、耐用的應(yīng)用程序:垃圾收集會(huì)自動(dòng)回收不再使用的對(duì)象所占用的內(nèi)存;異常處理提供了一種結(jié)構(gòu)化且可擴(kuò)展的方式來檢測(cè)錯(cuò)誤和恢復(fù);而語言的類型安全設(shè)計(jì)則可以防止讀取未初始化的變量、數(shù)組越界或進(jìn)行未檢測(cè)的類型轉(zhuǎn)換[10]。</p><p><b>　　開發(fā)工

50、具</b></p><p>　　Visual Studio 2010</p><p>　　Visual Studio是微軟公司出品的一款大型應(yīng)用軟件，從最初的 Visual Studio 97 開始就成為了編程的重要工具。Visual Studio 是一天完整的開發(fā)工具集，保護(hù)了大量的公墓內(nèi)，它主要用于生成 ASP.NET Web 應(yīng)用程序、XML Web Services、桌

51、面應(yīng)用程序和移動(dòng)應(yīng)用程序[11]。Visual Studio 2010 是 Visual Studio 的最新正式版。</p><p><b>　　Firebug</b></p><p>　　Firebug 是目前最流行的網(wǎng)頁開發(fā)調(diào)試工具。它提供了包含JavaScript控制臺(tái)、HTML節(jié)點(diǎn)查看、CSS即時(shí)調(diào)試、JavaScript調(diào)試等功能，讓開發(fā)網(wǎng)頁更方便。因?yàn)檎?/p>

52、個(gè)文檔是一個(gè)比較大型的一頁式應(yīng)用，因此非常需要這樣一個(gè)代碼調(diào)試工具來確保系統(tǒng)可以穩(wěn)定運(yùn)行。Firebug的運(yùn)行界面如圖2-1。</p><p>　　圖 21 Firebug 運(yùn)行界面</p><p><b>　　第三章 需求分析</b></p><p><b>　　軟件主體</b></p><p>

53、;　　軟件主體是面向最終用戶的產(chǎn)品，最后用戶使用此軟件來達(dá)到文檔生成的目的。此處的功能設(shè)計(jì)是為用戶角色的而設(shè)計(jì)的[12]。</p><p><b>　　用例圖</b></p><p>　　圖 31軟件主體用例圖</p><p><b>　　新建和保存項(xiàng)目</b></p><p>　　新建一個(gè)文檔項(xiàng)

54、目之后，用戶可以在此項(xiàng)目中添加用于生成文檔的源文件和文件夾。用戶也可以保存這個(gè)項(xiàng)目，而不需要每次生成的時(shí)候都重新添加文件。</p><p><b>　　編輯項(xiàng)目</b></p><p><b>　　添加文件</b></p><p>　　用戶可以單獨(dú)添加用于生成文檔的源文件。而且，為了更好的用戶體驗(yàn)，用戶也可以直接將資源管理

55、器中的文件拖拖動(dòng)到軟件界面實(shí)現(xiàn)添加操作。</p><p><b>　　添加文件夾</b></p><p>　　一般地，一個(gè)項(xiàng)目包含很多源文件，如果每個(gè)單獨(dú)添加，操作會(huì)非常麻煩，因此這里也允許用戶直接添加整個(gè)文件夾。軟件會(huì)自動(dòng)搜索這個(gè)文件夾所有 *.js 文件。同樣地，用戶也可以直接拖動(dòng)一個(gè)文件夾到軟件界面實(shí)現(xiàn)添加操作。</p><p><

56、b>　　刪除文件</b></p><p>　　用戶可以主動(dòng)刪除已添加的項(xiàng)。為了更好的用戶體驗(yàn)，當(dāng)用戶選擇一項(xiàng)之后按 DELETE，也可以快速刪除項(xiàng)。當(dāng)用戶同時(shí)刪除多項(xiàng)時(shí)，應(yīng)該給予用戶確認(rèn)后再進(jìn)行刪除。</p><p><b>　　移動(dòng)文件順序</b></p><p>　　文件的順序直接關(guān)系到后面文檔解析的結(jié)果，因此必須提供一個(gè)

57、改變文件添加順序的功能，讓用戶根據(jù)需要更改源文件的解析順序。</p><p><b>　　項(xiàng)目屬性</b></p><p>　　文檔生成的時(shí)候有很多選項(xiàng)，用戶可以在項(xiàng)目屬性面板里修改這些選項(xiàng)。</p><p><b>　　編譯項(xiàng)目</b></p><p>　　編譯項(xiàng)目即生成文檔。當(dāng)項(xiàng)目編輯完成后，就

58、可以開始真正的文檔生成操作了。軟件會(huì)向用戶顯示一個(gè)控制臺(tái)窗口，隨時(shí)向用戶報(bào)告生成進(jìn)度。如果生成時(shí)發(fā)現(xiàn)錯(cuò)誤和警告，也會(huì)通過控制臺(tái)窗口向用戶報(bào)告。</p><p>　　因?yàn)槲臋n生成是一個(gè)比較費(fèi)時(shí)的過程，用戶也可以根據(jù)需要隨時(shí)中止文檔生成操作。</p><p><b>　　生成的文檔界面</b></p><p>　　多媒體數(shù)據(jù)的格式有很多，常見的有

59、Word、 PDF和CHM。但是大部分格式都需要在本地安裝格外軟件，且不適合API文檔的信息展示方式。而如果使用HTML作為文檔數(shù)據(jù)載體，將可以帶來這些好處:</p><p>　　如今現(xiàn)有的每個(gè)Web瀏覽器都能理解這種語言[13]，而且大部分電腦都安裝有瀏覽器，因此目標(biāo)平臺(tái)廣泛。</p><p>　　可以將文檔放到WEB服務(wù)器，讓用戶在線瀏覽。</p><p>&l

60、t;b>　　樣式定制方便。</b></p><p>　　所以軟件最后生成的是文檔網(wǎng)頁，并且網(wǎng)頁的布局和交互類似于傳統(tǒng)的CHM格式文件。</p><p>　　界面的左側(cè)顯示一個(gè)類圖導(dǎo)航。通過這個(gè)導(dǎo)航可以找到任何API。點(diǎn)擊導(dǎo)航上的項(xiàng)，可以在界面的右側(cè)瀏覽此API有關(guān)的詳細(xì)信息。</p><p>　　用戶在查看API文檔的時(shí)候往往需要打開多個(gè)頁面進(jìn)行比

61、較瀏覽，所以整個(gè)頁面模擬選項(xiàng)卡的布局，方便用戶同時(shí)打開多個(gè)文檔并進(jìn)行對(duì)比瀏覽。</p><p>　　盡管 Web 應(yīng)用有這樣或那樣的優(yōu)點(diǎn)，但作為一種應(yīng)用媒介，它也有一個(gè)大的缺點(diǎn)。就是網(wǎng)頁需要刷新才能獲取新數(shù)據(jù)。因此我們需要使用AJAX技術(shù)來填補(bǔ)這個(gè)空白[14]。</p><p>　　用于在線可評(píng)論的文檔</p><p>　　傳統(tǒng)的文檔都是靜態(tài)數(shù)據(jù)，用戶只能瀏覽而不能

62、參與評(píng)論。在 Web 2.0 下，社區(qū)化的文檔更能幫助讀者理解文檔內(nèi)容。</p><p>　　當(dāng)用戶打開文檔界面時(shí)，文檔會(huì)從服務(wù)器自動(dòng)載入相關(guān)的評(píng)論。用戶還可以在任何頁面添加自己的評(píng)論。</p><p><b>　　文檔調(diào)試工具</b></p><p>　　最終的文檔是根據(jù)代碼中的注釋提取出來的，源文件中的注釋不可能一次性就寫正確，往往需要反復(fù)

63、修改才能確保最終生成的文檔是正確的。</p><p>　　但每次生成操作生成的是一個(gè)最終的文檔頁面，這是一個(gè)比較漫長(zhǎng)的過程。因此還需要提供一個(gè)文檔調(diào)試工具，這個(gè)工具只解析文檔并向用戶報(bào)告文檔解析結(jié)果，而不生成最后的文檔。</p><p>　　用戶可以使用這個(gè)工具來排除文檔注釋中的錯(cuò)誤，然后使用軟件主體來生成最后的文檔。</p><p>　　第四章 系統(tǒng)設(shè)計(jì)實(shí)現(xiàn)<

64、;/p><p><b>　　文檔解析核心</b></p><p><b>　　數(shù)據(jù)流圖</b></p><p><b>　　圖 41數(shù)據(jù)流圖</b></p><p><b>　　類圖</b></p><p><b>　　圖

65、42類圖</b></p><p>　　DocProject 類負(fù)責(zé)管理整個(gè)文檔生成操作。文檔生成操作分 文檔解析 和 生成最終文件 兩步。文檔解析由 DocParser 類完成。生成最終文件由DocGenerator類完成。</p><p>　　因?yàn)槲臋n解析的步驟較為復(fù)雜，因此文件解析又分成語法樹解析、文檔注釋解析、文檔注釋分析、文檔注釋提取。這些操作分別由 Javascri

66、ptParser 類、JavaCommentParser 類、DicAstVisitor 類、DocMerger類完成。</p><p><b>　　相關(guān)的實(shí)體類</b></p><p>　　為了實(shí)現(xiàn)相關(guān)功能，還需要定義一些實(shí)體類。</p><p>　　XXCommentNode 類</p><p>　　XXCommen

67、tNode 存儲(chǔ)某個(gè)節(jié)點(diǎn)的數(shù)據(jù)。比如 ReturnCommentNode 是一個(gè)包含 ReturnType 和 ReturnSummary 的一個(gè)結(jié)構(gòu)。</p><p>　　DocComment類</p><p>　　DocComment 表示文檔中的一個(gè)注釋信息，它是一個(gè)哈希表，存儲(chǔ)了標(biāo)簽和值的一一對(duì)應(yīng)關(guān)系。比如如下注釋:</p><p><b>　　/

68、**</b></p><p><b>　　* 說明</b></p><p>　　* @since 1.3</p><p>　　* @return {Object} value</p><p><b>　　*/</b></p><p>　　對(duì)應(yīng)解析的結(jié)果是一個(gè) Do

69、cComment 對(duì)象,其內(nèi)容為:</p><p>　　summary => 說明</p><p>　　since => 1.3</p><p>　　return => ReturnCommentNode( {Object} value )</p><p>　　其中， since 標(biāo)簽對(duì)應(yīng)的數(shù)據(jù)是一個(gè)字符串，值為 1.3 。

70、return 標(biāo)簽對(duì)應(yīng)的數(shù)據(jù)是一個(gè) ReturnCommentNode實(shí)例。</p><p><b>　　DocData </b></p><p>　　DocData存儲(chǔ)最后的文檔解析數(shù)據(jù)。其數(shù)據(jù)結(jié)構(gòu)如圖4-3:</p><p>　　圖 43 DocData的字段</p><p>　　其中，DocComments 為源

71、文件中所有注釋集合，它是按照注釋在源文件的排列順序出現(xiàn)的。Files 為源文件的列表，它和用戶選擇的解析源文件基本一致，但會(huì)自動(dòng)重命名同名的文件，比如如果出現(xiàn)3個(gè)名為base.js的源文件，那么，第二個(gè)就會(huì)被重命名為base_1.js,第三個(gè)就會(huì)被重命名為base_2.js。Properties 是根據(jù)注釋信息得到的項(xiàng)目屬性。它是根據(jù)源文件中的一些特定標(biāo)簽得到的，比如源文件中的 @copyright 標(biāo)簽的信息不會(huì)被保存到一個(gè)DocCo

72、mment 對(duì)象中，而是被保存到 Properties 屬性的。只有有限的幾個(gè)內(nèi)置標(biāo)簽才會(huì)被保存到 Properties 屬性的。</p><p>　　DocProject 類的實(shí)現(xiàn)</p><p>　　DocProject 存儲(chǔ)了項(xiàng)目的所有配置，軟件的操作注意是對(duì) DocProject 進(jìn)行的。DocProject 提供的接口和需求一一對(duì)應(yīng)。DocProject本身又是一個(gè)哈希表[15]

73、，它存儲(chǔ)了一次文檔生成的全部配置。</p><p>　　DocProject 最主要的核心解析函數(shù)如下:</p><p>　　public override void Build() {</p><p>　　// 首先獲取原始的文檔數(shù)據(jù)。</p><p>　　DocData data = Parse();</p><p&g

74、t;　　// 然后使用 DocGenerator 進(jìn)行最終文件生成。</p><p>　　new DocGenerator(this).Generate(data);</p><p><b>　　}</b></p><p>　　public DocData Parse() {</p><p>　　// 創(chuàng)建一個(gè) DocP

75、arser 來解析文檔。 </p><p>　　DocParser parser = new DocParser(this);</p><p>　　// 使用 DocParser 來為添加的每個(gè)文件和文件夾單獨(dú)解析。</p><p>　　for(int i = 0; i < Items.Count; i++) { </p>

76、<p>　　parser.ParseItem(Items[i]);</p><p><b>　　}</b></p><p>　　// 返回解析之后得到的原始文檔數(shù)據(jù)。 </p><p>　　return parser.Data;</p><p><b>　　}</b>

77、;</p><p>　　文檔解析后得到一個(gè) DocData 對(duì)象，它是 DocGenerator 的輸入。</p><p>　　為了支持多語言的文檔生成，這里還定義了一個(gè)DocProjectBase 類，然后可以使用工廠模式創(chuàng)建不同語言的 DocProject 對(duì)象 。</p><p>　　工廠模式是用于將生成對(duì)象的步驟進(jìn)行封裝的創(chuàng)建型模式[16]。</p&g

78、t;<p>　　DocParser類的實(shí)現(xiàn)</p><p>　　DocParser 會(huì)先解析語法樹，同時(shí)提取注釋節(jié)點(diǎn)。</p><p>　　語法樹是分析樹的濃縮表示，對(duì)表示語言結(jié)構(gòu)是有用的。語法樹作為中間表示，允許把翻譯從分離處理。在分析期間完成翻譯固然有很多郵電，但也存在一些問題，如在分析期間調(diào)用的翻譯例程受到兩個(gè)限制。首先，適于分析的文法可能并不反映語言成分的自然層次結(jié)構(gòu)

79、。其次，分析方法對(duì)分析樹結(jié)點(diǎn)的考察次序有一定的限制，它所限制的次序肯能和一個(gè)結(jié)構(gòu)中各成分信息的使用次序并不一致[17]。</p><p>　　DocParser 主要提供的是解析文件的接口。解析文件先將文件解析成語法樹。以下是解析文件的偽代碼:</p><p>　　public void ParseFile(string path, string file) {</p>&l

80、t;p>　　_currentSource = file;</p><p>　　_comments.Clear();</p><p><b>　　// 解析語法樹。</b></p><p>　　Script script = _parser.ParseFile(path, _project.Encoding);</p><

81、;p>　　ParseScript(script);</p><p><b>　　}</b></p><p>　　然后對(duì)語法樹進(jìn)行分析遍歷。</p><p>　　void ParseScript(Script script) {</p><p>　　// 獲取語法分析返回的注釋列表。</p><p

82、>　　DocComment[] map = _comments.ToArray();</p><p>　　// 進(jìn)行文檔解析。</p><p>　　_docAstVistor.Parse(script, map);</p><p><b>　　// 文檔合成。 </b></p><p>　　_docMerger.P

83、arse(map);</p><p><b>　　}</b></p><p>　　DocParser 還負(fù)責(zé)提取源碼中的注釋。但真正的解析操作是調(diào)用 JavaCommentParser 類完成的。 </p><p>　　JavaCommentParser 類的實(shí)現(xiàn)</p><p>　　JavaCommentParser

84、負(fù)責(zé)解析一個(gè)文檔注釋，然后得到一個(gè)注釋的信息，并將這些信息存入一個(gè) DocComment 實(shí)例。JavaCommentParser 在設(shè)計(jì)上使用單例模式以節(jié)約內(nèi)存。JavaCommentParser 的主要功能其實(shí)就是注釋片段的詞法解析。這樣無論注釋怎么寫，其它程序都可以統(tǒng)一處理，而不需要關(guān)心原注釋的格式問題。</p><p>　　JavaScript 語法樹構(gòu)建器的實(shí)現(xiàn)</p><p>

85、　　文檔解析要求語法樹構(gòu)建器提供這兩個(gè)特別的功能:</p><p>　　允許文檔解析器處理文檔中的注釋，而不是忽略這些注釋。</p><p><b>　　允許忽略語法錯(cuò)誤。</b></p><p>　　所以網(wǎng)上沒有現(xiàn)成的滿足這兩個(gè)特別需求的解析器，因此這里重復(fù)開發(fā)了一個(gè)JavaScript語法構(gòu)建器。構(gòu)建器是完全按照 ECMA 262 中規(guī)定的

86、文法完成的。</p><p>　　語法解析器提供了一個(gè) IDocParser 接口，如果外界需要處理在語法解析同時(shí)解析注釋，可以定義一個(gè)類來實(shí)現(xiàn)這個(gè)接口，并綁定這個(gè)類到語法解析器。這里由DocParser 負(fù)責(zé)實(shí)現(xiàn)這個(gè)接口，它會(huì)攔截 /** 開頭的注釋進(jìn)行文檔解析。</p><p>　　DocAstVistor 類的實(shí)現(xiàn)</p><p>　　DocAstVistor

87、 主要的目標(biāo)是遍歷語法樹，根據(jù)語法樹的信息自動(dòng)填充文檔注釋。因此，DocAstVistor 可以讓文檔作者少寫很多注釋內(nèi)容。</p><p>　　DocAstVistor 所做的主要工作有:</p><p><b>　　自動(dòng)識(shí)別變量名:</b></p><p><b>　　比如有代碼:</b></p><

88、;p><b>　　/**說明*/</b></p><p>　　var a = 2;</p><p>　　DocAstVistor 可以根據(jù)代碼中的變量a，將注釋補(bǔ)成 /**說明 @name a*/ ，這樣在最后的文檔中就可以告訴用戶這是一個(gè)名字為a的變量。調(diào)用時(shí)也使用這個(gè)名字。</p><p><b>　　自動(dòng)識(shí)別所屬成員:&l

89、t;/b></p><p><b>　　比如有代碼:</b></p><p>　　/**@class A*/</p><p><b>　　/**說明*/</b></p><p>　　var a = 2;</p><p>　　此時(shí)的a 會(huì)根據(jù)就近原則自動(dòng)歸類成 class

90、 A 的一個(gè)字段。</p><p><b>　　自動(dòng)識(shí)別默認(rèn)值</b></p><p><b>　　比如有代碼:</b></p><p><b>　　/**說明*/</b></p><p>　　var a = 2;</p><p>　　其默認(rèn)值是 2，這

91、個(gè)信息即可在最終的文檔顯示。</p><p><b>　　自動(dòng)識(shí)別參數(shù)信息</b></p><p>　　函數(shù)定義里面已經(jīng)寫明了參數(shù)名，這時(shí)用戶不需要在文檔里重復(fù)寫明這些信息。DocAstVistor 可以自動(dòng)填充參數(shù)的信息。</p><p>　　DocMerger 類的實(shí)現(xiàn)</p><p>　　經(jīng)過 DocAstVist

92、or 解析出來的文檔是一個(gè)列表。DocMerger 可以將這個(gè)列表形狀改寫成對(duì)應(yīng)的變量樹結(jié)構(gòu)。比如:</p><p>　　Class1.a 方法</p><p>　　Class2.b 方法</p><p>　　Class1.e 屬性</p><p>　　經(jīng)過 DocMerger 改寫后可以得到:</p><p><

93、;b>　　Class1 類:</b></p><p>　　成員有: a方法， e屬性</p><p><b>　　Class2 類:</b></p><p>　　成員有: b 方法。</p><p>　　DocMerger 處理過的文檔已經(jīng)接近人能直接閱讀的組織結(jié)構(gòu)了。</p><p

94、>　　DocGenerator 類的實(shí)現(xiàn)</p><p>　　DocParser 負(fù)責(zé)解析文檔的原始數(shù)據(jù)，而 DocGenerator 則根據(jù)原始數(shù)據(jù)來生成最后的文檔頁面。DocGenerator 主要做三件事情:</p><p>　　遍歷文檔注釋列表，為每一個(gè)注釋生成一個(gè)詳細(xì)信息。</p><p>　　遍歷變量樹，用于文檔的導(dǎo)航。</p>&l

95、t;p>　　遍歷源文件，并拷貝到文檔中，方便在文檔中查看API的源文件。</p><p><b>　　軟件主體</b></p><p><b>　　界面布局</b></p><p>　　需求中指出，軟件在使用時(shí)不僅只有一個(gè)窗口，還需要多個(gè)子窗口。所以，主窗體的布局使用分欄模式。最后的界面設(shè)計(jì)如圖 4-4。</p

96、><p><b>　　\</b></p><p>　　圖 44軟件主體的布局</p><p>　　軟件使用.Net 提供的 SplitContainer 控件將窗口分成3塊，每塊都是允許折疊的區(qū)域。在運(yùn)行時(shí)移動(dòng)鼠標(biāo)到拆分器控件上面， 會(huì)出現(xiàn)左右箭頭光標(biāo)，此時(shí)可以調(diào)節(jié)拆分器兩邊的寬度[18]。但 SplitContainer 只支持上下或左右的分割

97、，所以，這里使用2個(gè)SplitContainer 進(jìn)行嵌套，首先是上下分割的容器，然后對(duì)上容器進(jìn)行左右分割。如此，就能實(shí)現(xiàn)圖中的布局效果。</p><p><b>　　項(xiàng)目操作</b></p><p>　　所有的操作都是以項(xiàng)目為單位的，用戶可以新建、打開或保存項(xiàng)目。一次文檔生成也被理解是為對(duì)項(xiàng)目的編譯。</p><p>　　項(xiàng)目在保存時(shí)使用XM

98、L格式， XML(eXtensible Markup Language) 是SGML的一個(gè)子集……其目標(biāo)是能夠以目前HTML可能實(shí)現(xiàn)的方式在Web上使用、接受和處理通用SGML。XML的設(shè)計(jì)目標(biāo)是實(shí)現(xiàn)簡(jiǎn)便并且能與SGML和HTML共同操作[19]。在.NET中，XML作為數(shù)據(jù)格式和ADO.NET一起使用，發(fā)揮了重要的作用[20]。.net內(nèi)置了XML解析器，讓項(xiàng)目保存和載入功能很方便完成。</p><p>　　因

99、為所有的項(xiàng)目配置都存儲(chǔ)在 DocProject 中，因此保存和載入項(xiàng)目其實(shí)就是序列號(hào)和反序列化這個(gè)對(duì)象的過程。DocProject 本身是一個(gè)哈希表，因此保存和讀取項(xiàng)目時(shí)只要遍歷其所有的鍵值對(duì)即可。</p><p><b>　　軟件實(shí)現(xiàn)</b></p><p>　　最后的生成軟件是一個(gè)小巧的WinForm本地軟件。軟件界面如圖4-5。</p><p

100、>　　用戶可以點(diǎn)擊文件/新建項(xiàng)目，然后點(diǎn)擊添加文件來添加要生成的源文件，也可以通過拖動(dòng)來添加需要的文件和文件夾。列表框允許用戶選擇一項(xiàng)或多項(xiàng)，然后對(duì)這些項(xiàng)進(jìn)行刪除或移動(dòng)操作，為了方便用戶確認(rèn)源文件，雙擊任一項(xiàng)可以幫助用戶定位該項(xiàng)在資源管理器的位置。用戶編輯的界面效果如圖4-6。</p><p>　　點(diǎn)擊屬性可以打開屬性面板，如圖4-7。</p><p>　　屬性面板是一個(gè) .net

101、的 PropertyGrid 控件，該控件允許向用戶顯示一個(gè)表格，并通過這個(gè)表格修改一個(gè)代碼中的任何對(duì)象。這里屬性面板就是一個(gè)編輯 DocProject 對(duì)象的 PropertyGrid 控件。</p><p>　　最后點(diǎn)擊生成，等待軟件生成完成。生成時(shí)，軟件會(huì)自動(dòng)向用戶展示控制臺(tái)窗口。生成時(shí)的界面如圖4-8。</p><p>　　圖 45軟件主體運(yùn)行界面</p><

102、p><b>　　圖 46編輯項(xiàng)目</b></p><p>　　圖 47設(shè)置項(xiàng)目屬性</p><p><b>　　圖 48控制臺(tái)</b></p><p><b>　　文檔頁面</b></p><p>　　生成的文檔是一個(gè)一頁式的富互聯(lián)網(wǎng)應(yīng)用。</p>&

103、lt;p>　　文檔頁面使用左右布局。左側(cè)顯示導(dǎo)航條。右側(cè)顯示溫度內(nèi)容。</p><p>　　導(dǎo)航條是一個(gè)樹結(jié)構(gòu)的界面，一開始導(dǎo)航顯示了全部的全局類，點(diǎn)擊任一個(gè)類名字后可以展開顯示這個(gè)類對(duì)應(yīng)的成員。為了保證文檔的載入速度，導(dǎo)航條的所有項(xiàng)都是按需加載的，而不是一次性全部載入完。比如當(dāng)用戶需要顯示 Array.prototype.each 方法對(duì)應(yīng)的API信息時(shí)，導(dǎo)航才會(huì)讀取并顯示Array類的其它成員列表。&l

104、t;/p><p>　　文檔右側(cè)的數(shù)據(jù)是當(dāng)用戶點(diǎn)擊左邊的導(dǎo)航時(shí)，通過JSONP自動(dòng)載入過來的。載入之后通過JavaScript模板引擎解析成HTML代碼，然后向用戶顯示。而用于JSONP載入的數(shù)據(jù)則是文檔生成時(shí)生成的文件。</p><p>　　頁面嘗試使用文件夾類似層次結(jié)構(gòu)來組織URL，從而可以按照層次結(jié)構(gòu)閱讀URL[21]。</p><p>　　為了允許用戶點(diǎn)擊后退瀏覽

105、器時(shí)可以顯示上一個(gè)文檔項(xiàng)，網(wǎng)頁上使用hash change技術(shù)，通過改變地址的哈希值來偽造訪問歷史。每當(dāng)URL改變時(shí)(主要是哈希值改變)，系統(tǒng)會(huì)自動(dòng)分析新的URL信息，并向用戶展示當(dāng)前URL對(duì)應(yīng)的文檔頁。</p><p><b>　　最后界面效果如圖:</b></p><p><b>　　圖 49文檔界面</b></p><

106、p><b>　　在線文檔評(píng)論</b></p><p>　　為了支持文檔在線評(píng)論，在文檔中顯示一些界面讓用戶添加和瀏覽評(píng)論。如圖</p><p><b>　　圖 410評(píng)論框</b></p><p>　　當(dāng)用戶點(diǎn)擊提交時(shí)，評(píng)論框里的數(shù)據(jù)就會(huì)被通過JSONP方式來提交給ASP.NET網(wǎng)站提供接口程序。這里使用JSONP

107、方式而不是其它的AJAX方式，是因?yàn)榻涌谔峁┏绦蚝臀臋n本身可能不在一個(gè)域名下，而只有JSONP才能跨域保存數(shù)據(jù)。</p><p>　　ASP.NET中用于支持評(píng)論的接口如表 4-1。</p><p><b>　　表4-1接口設(shè)計(jì)</b></p><p>　　用于保存評(píng)論的數(shù)據(jù)庫結(jié)構(gòu)如表 4-2。</p><p>　　用戶

108、可以文檔中的docplus.js中配置服務(wù)器所在地址，然后文檔負(fù)責(zé)提供和顯示數(shù)據(jù)。后臺(tái)負(fù)責(zé)接收和處理數(shù)據(jù)。</p><p><b>　　表4-2數(shù)據(jù)庫設(shè)計(jì)</b></p><p><b>　　文檔調(diào)試工具</b></p><p>　　圖 411文檔調(diào)試工具</p><p>　　文檔調(diào)試工具主要用于

109、快速調(diào)試文檔。</p><p>　　軟件界面相對(duì)比較簡(jiǎn)單，左邊為輸入的源碼，右邊顯示解析的結(jié)果。用戶可以很方便地根據(jù)結(jié)果反復(fù)修改源碼中的文檔注釋。</p><p>　　文檔調(diào)試工具的布局和軟件主體一樣。</p><p>　　為了在編輯代碼時(shí)可以有語法高亮的功能，此處使用了開源的 ScintillaNET 控件。</p><p>　　軟件主要提

110、供3個(gè)功能:</p><p>　　文檔解析: 解析最終的文檔數(shù)據(jù)。</p><p>　　文檔注釋: 僅提取注釋而不解析。這個(gè)功能可以方便用戶驗(yàn)證文檔出現(xiàn)錯(cuò)誤時(shí)，是文檔注釋本身的錯(cuò)誤，還是解析時(shí)發(fā)生的邏輯錯(cuò)誤。如果是因?yàn)橛脩艄P誤(比如少寫一個(gè)字母)而導(dǎo)致的錯(cuò)誤，那么通過文檔注釋可以快速定位錯(cuò)誤。</p><p>　　語法解析: 不解析注釋，僅解析代碼語法。</p

111、><p><b>　　第五章 系統(tǒng)測(cè)試</b></p><p><b>　　單元測(cè)試</b></p><p>　　測(cè)試系統(tǒng)的第一步是測(cè)試組成該系統(tǒng)的單個(gè)構(gòu)建。測(cè)試這些構(gòu)件成為單元測(cè)試(unit testing)[22]。但由于項(xiàng)目時(shí)間較緊，因此未對(duì)所有模塊進(jìn)行單元測(cè)試，而只是針對(duì)文檔生成核心中的詞法解析和語法解析部分進(jìn)行單元測(cè)

112、試。</p><p><b>　　系統(tǒng)功能測(cè)試</b></p><p>　　在單元測(cè)試和集成測(cè)試中，我們的目標(biāo)是確信代碼正確實(shí)現(xiàn)了設(shè)計(jì)。在系統(tǒng)測(cè)試(system testing)中，我們的目標(biāo)是確保實(shí)際運(yùn)行的系統(tǒng)做了客戶想要做它做的工作[22]。</p><p>　　Ext 是一個(gè)大型的類似RAD工具的UI庫[23]，其代碼量大、文檔豐富。因此

113、本次測(cè)試使用了EXT源碼測(cè)試用例。</p><p>　　經(jīng)測(cè)試，全部文檔生成共使用8分鐘，軟件無崩潰現(xiàn)象，文檔成功生成。并且文檔的正確性也可以保證。</p><p><b>　　第六章 總結(jié)</b></p><p><b>　　完成的工作 </b></p><p>　　本文主要講述了JavaScri

114、pt文檔生成軟件的全部開發(fā)流程，其中重點(diǎn)介紹了文檔解析的算法和實(shí)現(xiàn)。</p><p>　　軟件最后可以穩(wěn)定運(yùn)行，并成功完成文檔生成的任務(wù)。</p><p>　　此軟件的實(shí)現(xiàn)用到了很多領(lǐng)域的知識(shí)，包括編譯原理、WinForm開發(fā)和ASP.NET開發(fā)。一份優(yōu)秀的API文檔需要在各個(gè)細(xì)節(jié)上都有著優(yōu)秀的體驗(yàn)，無論是從頁面的加載速度，還是到每個(gè)參數(shù)類型的完整解釋，都需要用大量時(shí)間去做好，這樣才能充分

115、發(fā)揮文檔的作用。整個(gè)項(xiàng)目的源碼超過2萬行。雖然開發(fā)中期經(jīng)歷了各種困難，但幸好我可以如期完成它。</p><p>　　開發(fā)過程中，我查閱了很多文檔。我仔細(xì)研究了國(guó)外同類產(chǎn)品的文檔，模仿它們的一些優(yōu)秀設(shè)計(jì)，并保證軟件一定程度上和它們兼容。期間，我對(duì)代碼經(jīng)過三次重構(gòu)，最后終于保證代碼結(jié)構(gòu)的清晰。這也方便其他人對(duì)項(xiàng)目進(jìn)行改造以加入一些自定義功能。</p><p>　　希望這個(gè)軟件可以成功投入使用并

116、最終解決一直為人苦惱的JavaScript 文檔生成問題。</p><p><b>　　下一步工作</b></p><p>　　雖然文檔解析能夠智能解析一部分注釋，但是解析還是比較依賴文檔注釋的。如果文檔注釋寫錯(cuò)或缺失，就可能導(dǎo)致生成的文檔不正確。完美的文檔生成解決方案應(yīng)該可以分析代碼、模擬執(zhí)行代碼，并根據(jù)執(zhí)行結(jié)果生成最終文檔，而不是僅僅依靠注釋的。下一版可以在注釋分

117、析上更加智能化，減少注釋分析時(shí)對(duì)注釋的依賴。</p><p>　　除了JavaScript，還有很多類似的腳本語言都缺少相應(yīng)的文檔解析工具。大部分語言都是相似的，軟件可以根據(jù)JavaScript的語法解析器進(jìn)行改造，并繼續(xù)開發(fā)其它語言的文檔解析功能，并最終統(tǒng)一不同語言的API文檔風(fēng)格，這樣可以有效降低讀者學(xué)習(xí)的成本。</p><p><b>　　參考文獻(xiàn)</b><

118、;/p><p>　　冉曉雯.ASP.NET 3.5 完全學(xué)習(xí)手冊(cè)[M].北京:清華大學(xué)出版社,2009</p><p>　　托洛斯 (Tulloch, M.). 天宏工作室譯.IIS 6 管理指南[M].北京:清華大學(xué)出版社, 2004</p><p>　　鄭阿奇.Access 實(shí)用教程(2007版) [M].北京:電子工業(yè)出版社, 2011,1</p>

119、<p>　　Mickey Williams.Visual c#．冉曉曼，羅鄧，郭炎譯.NET技術(shù)內(nèi)幕[M]．北京:清華大學(xué)出版社,2003</p><p>　　錢哨.C# WinForm實(shí)踐開發(fā)教程[M].中國(guó)水利水電出版社,2011</p><p>　　莫雯尼(Moroney, L). 華中宇等譯.ASP.NET基礎(chǔ)基礎(chǔ)[M].北京:人民郵電出版社,2009</p>