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

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

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

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

4、生成操作，使用C#開發(fā)一個WinForm軟件。生成的文檔是一個普通的網(wǎng)頁，用戶可以自定義文檔界面模板。生成的文檔可以放在ASP.NET服務(wù)器上直接運行。讀者可以在線閱讀文檔，并在文檔的任何一頁添加評論。 </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國內(nèi)外研究發(fā)展現(xiàn)狀4</p><p>　　1.3研究開發(fā)的基本目標4</p><p>　　1.4本文的組織結(jié)構(gòu)5</p><p>　　第二章 方法與技術(shù)6</p><p>　　2.1軟件運行環(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 簡介6</p><p>　　2.3ASP.NET 簡介7</p><p>　　2.4AJAX 簡介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新建和保存項目10</p><p>　　3.1.3編輯項目10</p><p>　　3.1.4編譯項目11</p><p>　　3.2生成的文檔界面11</p><p>　　3.3用于在線可評論的文

16、檔12</p><p>　　3.4文檔調(diào)試工具12</p><p>　　第四章 系統(tǒng)設(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)的實體類14

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

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

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

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

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

22、lt;p><b>　　圖目錄</b></p><p>　　圖 11文檔注釋3</p><p>　　圖 21 Firebug 運行界面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軟件主體運行界面21</p><p>　　圖 46編輯項目21</p><p>　　圖 47設(shè)置項目屬性22</p><p>　　圖 48控制臺22

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

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

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

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

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

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

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

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

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

33、>　　文檔網(wǎng)站。網(wǎng)站用于展示文檔，同時網(wǎng)站允許使用不同的模板風(fēng)格，方便用戶自定義網(wǎng)站。</p><p>　　可以為最終用戶提供聯(lián)機使用幫助，包括本系統(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>　　第三章，重點介紹了文檔生成過程的具體需求。</p><p>　　第四章，對整個系統(tǒng)進行設(shè)計和實現(xiàn)。重點介紹分析算法的實現(xiàn)和最終文檔頁面的代碼設(shè)計。</p><p>　　第五章，系統(tǒng)測試與系統(tǒng)使用說

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

36、系統(tǒng)開發(fā)的主要難點，它需要用到編譯原理相關(guān)的知識。</p><p><b>　　軟件運行環(huán)境</b></p><p>　　本系統(tǒng)基于.Net Framework 3.5 壞境開發(fā)。.Net Framework 壞境是支持生成和運行下一代應(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的縮寫，是一個World Wide Web server。Gopher server和FTP server全部包容在里面。 IIS意味著你能發(fā)布網(wǎng)頁，并且有ASP（Active Server Pages）、JAVA、VBScript產(chǎn)生頁面，有著一些擴展功能[2]。</p><p>　　數(shù)據(jù)庫：Access2007</p><p>　　

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

40、ows窗體)是1個新的窗體包，它使得開發(fā)人員可以創(chuàng)建基于Windows的應(yīng)用程序，來充分利用Microsoft Windows操作系統(tǒng)中豐富的用戶界面特性。Windows Forms是新的Microsoft．NET Framework的一部分，它使用了許多新技術(shù)，包括1個公共應(yīng)用程序框架、受控的執(zhí)行環(huán)境、集成的安全性和面向?qū)ο蟮脑O(shè)計原則。此外，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平臺的語言。開發(fā)人員可以使用任何支持．NET平臺的語言。在Visual C#中構(gòu)建Windows窗體程序時需要向項目添加窗體，將控件拖放到窗體，然后在控件雙擊，即可編寫窗體背后的代碼。開發(fā)人員使用這種熟知的模型，來迅速地構(gòu)建桌面應(yīng)用程序。C#的Windows Forms有

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

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

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

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

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

47、重點是將源代碼翻譯成文檔，因此只需要編譯原理中詞法分析、語法分析的技術(shù)。</p><p>　　使用語法分析的方式來分析源碼是本軟件和jsdoc的最大的區(qū)別。Jsdoc 只以文本方式去分析注釋，它忽略了代碼本身所展示的信息。而如果先解析語法，然后進行文檔分析，就可以充分獲取語法樹種提供的信息來補全文檔。</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)架。相對于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)用程序:垃圾收集會自動回收不再使用的對象所占用的內(nèi)存;異常處理提供了一種結(jié)構(gòu)化且可擴展的方式來檢測錯誤和恢復(fù);而語言的類型安全設(shè)計則可以防止讀取未初始化的變量、數(shù)組越界或進行未檢測的類型轉(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ā)工具集，保護了大量的公墓內(nèi)，它主要用于生成 ASP.NET Web 應(yīng)用程序、XML Web Services、桌

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

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

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

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

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

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

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

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

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

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

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

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

