開題報(bào)告--javascript在線api文檔生成

1、<p>　　本科畢業(yè)設(shè)計(jì)開題報(bào)告</p><p><b>　?。?012屆）</b></p><p>　　論文題目 JavaScript在線API文檔生成</p><p>　　JavaScript在線API文檔生成</p><p><b>　　選題的背景與意義</b></p>

2、<p>　　1.1研究開發(fā)的目的</p><p>　　隨著軟件工程的規(guī)模越來(lái)越大，參與項(xiàng)目的人數(shù)也越來(lái)越多，因此非常需要有API文檔來(lái)描述各個(gè)模塊的功能，以讓團(tuán)隊(duì)內(nèi)的成員無(wú)需關(guān)心其它人的編碼細(xì)節(jié)就能協(xié)調(diào)開發(fā)，減少溝通成本。</p><p>　　API文檔可以讓作者自己書寫，但毫無(wú)疑問書寫文檔的時(shí)間是非常長(zhǎng)的，而且現(xiàn)代軟件項(xiàng)目的需求經(jīng)常改變，這就意味著每次修改需求都要重新修改源

3、碼和對(duì)應(yīng)的文檔，其維護(hù)的成本是相當(dāng)大的。因此現(xiàn)實(shí)很少有人會(huì)花額外時(shí)間來(lái)編輯API文檔。</p><p>　　如果將文檔直接以注釋的方式寫進(jìn)代碼里，這樣源碼和文檔總是出現(xiàn)在一起，修改的時(shí)候可以一并修改，這樣就能大大減少維護(hù)文檔的時(shí)間成本了。同時(shí)也方便其他人在閱讀源碼時(shí)通過注釋來(lái)更直觀地理解功能。</p><p>　　文檔生成工具可以提取源碼中的注釋，并最后生成一個(gè)可供人直接閱讀的API文檔。

4、使用一些工具來(lái)生成API文檔自然可以節(jié)約額外的文檔書寫時(shí)間，也可以在源碼被修改后重新生成文檔，而不需要每次都手寫文檔。因此，開發(fā)一個(gè)優(yōu)秀的文檔生成工具是非常有必要的。</p><p>　　傳統(tǒng)的API文檔都是一個(gè)類似word的本地?cái)?shù)據(jù)文件，它確實(shí)完成了API文檔所應(yīng)該擁有的功能。但在 web2.0 時(shí)代，如果能讓更多人通過網(wǎng)頁(yè)參與API文檔內(nèi)容的討論，則可以幫助作者修正錯(cuò)誤，更幫助其他讀者理解。同時(shí)還能讓來(lái)自不同

5、地區(qū)的讀者在網(wǎng)站上共同學(xué)習(xí)、共同進(jìn)步。因此生成的文檔可以讓讀者可以就某個(gè)API進(jìn)行評(píng)論。</p><p>　　在線API文檔也方便讀者瀏覽文檔，讀者不需要安裝額外的軟件，只需一個(gè)瀏覽器即可直接打開文檔。</p><p>　　1.2國(guó)內(nèi)外研究發(fā)展現(xiàn)狀</p><p>　　目前主流的編程語(yǔ)言都有相應(yīng)的文檔生成工具。比如Java語(yǔ)言可以使用javadoc來(lái)生成文檔，生成的

6、文檔非常精確， C#有開源的NDoc[1] 項(xiàng)目。</p><p>　　目前國(guó)外最有名的JavaScript文檔生成工具為jsdoc toolkit[2]，它的工作原理是在強(qiáng)制作者在代碼中書寫一些標(biāo)記，然后jsdoc文檔會(huì)分析這些標(biāo)記來(lái)構(gòu)建文檔，并確保最后生成的文檔是正確的。雖然使用這個(gè)方式比較容易理解和使用，但由于它只分析這些標(biāo)記，而忽略源碼本身，很多可以從源碼中得到的信息必須在標(biāo)記中重新寫明，所以讓文檔書寫的

