Vue-cli3.x中使用jsDoc

每個項目在負責交接的時候，都會遺留大部分的問題，而好的註釋和詳細的文檔是我們快速接手的必要前提，所以這裏記錄一下在vue腳手架3.x中集成Jsdoc的方式，首先使用shell命令安裝插件

在全局安裝jsdoc

npm install -g jsdoc

在項目中安裝jsdoc

npm install --save-dev jsdoc

解析js文件生成文檔命令

jsdoc yourJavaScriptFile.js
// yourJavaScriptFile.js是你需要解析的js文件，當然該文件要在shell命令的
當前根目錄文件夾下，如果不在，使用相對路徑指向js文件，例如jsdoc ./Doc/base.js

項目安裝完畢過後，vue-cli3.x的package.json中會有安裝的版本號,

jsDoc生成文檔是根據自己特定語法的，這裏推薦一箇中文文檔地址https://www.html.cn/doc/jsdoc/about-configuring-jsdoc.html

接下來我描述一下我的項目目錄和我解析文件的方式

 文件內容

使用jsdoc命令解析該js文件,我的shell窗口是在項目根目錄下打開的，所以使用相對路徑

jsdoc ./src/ApiDoc/base.js

默認在項目根目錄下生成out文件夾，解析後的文檔html可以直接在瀏覽器中運行起來，默認運行起來的頁面主頁頁腳會帶上日期，如果不帶上需要自行配置，這裏暫時不提，下面再講

如何自定義輸出解析文件的文件夾名稱以及導出路徑？

自定義解析導出文件夾命令,這裏提醒一下自定義的文件路徑需要存在，也就是說doc文檔存放的文件夾首先需要創建好

jsdoc -d yourpathfolder ./src/Doc/base.js
          文件夾路徑     解析的文件路徑

 

我創建的存放文件夾JsDoc

這裏可以看到該文件夾下面有ApiDoc文件夾以及一個conf.json文件，這裏講講我這樣建立的原因,因爲一個項目中我們需要解析成文檔說明的js文件肯定不止一個，所以存取解析文件的文件夾需要獨立起來，這裏的ApiDoc文件夾就是用來專門存放接口文檔js文件調取的，如果我們還有什麼自己封裝的函數集成js或者抽離出來的公共js文件的話，可以再重新創建一個文件夾用於解析後文件的存放,

conf.json文件的作用就是上面提到的主頁頁腳默認帶上日期的一些默認項配置，也就是用於自定義JsDoc解析文件的模板信息

配置好conf.json後，執行解析的shell命令如下

jsdoc     -d ./JsDoc/ApiDoc     ./src/ApiDoc/base.js -c     ./JsDoc/conf.json -r
        文件解析存儲路徑           解析文件的路徑信息            自定義解析模板的配置文件路徑

這裏貼上我的conf.json文件內容

{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "source": {
        "includePattern": ".+\\.js(doc)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false,
        "default":{
            "outputSourceFiles":false,
            "includeDate":false,
            "useLongnameInNav":true
        }
    }
}