一種生成說明文檔的方法和裝置的制造方法
【技術(shù)領(lǐng)域】
[0001]本發(fā)明涉及計(jì)算機(jī)技術(shù)領(lǐng)域，尤其涉及一種生成說明文檔的方法和裝置。
【背景技術(shù)】
[0002]腳本語言是為了縮短傳統(tǒng)的編寫-編譯-鏈接-運(yùn)行過程而創(chuàng)建的計(jì)算機(jī)編程語言。JavaScript是一種應(yīng)用于Web的腳本語言，已經(jīng)被廣泛用于Web應(yīng)用開發(fā)。瀏覽器可以在JavaScript下編寫源碼來實(shí)現(xiàn)，不同瀏覽器的JavaScript源碼不同。由于不同瀏覽器的JavaScript源碼不同，所以不同的瀏覽器難以兼容。JavaScript框架能實(shí)現(xiàn)瀏覽器的兼容。
[0003]Angular JS是其中一種JavaScript框架。由于Angular JS當(dāng)前很熱門，所以程序開發(fā)人員熱衷于基于Angular JS來開發(fā)組件。眾所周知的是，在基于Angular JS對組件進(jìn)行開發(fā)的過程中，程序開發(fā)人員開發(fā)的組件需要有相應(yīng)的說明文檔，以向組件的使用者說明所開發(fā)的組件如何使用。
[0004]當(dāng)前，生成說明文檔的方法依賴于程序開發(fā)人員在編寫源碼過程中所寫的注釋。該方法主要包括以下幾步:獲取程序開發(fā)人員在編寫源碼過程中寫的注釋，對所獲取的注釋進(jìn)行解析以將其轉(zhuǎn)換成預(yù)定義的格式，生成說明文檔。說明文檔通常包括使用說明和示例代碼，示例代碼用于向組件的使用者展示對所開發(fā)的組件調(diào)用之后的運(yùn)行結(jié)果。
[0005]然而，現(xiàn)有的生成說明文檔的方法給程序開發(fā)人員造成了很大的負(fù)擔(dān)。一方面，由于該方法依賴于注釋，所以程序開發(fā)人員在編寫源碼的過程中不得不花大量的精力和時間來寫注釋，結(jié)果寫注釋成了程序開發(fā)人員的負(fù)擔(dān)；另一方面，因?yàn)檎f明文檔包含有示例代碼并且說明文檔的生成依賴于注釋，所以示例代碼只得包含在注釋中，這樣所造成的結(jié)果是:在對開發(fā)的組件進(jìn)行測試時，由于注釋中的內(nèi)容是不會被運(yùn)行的，所以包含在注釋中的示例代碼無法被重復(fù)利用，程序開發(fā)人員只得重新準(zhǔn)備一份測試代碼來測試開發(fā)的組件。

【發(fā)明內(nèi)容】

