譯者按： 代碼要有規范的注釋，遵從jsDoc規則來注釋可以生成有用的文檔。
為了保證可讀性，本文采用意譯而非直譯，並且對源代碼進行了大量修改。另外，本文版權歸原作者所有，翻譯僅用於學習。
今天，我來分享如何快速生成JavaScript代碼的文檔，並且使用Github pages發布。
我首先創建一個示例類JokeMachine，它存儲一個笑話列表，調用sayRandomJoke會隨機講一個笑話。
|
class HelloWorld {
constructor(){
this.firstName = '';
this.lastName = '';
}
setName(firstName, lastName){
this.firstName = firstName;
this.lastName = lastName;
}
getFullName(){
return this.firstName + ' ' + this.lastName;
}
sayHello(){
console.log('Hello, ' + this.getFullName());
}
}
|
添加代碼文檔
參照jsdoc指導規則，直接在代碼中編寫文檔。
|
/**
* HelloWorld類存儲一位客人的名字，並打招呼。
*/
class HelloWorld {
constructor(){
this.firstName = '';
this.lastName = '';
}
/**
* 設置客人的姓名
*
* @param {String} lastName 姓
* @param {String} firstName 名
*/
setName(lastName, firstName){
this.lastName = lastName;
this.firstName = firstName;
}
/**
* 獲取客人的全名
*
* @return {String} 客人的姓名
*/
getFullName(){
return this.lastName + ' ' + this.firstName;
}
/**
* 向客人打招呼
*
*/
sayHello(){
console.log('Hello, ' + this.getFullName());
}
}
|
使用jsDoc生成文檔
現在我們可以為JokeMachine類生成文檔。首先，在全局安裝jsDoc或則局部安裝。我個人喜歡全局安裝。
|
npm install -g jsdoc
|
如果想知道更多信息，可以參考jsDoc的Github頁面。
最后，使用如下命令生成文檔：
|
jsdoc Joke.js
|
你會發現一個名為out的新文件夾。打開文件夾中的index.html,可以看到生成好的文檔。
點擊右側導航欄的JokeMachine標簽，然后可以查看JokeMachine所有的方法說明。
是不是很酷？
你也許注意到了，沒有一個根頁面，因為jsDoc根據README.md文件來生成。
因此，我們添加一個。
|
touch README.md
|
並簡單介紹一下
|
# 使用jdDoc來生成文檔
## Hello World示例
這里是根頁面
|
我們再次生成文檔，注意第二個參數是README.md。
|
jsdoc Joke.js README.md
|
新生成的文檔根頁面如下：
使用Github pages托管
最簡單的方法就是創建一個Github repository, 然后使用免費的Github pages服務(譯者注：國內Coding也有相應的服務)。如果你還不知道如何創建repository，可以參考幫助文檔。
你需要將文件夾重命名為docs，然后去Github網站，到項目的設置(Settings > Github Pages)，選擇master branch/docs folder， 然后保存。
然后，會生成一個指向該文檔的鏈接：
點擊鏈接，就可以看到文檔啦。
版權聲明: 轉載時請注明作者Fundebug以及本文地址： https://blog.fundebug.com/2017/10/18/generate-docs-with-jsdoc/