webstorm中生成jsdoc注释文档的方法

81次阅读

共计 1409 个字符,预计需要花费 4 分钟才能阅读完成。

webstorm 中生成 jsdoc 注释文档的方法

生成如下下图的文档格式

使用到的文档

  1. jsdoc 非常简单易懂的使用方法

)

  1. 官方文档,详细看 Block Tags,不知道有没有科学上网限制
  2. intellij 的自定义模板方法,因为同为 idea 使用方式极为类似

步骤

  • 完成 jsdoc 的安装并且检验是否安装成功

首先打开第一个文档,使用命令行安装
npm install -g jsdoc 或者局部安装npm install jsdoc
安装完成之后复制文档 jsdoc 非常简单易懂的使用方法 中的这段代码到你的 js 中

/**
 * 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 + 你的文件路径
成功之后在目录中会生成一个 out 的文件夹

在浏览器中打开 index.html 就可以看到这样的界面

到这里说明 jsdoc 安装完成。

  • 熟悉一下官方文档

现在可以大致看看官方文档中注释 Block Tags 有哪些,可以先试试

  • 结合 webstorm 食用口感更佳

我并不想在在每个 js 中手动写一长串的注释。。。(估计没人愿意吧)
这个地方就要使用到 webstorm 的自定义模板
打开我们最后一个文档 intellij 的自定义模板方法
打开 webstorm
Settings–>Editor–>Live Templates

先点击 javascript 后点击 +,然后添加完之后就出现我定义的method* 的模板
关键是添加这个模板的过程:

这个内容有一些技巧在其中

/**
 * @file: $file_name$
 * @method $functionName$
 * @param {type} argName - description 
 * @param {type} argName - description 
 * @param {type} argName - description 
 * @return {type} argName - description
 * @description: 
 * @author: $USER$
 * @date: $DATE$
 */

点击右边的按钮之后弹出

全部设置好之后再看看这个地方是不是忘了

  • 试验一下效果,发现还差一点

我在某个 js 文件中输入 method* 然后 tab 就输出我的模板

发现 method 的 $functionName$并没有出现,但是 file 的 $file_name$ 出现了, 试了下要在函数的内部使用才能生效

  • 继续优化

每次在终端输命令好烦。。于是写进 npm 的 script 里面

之后每次写完就 npm run doc
说明一下添加 README.md 是在第一文档中有写,就不赘述了
现在就试一下吧

自己也在摸索中,有很多不足请见谅

正文完
 0