使用JSDoc自動生成代碼文檔

譯者按： 代碼要有規範的註釋，聽從jsDoc規則來註釋能夠生成有用的文檔。

• 原文: Generate docs and host it with JSDoc and GitHub Pages
• 譯者: Fundebug

爲了保證可讀性，本文采用意譯而非直譯，而且對源代碼進行了大量修改。另外，本文版權歸原做者全部，翻譯僅用於學習。

今天，我來分享如何快速生成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/