63、修改才能確保最終生成的文檔是正確的。</p><p>　　但每次生成操作生成的是一個最終的文檔頁面，這是一個比較漫長的過程。因此還需要提供一個文檔調(diào)試工具，這個工具只解析文檔并向用戶報告文檔解析結(jié)果，而不生成最后的文檔。</p><p>　　用戶可以使用這個工具來排除文檔注釋中的錯誤，然后使用軟件主體來生成最后的文檔。</p><p>　　第四章 系統(tǒng)設(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 類負責(zé)管理整個文檔生成操作。文檔生成操作分 文檔解析 和 生成最終文件 兩步。文檔解析由 DocParser 類完成。生成最終文件由DocGenerator類完成。</p><p>　　因為文檔解析的步驟較為復(fù)雜，因此文件解析又分成語法樹解析、文檔注釋解析、文檔注釋分析、文檔注釋提取。這些操作分別由 Javascri

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

67、tNode 存儲某個節(jié)點的數(shù)據(jù)。比如 ReturnCommentNode 是一個包含 ReturnType 和 ReturnSummary 的一個結(jié)構(gòu)。</p><p>　　DocComment類</p><p>　　DocComment 表示文檔中的一個注釋信息，它是一個哈希表，存儲了標簽和值的一一對應(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>　　對應(yīng)解析的結(jié)果是一個 Do

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

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

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

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

73、，它存儲了一次文檔生成的全部配置。</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 進行最終文件生成。</p><p>　　new DocGenerator(this).Generate(data);</p><p><b>　　}</b></p><p>　　public DocData Parse() {</p><p>　　// 創(chuàng)建一個 DocP

75、arser 來解析文檔。 </p><p>　　DocParser parser = new DocParser(this);</p><p>　　// 使用 DocParser 來為添加的每個文件和文件夾單獨解析。</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>　　文檔解析后得到一個 DocData 對象，它是 DocGenerator 的輸入。</p><p>　　為了支持多語言的文檔生成，這里還定義了一個DocProjectBase 類，然后可以使用工廠模式創(chuàng)建不同語言的 DocProject 對象 。</p><p>　　工廠模式是用于將生成對象的步驟進行封裝的創(chuàng)建型模式[16]。</p&g

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

79、。其次，分析方法對分析樹結(jié)點的考察次序有一定的限制，它所限制的次序肯能和一個結(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>　　然后對語法樹進行分析遍歷。</p><p>　　void ParseScript(Script script) {</p><p>　　// 獲取語法分析返回的注釋列表。</p><p

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

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

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

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

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

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

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

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

90、 A 的一個字段。</p><p><b>　　自動識別默認值</b></p><p><b>　　比如有代碼:</b></p><p><b>　　/**說明*/</b></p><p>　　var a = 2;</p><p>　　其默認值是 2，這

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

92、or 解析出來的文檔是一個列表。DocMerger 可以將這個列表形狀改寫成對應(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 類的實現(xiàn)</p><p>　　DocParser 負責(zé)解析文檔的原始數(shù)據(jù)，而 DocGenerator 則根據(jù)原始數(shù)據(jù)來生成最后的文檔頁面。DocGenerator 主要做三件事情:</p><p>　　遍歷文檔注釋列表，為每一個注釋生成一個詳細信息。</p><p>　　遍歷變量樹，用于文檔的導(dǎo)航。</p>&l

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

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

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

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

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

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

101、的 PropertyGrid 控件，該控件允許向用戶顯示一個表格，并通過這個表格修改一個代碼中的任何對象。這里屬性面板就是一個編輯 DocProject 對象的 PropertyGrid 控件。</p><p>　　最后點擊生成，等待軟件生成完成。生成時，軟件會自動向用戶展示控制臺窗口。生成時的界面如圖4-8。</p><p>　　圖 45軟件主體運行界面</p><

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

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

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

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

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

107、方式而不是其它的AJAX方式，是因為接口提供程序和文檔本身可能不在一個域名下，而只有JSONP才能跨域保存數(shù)據(jù)。</p><p>　　ASP.NET中用于支持評論的接口如表 4-1。</p><p><b>　　表4-1接口設(shè)計</b></p><p>　　用于保存評論的數(shù)據(jù)庫結(jié)構(gòu)如表 4-2。</p><p>　　用戶

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

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

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

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

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

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

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

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

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

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

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

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