7、工作量倍增。此外，它還具有以下缺點(diǎn)：</p><p>　　1.只有命令行模式，新用戶不容易上手。</p><p>　　2.由于是國(guó)外的項(xiàng)目，中文容易出現(xiàn)亂碼。</p><p>　　3.生成的文檔比較簡(jiǎn)單，信息量少。</p><p>　　因此它不是完美的解決方案。</p><p>　　目前最有名的在線API文檔系統(tǒng)

8、為MSDN，MSDN 庫(kù)為使用 Microsoft® 工具、產(chǎn)品、技術(shù)和服務(wù)的開發(fā)人員提供必不可少的信息資源。MSDN 庫(kù)包含操作方法和參考文檔、示例代碼、技術(shù)文章和其他內(nèi)容。但 MSDN 僅針對(duì)指定平臺(tái)才能使用，而且MSDN是不開源的，無(wú)法被其他用戶使用[3]。</p><p>　　研究開發(fā)的基本內(nèi)容、目標(biāo)，擬解決的主要問題或技術(shù)關(guān)鍵</p><p>　　2.1研究開發(fā)的內(nèi)容&

9、lt;/p><p>　　本研究是針對(duì)JavaScript 語(yǔ)言的文檔生成。</p><p>　　程序數(shù)據(jù)流圖如圖2-1所示。</p><p><b>　　圖2-1 數(shù)據(jù)流圖</b></p><p><b>　　文檔分析</b></p><p>　　根據(jù)指定的源碼解析得到文檔的原始

10、數(shù)據(jù)。分析算法是整個(gè)研究的重點(diǎn)課題。</p><p>　　文檔分析內(nèi)主要經(jīng)過詞法分析[3]、注釋分析、語(yǔ)法分析[4]、注釋語(yǔ)義分析、合成文檔這幾個(gè)步驟。詞法分析和注釋分析同時(shí)進(jìn)行，它的目標(biāo)是提取源碼的注釋和代碼。詞法分析可以輸出得到全部標(biāo)識(shí)符。語(yǔ)法分析時(shí)根據(jù)詞法分析得到標(biāo)識(shí)符構(gòu)建語(yǔ)法樹。語(yǔ)法樹包含了所有的源碼信息。在得到了源碼的結(jié)構(gòu)和注釋信息后，即可開始注釋語(yǔ)義分析，它一邊遍歷語(yǔ)法樹，一邊分析每個(gè)注釋的含義，并得

11、出一個(gè)完整的變量集合，變量集合包含了所有被成功解析的注釋的信息。最后分析變量集合提取最終的文檔信息。最終的文檔數(shù)據(jù)以XML格式保存。</p><p><b>　　展示網(wǎng)站</b></p><p>　　為了方便用戶在線瀏覽文檔，必須提供一個(gè)網(wǎng)站形式的文檔系統(tǒng)。這個(gè)網(wǎng)站可以讀取XML格式的文檔并以網(wǎng)頁(yè)形式展示。同時(shí)網(wǎng)站還允許用戶登錄以每個(gè)API接口進(jìn)行討論。</p&

12、gt;<p><b>　　用戶操作界面</b></p><p>　　為了用戶可以方便地使用軟件來(lái)生成，軟件必須提供一個(gè)圖形操作界面。操作界面的主要功能就是讓用戶選擇需要生成文檔的源文件位置，然后即可運(yùn)行得到最終的文檔。</p><p>　　2.2研究開發(fā)的基本目標(biāo)</p><p>　　該軟件主要分三個(gè)部分：</p>

