JSDoc 是一個JavaScript的API文檔生成器. 他可以讓開發(fā)者在開發(fā)的過程中, 將編寫的注釋通過JSDoc工具生成一個api文檔, 媽媽再也不用擔(dān)心我不會寫接口文檔了.

這里是原作者GitHub項目的地址:鏈接

1.少廢話先看東西

先看一下效果圖吧:

/*** @file 這是一個jsDoc的測試demo* @author walker* @version 0.0.1*/

這是對整個js文件的描述

還有一些js文件中函數(shù)的效果圖:

看了效果圖,想必大概也了解這個工具究竟是用來做什么的,雖然界面沒有那沒漂亮,但整齊還是有的.

2.JSDoc的安裝及使用

node不用說, 肯定是必備的. 項目作者還說了:"JSDoc支持穩(wěn)定版本的Node.js 8.15.0及更高版本。您可以在全局或項目的node_modules文件夾中安裝JSDoc ".
1) 新建一個項目, 在項目目錄下初始化一下npm

npm init

2) 命令行裝 JSDoc

// 先在全局安裝 npm install -g jsdoc // 當(dāng)前項目安裝 npm install --save-dev jsdoc

3) 新建一個要被編譯的js文件
demo.js就是這個名字沒錯了

/*** @file 這是一個jsDoc的測試demo* @author walker* @version 0.0.1*//*** @description Book類, 代表一個書本* @param {string} title - 書本的標(biāo)題.* @param {string} author - 書本的作者.*/ function Book(title, author) {this.title = title;this.author = author; } Book.prototype = {/*** @description 獲取書本的標(biāo)題* @returns {string|*}*/getTitle: function () {return this.title;},/*** @description 設(shè)置書本的頁數(shù)* @param pageNum {number} 頁數(shù)*/setPageNum: function (pageNum) {this.pageNum = pageNum;} };/*** @description 這是一個有返回值得求和函數(shù)* @param {*} num1 加數(shù)* @param {*} num2 被加數(shù)* @returns {num|*} myTestVal 兩數(shù)之和 */ var myTest2 = function (num1, num2) {var myTestVal;myTestVal = num1 + num2;return myTestVal; } myTest2(2, 2)/*** @description num2是一個沒用的變量*/ var num2 = 2;// @description num是兩數(shù)之和 var num; /*** @description 這是一個沒有返回值求和的函數(shù)* @param {*} num1 加數(shù)* @param {*} num2 被加數(shù)*/ var myTest = function (num1, num2) {num = num1 + num2; } myTest(1, 2)var testVal; /*** @description 這是一個沒有參數(shù)的函數(shù)*/ function test() {console.log("123") }

4) 命令行編譯文件:

jsdoc demo.js

5) 編譯成功
編譯成功后就會看到目錄下多了一個out目錄, 點擊index.html從瀏覽器打開m, 就會看到上面的效果圖了

3.下面介紹一些常見的JSDoc注釋符

標(biāo)簽描述示例

@file	文件描述。也可寫作@overview或者@fileoverview	@file description
@author	指明作者	@author description
@version	指定類的版本	@version info
@class	指明類名，也寫作@constructor	@class class name or function name
@description	描述當(dāng)前函數(shù)或者類的作用，也可寫作@desc	@description functions
@param	說明一個方法的參數(shù)，通常需要用{}指明數(shù)據(jù)類型	@param {String} parameter name
@returns	說明返回值類型，用{}指明返回值數(shù)據(jù)類型	@returns {String} explanation
@type	指定函數(shù)的返回類型
@deprecated	指明一個過期的類或成員	@deprecated description
@see	指定一個到另一個主題的鏈接	@see anchor
@extends	指示一個類派生了另一個類。JSDoc通常自己就可以檢測出這種信息，不過，在某些情況下則必須使用這個標(biāo)
@exception	標(biāo)志一個類拋出的異常	@exception exception-name explanation
@throws	和 @exception標(biāo)簽一樣.	The @throws tag has the same meaning as the @exception tag.
{@link}	插入一個到另一個主題的鏈接	{@link name text}
@since	標(biāo)記當(dāng)引入一個特定的變化時	@since release
@final	指示一個值是常量值. 記住JavaScript無法真正保證一個值是常量	Constant value
@ignore	JSDoc忽略有這個標(biāo)記的函數(shù)

ps:單行注釋”//”不會被編譯.
如果只想對函數(shù)進行描述,”//@description Book類, 代表一個書本”, 這樣寫是不行的,必須使用/** */注釋

還有一些文檔,詳情請看鏈接
JSDoc3常用標(biāo)簽使用說明+示例: https://www.jianshu.com/p/c190dc9dd0d5
JSDoc在線手冊：http://www.dba.cn/book/jsdoc/
JSDoc3: https://github.com/jsdoc/jsdoc
JSDoc英文手冊：https://jsdoc.app/
JSDoc 注釋規(guī)范：https://www.cnblogs.com/Garven/articles/7161797.html

最后:其實這只是傳統(tǒng)項目的用法,在vue或者其他框架中.這樣直接用肯定是不行的, 肯定有專門的插件可以配套使用, 隨便搜了下,是有的,多多推薦.

總結(jié)

以上是生活随笔為你收集整理的JSDoc --JS API文档生成器的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。