[0006]有鑒于此，本發(fā)明提供一種生成說明文檔的方法和裝置，以減輕程序開發(fā)人員的負(fù)擔(dān)。
[0007]—種生成說明文檔的方法，所述方法包括:
[0008]遍歷至少一個組件，查找使用者所需的組件；
[0009]從預(yù)先創(chuàng)建的第一文件中獲取使用者所需的組件的使用說明，所述第一文件獨(dú)立于保存源碼的文件；
[0010]從預(yù)先創(chuàng)建的第二文件中獲取使用者所需的組件的示例代碼，所述第二文件獨(dú)立于保存源碼的文件，并且所述第二文件中的示例代碼能夠運(yùn)行；
[0011]由獲取的所述使用說明和所述示例代碼生成使用者所需的組件的說明文檔。
[0012]優(yōu)選地，從預(yù)先創(chuàng)建的第一文件中獲取使用說明包括:
[0013]根據(jù)grunt的配置信息中預(yù)先定義的所述第一文件的文件名稱查找所述使用說明；
[0014]優(yōu)選地，從預(yù)先創(chuàng)建的第二文件中獲取示例代碼包括:
[0015]根據(jù)grunt的配置信息中預(yù)先定義的所述第二文件的文件名稱查找所述示例代碼。
[0016]優(yōu)選地，由獲取的使用說明和示例代碼生成組件的說明文檔包括:
[0017]將獲取的所述使用說明和所述示例代碼寫入grunt的配置信息中；
[0018]獲取所述說明文檔的html頁面模板；
[0019]將配置信息中的所述使用說明和所述示例代碼與所述html頁面模板進(jìn)行結(jié)合，從而生成html文檔形式的說明文檔。
[0020]優(yōu)選地，將配置信息中的所述使用說明和所述示例代碼與所述html頁面模板進(jìn)行結(jié)合包括:
[0021]將配置信息中的所述使用說明和所述示例代碼解析到所述html頁面模板中。
[0022]優(yōu)選地，將配置信息中的所述使用說明和所述示例代碼與所述html頁面模板進(jìn)行結(jié)合包括:
[0023]將配置信息中的所述示例代碼解析到所述html頁面模板中，并將配置信息中的使用說明保存在所述html頁面模板中。
[0024]—種生成說明文檔的裝置，所述裝置包括:
[0025]第一查找單元，用于遍歷至少一個組件，查找使用者所需的組件；
[0026]第一獲取單元，用于從預(yù)先創(chuàng)建的第一文件中獲取使用說明，所述第一文件獨(dú)立于保存源碼的文件；
[0027]第二獲取單元，用于從預(yù)先創(chuàng)建的第二文件中獲取示例代碼，所述第二文件獨(dú)立于保存源碼的文件，并且所述第二文件中的示例代碼能夠運(yùn)行；
[0028]生成單元，用于由獲取的所述使用說明和所述示例代碼生成組件的說明文檔。
[0029]優(yōu)選地，所述第一獲取單元包括:
[0030]第二查找單元，用于根據(jù)grunt的配置信息中預(yù)先定義的所述第一文件的文件名稱查找所述使用說明；
[0031]優(yōu)選地，所述第二獲取單元包括:
[0032]第三查找單元，用于根據(jù)grunt的配置信息中預(yù)先定義的所述第二文件的文件名稱查找所述示例代碼。
[0033]優(yōu)選地，所述生成單元包括:
[0034]寫入單元，用于將獲取的所述使用說明和所述示例代碼寫入grunt的配置信息中；
[0035]第三獲取單元，用于獲取所述說明文檔的html頁面模板；
[0036]結(jié)合單元，用于將配置信息中的所述使用說明和所述示例代碼與所述html頁面模板進(jìn)行結(jié)合，從而生成html文檔形式的說明文檔。
[0037]優(yōu)選地，所述結(jié)合單元包括:
[0038]第一解析單元，用于將配置信息中的所述使用說明和所述示例代碼解析到所述html頁面模板中。
[0039]優(yōu)選地，所述結(jié)合單元包括:
[0040]第二解析單元，用于將配置信息中的所述示例代碼解析到所述html頁面模板中；
[0041]保存單元，用于將配置信息中的使用說明保存在所述html頁面模板中。
[0042]可以看出，由于組件的使用說明和示例代碼均以獨(dú)立于源碼的形式保存在各自的文件中，不再包含在源碼的注釋中，所以程序開發(fā)人員在編寫源碼的過程中無需對注釋花費(fèi)過多精力和時間，并且由于本發(fā)明的示例代碼可以運(yùn)行，所以通過本發(fā)明，示例代碼還可以用于測試組件，故程序開發(fā)人員無需準(zhǔn)備兩份代碼分別用于生成說明文檔和測試組件，從而極大地減輕了程序開發(fā)人員的負(fù)擔(dān)。
【附圖說明】
[0043]圖1為本發(fā)明提供的一種方法的流程圖；
[0044]圖2為本發(fā)明實(shí)施例最終生成的html頁面形式的說明文檔的示意圖；
[0045]圖3為本發(fā)明實(shí)施例組件架構(gòu)示意圖；
[0046]圖4為本發(fā)明實(shí)施例提供的一種方法的流程圖；
[0047]圖5為本發(fā)明提供的一種裝置的框圖；
[0048]圖6為本發(fā)明實(shí)施例提供的一種裝置的框圖。
【具體實(shí)施方式】
[0049]在對詳細(xì)的描述進(jìn)行說明之前，應(yīng)該理解，用在本說明書以及權(quán)利要求中的術(shù)語及詞語可能不限于普通含義或詞典含義，而是在發(fā)明人能夠使用新詞以最佳方式解釋本發(fā)明的原則下，被解釋為適于本發(fā)明技術(shù)范圍的含義或概念。
[0050]本發(fā)明提供實(shí)施例使得公開充分并完全涵蓋本領(lǐng)域技術(shù)人員。對具體細(xì)節(jié)例如具體部件、裝置進(jìn)行闡述，以透徹理解本實(shí)施例。對本領(lǐng)域技術(shù)人員來說，顯然，不需要采用具體的細(xì)節(jié)，實(shí)施例可以以許多不同的形式進(jìn)行具體體現(xiàn)，而且不應(yīng)該解釋為對本發(fā)明范圍的限制。在一些實(shí)施例中，公知裝置結(jié)構(gòu)、以及公知技術(shù)不再詳細(xì)描述。
[0051]盡管術(shù)語第一、第二可以用來描述各種部件，這些部件不應(yīng)被這些術(shù)語限制。這些術(shù)語可以僅用來將一個部件與另一部件區(qū)別開來。除非上下文清楚地指出，當(dāng)使用例如“第一”、“第二”、以及其它數(shù)字術(shù)語這樣的術(shù)語時，不暗指序列或者順序。因此，在不背離實(shí)施例的原則的情況下，描述的第一部件可以被稱為第二部件。
[0052]在下文中，將參考附圖對本發(fā)明的示例性實(shí)施例進(jìn)行詳細(xì)描述。
[0053]本發(fā)明提供的方法不依賴于注釋，而是將生成說明文檔所需的示例代碼和使用說明分別獨(dú)立于源碼保存為單獨(dú)的文件，所以不必迫使程序開發(fā)人員在編寫源碼時以生成組建說明文檔為目的而額外地編寫大量的注釋，并且由于示例代碼被可執(zhí)行地保存在單獨(dú)的文件中而沒有包含在注釋中，所以在測試組件時示例代碼可以被重復(fù)利用，進(jìn)一步減輕了程序開發(fā)人員的負(fù)擔(dān)。
[0054]請參考圖1，為本發(fā)明提供的一種方法的流程圖，可以包括以下步驟:
[0055]步驟101:遍歷至少一個組件，查找使用者所需的組件；
[0056]步驟102:從預(yù)先創(chuàng)建的第一文件中獲取使用者所需的組件的使用說明，第一文件獨(dú)立于保存源碼的文件；
[0057]步驟103:從預(yù)先創(chuàng)建的第二文件中獲取使用者所需的組件的示例代碼，第二文件獨(dú)立于保存源碼的文件，并且第二文件中的示例代碼能夠運(yùn)行；
[0058]步驟104:由獲取的使用說明和示例代碼生成使用者所需的組件的說明文檔。
[0059]需要指出的是，上述方法的執(zhí)行順序不限于此。例如，步驟102和步驟103的執(zhí)行順序可以互換。
[0060]可以看出，由于組件的使用說明和示例代碼均以獨(dú)立于源碼的形式保存在各自的文件中，不再包含在源碼的注釋中，所以程序開發(fā)人員在編寫源碼的過程中無需對注釋花費(fèi)過多精力和時間，并且由于本發(fā)明的示例代碼可以運(yùn)行，所以通過本發(fā)明，示例代碼還可以用于測試組件，故程序開發(fā)人員無需準(zhǔn)備兩份代碼分別用于生成說明文檔和測試組件，從而極大地減輕了程序開發(fā)人員的負(fù)擔(dān)。
[0061]下面以一個更加詳細(xì)的實(shí)施例介紹本發(fā)明。
[0062]首先介紹該實(shí)施例所需的安裝環(huán)境。在本實(shí)施例中，基于Angular JS來開發(fā)組件，所以說明文檔的html頁面應(yīng)由Angular JS來驅(qū)動；由于通過調(diào)用grunt來生成說明文檔，所以需要安裝grunt ;因?yàn)間runt運(yùn)行在node js環(huán)境下，所以在安裝grunt之前還需要安裝node js?？梢岳斫獾?，所需的安裝環(huán)境不限于此。
[0063]為了更好地理解本實(shí)施例，還需要指出的是，本實(shí)施例提供的方法最終將以html頁面的形式向組件使用者展示說明文檔，可以理解的，向組件使用者展示說明文檔的方式不限于此。html頁面形式的說明文檔包括使用說明、示例代碼及其運(yùn)行結(jié)果。請參考圖2，為本實(shí)施例最終生成的html頁面形式的說明文檔的示意圖。
[0064]請參考圖3，為本實(shí)施例組件架構(gòu)示意圖。根據(jù)圖3，本實(shí)施例可以包括多個(例如三個)組件，其中，組件I可以包括三個部分:源碼、示例代碼和使用說明，源碼包括js源碼，可選地，源碼還可以包括html源碼和css源碼，示例代碼包括示例js代碼和示例html代碼。