13、<p>　　軟件主體。本程序目標(biāo)用戶為源碼作者，這些用戶可以通過這個(gè)軟件進(jìn)行文檔生成操作，同時(shí)軟件也會(huì)向它們報(bào)告解析錯(cuò)誤。</p><p>　　文檔網(wǎng)站。網(wǎng)站用于展示文檔，同時(shí)網(wǎng)站允許使用不同的模板風(fēng)格，方便用戶自定義網(wǎng)站。</p><p>　　可以為最終用戶提供聯(lián)機(jī)使用幫助，包括本系統(tǒng)的說明信息、使用方法和步驟以及版權(quán)信息和聯(lián)系方式等。</p><p>

14、　　2.3擬解決的主要問題或技術(shù)關(guān)鍵</p><p><b>　　準(zhǔn)確地分析</b></p><p>　　文檔生成工具應(yīng)該自動(dòng)分析注釋上下文，自動(dòng)決定注釋含義，以保證文檔的正確性。因?yàn)槔煤镁幾g原理的相關(guān)內(nèi)容是分析的關(guān)鍵。</p><p><b>　　友好的用戶界面</b></p><p>　　用戶

15、的操作應(yīng)該盡量簡(jiǎn)單。如果出現(xiàn)錯(cuò)誤，應(yīng)該更友好地提示，以方便用戶快速找到和修正它們。</p><p><b>　　允許自定義網(wǎng)站模板</b></p><p>　　最后生成的網(wǎng)站必須支持自定義模板，以符合不同人的需求。</p><p>　　研究開發(fā)的方法、技術(shù)路線和步驟</p><p>　　3.1研究開發(fā)的方法</p&

16、gt;<p>　　要實(shí)現(xiàn)完整的文檔生成，需要用到WinForm開發(fā)、ASP.NET開發(fā)、SQL、編譯原理相關(guān)的技術(shù)。其中核心是語(yǔ)法和文檔解析的過程。</p><p><b>　　轉(zhuǎn)換思想[5]</b></p><p>　　軟件理論中的編譯方法學(xué)包括編譯與解釋2 種。解釋程序是一種語(yǔ)言處理程序，它對(duì)源程序的處理可以是輸入一句，解釋一句，主要包括換碼、編輯和

17、執(zhí)行三個(gè)階段。由于解釋也是涉及兩種不同程序語(yǔ)言的轉(zhuǎn)換，因此可將這種轉(zhuǎn)換思想用于文檔解析的過程。</p><p>　　編譯方法學(xué)中的識(shí)別原理</p><p>　　用詞法分析程序[6]從一串?dāng)?shù)據(jù)流中區(qū)別出單個(gè)的字符后，便完成了詞法分析的任務(wù)，接下來(lái)所進(jìn)行的語(yǔ)法分析目的是區(qū)分不同類別的字符。</p><p>　　語(yǔ)句中專用標(biāo)識(shí)符的處理</p><p&g

18、t;　　專用標(biāo)識(shí)符包括函數(shù)標(biāo)識(shí)符，命令符等，這些專用標(biāo)識(shí)符及他們對(duì)應(yīng)的地址組成線性表的。一個(gè)數(shù)據(jù)單元 線性表的起始單元地址保存在內(nèi)存中。</p><p>　　語(yǔ)句中其余自定義部分的處理</p><p>　　除了專用標(biāo)識(shí)符是固定的數(shù)目外，還有一種用戶自定義的標(biāo)識(shí)符，數(shù)目不能確定，包括簡(jiǎn)單變量，下標(biāo)變量和自定義函數(shù)等。在這種情況下，也是要構(gòu)造一個(gè)名字表，不同于前面專用標(biāo)識(shí)符名字表的是這里的名字

19、表不是一張已固定的造好的表，而是一張動(dòng)態(tài)的邊造邊查的表，當(dāng)一個(gè)新的標(biāo)識(shí)符出現(xiàn)時(shí) 查找這張表 如果這個(gè)標(biāo)識(shí)符已在表中，則查這個(gè)標(biāo)識(shí)符對(duì)應(yīng)的其它內(nèi)容， 如果這個(gè)標(biāo)識(shí)符不在表中，則在表的末尾增加一個(gè)數(shù)據(jù)單元，填入這個(gè)新的標(biāo)識(shí)符以及它在表中的序號(hào)[7]。</p><p>　　圖3-1 詞法分析器和語(yǔ)法分析器的相互作用[5]</p><p><b>　　文檔注釋的詞法解析</b>

