安利一个文档生成工具-jsdoc

什么是jsdoc?

如果你还不知道jsdoc,那么我是不是可以这么理解:你JavaScript代码中的注释没有任何规范,或者你所做的都是些小项目,根本不需要对接。一个好的注释习惯可以帮助理清代码逻辑,统一的代码注释甚至可以利用工具来生成参考文档。jsdoc便是这么一个工具,它可以将你JavaScript代码中的注释自动转换为一个参考文档。

这样的好处,既可使用注释来梳理业务逻辑,又可以使用注释生成一个API参考文档,提供给需要对接的项目组翻阅,可谓一举两得。

如何使用?

首先肯定是安装咯。

npm i jsdoc -g

我这里全局安装,局部安装的自己研究吧。

然后就是写一个JavaScript文件

/**
 * @file    mysdk.js
 * @author  xiaohei
 * @date    2017/11/6
 * @description  sdk.js文件。
 */
 
/**
 * 我的测试类
 * @constructor
 */
function MySdk() {
   /**
    * 测试属性
    * @type {number}
    */
   this.a = 1;
   
   /**
    * 测试方法
    * @param p {string} 参数p
    * @return {number}
    */
   this.b = function (p) {
      return 2;
   }
}

然后,我们使用jsdoc的命令行编译一下,就能生成一个参考文档了。如下:

jsdoc mysdk.js -d docs/mysdk

它会在docs/mysdk目录下生成很多的html文件,如下:

image.png
最后我们直接双击index.html即可。

最终效果

image.png

右边是我们定义的一个MySdk类,左边是我们的文件。点击MySdk还可以查看类的各种属性和方法。

image.png

很好用吧?

总结

方便快捷,没人会比程序员自己更了解一个API的功能。写注释的时候就已经在写文档了,从现在起,将你的代码注释规范起来吧!

更多信息,请参看其官方文档,点击这里。如果英文看不太懂的,请参看中文地址,点击这里

最后是npm模块jsdoc的参考地址,点击这里。它有很多模板可以用,我这里只是默认模板,有兴趣的可以看看。



打赏作者

发表评论

电子邮件地址不会被公开。 必填项已用*标注