20、;</p><p>　　圖3-2分析注釋片段的有窮自動(dòng)機(jī)</p><p>　　文檔注釋是由多個(gè)注釋標(biāo)簽組成的，每個(gè)標(biāo)簽的格式為 @開頭的內(nèi)容。由于是注釋，所以 ‘@’前允許添加 ‘*’號(hào)。</p><p><b>　　系統(tǒng)流程</b></p><p>　　圖3-3 系統(tǒng)流程圖</p><p>　　

21、3.2系統(tǒng)開發(fā)擬采用的技術(shù)及開發(fā)環(huán)境</p><p>　　系統(tǒng)平臺(tái)：.Net Framework 3.5[8]</p><p>　　.Net Framework 壞境是支持生成和運(yùn)行下一代應(yīng)用程序和XML Web Service 的內(nèi)部 Windows 組件[9]</p><p>　　系統(tǒng)構(gòu)架：B/S構(gòu)架</p><p>　　B/S（Brow

22、ser/Server）結(jié)構(gòu)即瀏覽器和服務(wù)器結(jié)構(gòu)，隨著互聯(lián)網(wǎng)的快速發(fā)展，越來(lái)越多的應(yīng)用選擇了B/S構(gòu)架。相對(duì)于C/S結(jié)構(gòu)屬于“胖”客戶端，需要在使用者電腦上安裝相應(yīng)的操作軟件來(lái)說，B/S結(jié)構(gòu)是屬于一種“瘦”客戶端，大多數(shù)或主要的業(yè)務(wù)邏輯都存在于服務(wù)器端[10]。</p><p><b>　　編程語(yǔ)言：C#</b></p><p>　　C#是一種現(xiàn)代的面向?qū)ο蟮某绦蜷_發(fā)語(yǔ)

23、言它使得程序員能夠在新的微軟.NET 平臺(tái)上快速開發(fā)種類豐富的應(yīng)用程序.NET [8]。C#提供一些特性來(lái)幫助構(gòu)建健壯、耐用的應(yīng)用程序:垃圾收集會(huì)自動(dòng)回收不再使用的對(duì)象所占用的內(nèi)存;異常處理提供了一種結(jié)構(gòu)化且可擴(kuò)展的方式來(lái)檢測(cè)錯(cuò)誤和恢復(fù);而語(yǔ)言的類型安全設(shè)計(jì)則可以防止讀取未初始化的變量、數(shù)組越界或進(jìn)行未檢測(cè)的類型轉(zhuǎn)換[11]。</p><p>　　C#的Windows Forms給開發(fā)人員提供了創(chuàng)建基于Windo

24、ws的應(yīng)用程序所需的多種技術(shù)。不僅有用于調(diào)整用戶界面的新控件和特性，還提供了靈活的部署和集成的安全特性[12]。Windows窗體提供了一套豐富的控件，并且開發(fā)人員可以定義自己有特色的新的控件[13] 。</p><p>　　ASP.NET 是一個(gè)后臺(tái)動(dòng)態(tài)語(yǔ)言技術(shù)。它是開發(fā)人員和構(gòu)架師共同思考關(guān)于未來(lái)Web開發(fā)的發(fā)展方向而得出的結(jié)果[14]。本系統(tǒng)需要使用ASP.NET作為后臺(tái)提供評(píng)論服務(wù)接口。</p>

25、;<p>　　配置存儲(chǔ)格式：XML</p><p>　　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共同操作[15]。在.NET中，XML作為數(shù)據(jù)格式和ADO.NET一起使用，發(fā)揮了重要的作用[16]。</p>

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

27、器： IIS(Internet Information Server) 7</p><p>　　IIS是Internet Information Services的縮寫，是一個(gè)World Wide Web server。Gopher server和FTP server全部包容在里面。 IIS意味著你能發(fā)布網(wǎng)頁(yè)，并且有ASP（Active Server Pages）、JAVA、VBScript產(chǎn)生頁(yè)面，有著一些擴(kuò)展

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

29、用程序和移動(dòng)應(yīng)用程序[19]。Visual Studio 2010 是 Visual Studio 的最新正式版，它是目前最流行的 Windows平臺(tái)應(yīng)用程序開發(fā)環(huán)境[20]。</p><p>　　研究工作總體安排與時(shí)間進(jìn)度</p><p>　　論文研究及系統(tǒng)實(shí)現(xiàn)過程按任務(wù)主要分為以下幾個(gè)階段：</p><p>　　表4-1 時(shí)間進(jìn)度安排表</p>&

30、lt;p><b>　　參考文獻(xiàn)</b></p><p>　　NDoc[OL].http://ndoc.sourceforge.net/</p><p>　　jsdoc-toolkit[OL].http://code.google.com/p/jsdoc-toolkit/</p><p>　　MSDN[OL].http://msdn.mic

31、rosoft.com/library/ </p><p>　　李文生.編譯原理與技術(shù)[M]. 清華大學(xué)出版社,2009 </p><p>　　繆淮扣, 語(yǔ)言處理程序[M], 北京: 清華大學(xué)出版社, 1993</p><p>　　Alfred.V.Aho, Monica S.Lam, Ravi Sethi, Jeffrey D.Ullman 趙建華、鄭淘、戴新宇譯.

32、編譯原理.機(jī)械工業(yè)出版社.2007</p><p>　　冉曉雯.ASP.NET 3.5 完全學(xué)習(xí)手冊(cè)[M].北京:清華大學(xué)出版社,2009</p><p>　　百度百科.http://baike.baidu.com/view/7243689.htm</p><p>　　Bill Evjen, Scott Hanselman, Devin Rader, 李增民譯.

33、 ASP.NET 4高級(jí)編程:涵蓋C#和VB.NET(第7版)[M], 清華大學(xué)出版社,2010-9</p><p>　　Bill Evjen, Scott Hanselman, Devin Rader, 李增民譯. ASP.NET 4高級(jí)編程:涵蓋C#和VB.NET(第7版)[M], 清華大學(xué)出版社,2010-9</p><p>　　海杰爾斯伯格(Hejlsberg, A.). 顧雁

34、宏譯.C# 程序設(shè)計(jì)語(yǔ)言(原書第3版) [M].北京:機(jī)械工業(yè)出版社, 2009.9</p><p>　　Mickey Williams.Visual c#．冉曉曼，羅鄧，郭炎譯.NET技術(shù)內(nèi)幕[M]．北京:清華大學(xué)出版社,2003</p><p>　　弗雷澤(Stewart Fraser), 利文斯敦 (Steven Living stone) 毛堯飛, 崔偉譯.C# XML 入門經(jīng)典-

35、---C#編程人員必備的XML技能[M].北京:清華大學(xué)出版社, 2005</p><p>　　莫雯尼(Moroney, L). 華中宇等譯.ASP.NET基礎(chǔ)基礎(chǔ)[M].北京:人民郵電出版社,2009</p><p>　　賈小珠.深入淺出XML[M].北京:人民郵電出版社, 2001,9</p><p>　　弗雷澤(Stewart Fraser), 利文斯敦 (S

36、teven Living stone) 毛堯飛, 崔偉譯.C# XML 入門經(jīng)典----C#編程人員必備的XML技能[M].北京:清華大學(xué)出版社, 2005</p><p>　　托洛斯 (Tulloch, M.). 天宏工作室譯.IIS 6 管理指南[M].北京:清華大學(xué)出版社, 2004</p><p>　　百度百科. http://baike.baidu.com/view/28727.