工具介绍 JSDoc——一个JavaScript API文档生成器

背景：众所周知，咱们SpreadJS之前的API是纯英文的，有的小伙伴可能看起来就比较头疼。于是我们推出了中文版的API，也是广受好评。（虽然新的中文API可能存在翻译上的纰漏，但是还是在不断地优化当中）

要知道，想要实现一个API文档的网站，不是一项小工程。JSDoc就为我们带来了极大的便利。下面就简单地介绍一下JSDoc以及如何快速上手JSDoc！

JSDoc是一个根据JavaScript文件中注释信息，生成JavaScript应用程序或库、模块的API文档的开源工具。 你可以使用他记录如：命名空间，类，方法，方法参数等。类似JavaDoc和PHPDoc。​

现在很多编辑器或IDE中还可以通过JSDoc直接或使用插件生成智能提示。从而使开发者很容易了解整个类和其中的属性和方法，并且快速知道如何使用，从而提高开发效率，降低维护成本。

这是JSDoc自带的模板，如果满足不了你的需求，还有另外7套现成的模板供你使用。如果还满足不了你的需求，完全可以根据自己需求去深度定制属于你自己的模板。值得注意的是，这是一个开源的项目。


另外，vscode对JSDoc有较好的支持，帮助我们更高效率去完成注释的编写，有了这些注释之后，就可以通过JSDoc去生产一个个html文件。做个简单的比喻，JSDoc就是一个工厂，而JSDoc的模板就是工厂里的工人。另外，这些你写的注释就是你“生产”html页面的原材料，将原材料送入工厂，通过模板去加工，出来的就是严格按照模板加工的html。

ok，关于JSDoc的介绍大概就是这么多，那么我们现在手把手教你快速上手JSDoc！
1、在空的文件夹下npm init –y  创建一个package.json
2、npm i –D  jsdoc  安装JSDoc以及对应module
3、创建jsdoc.config文件配置相关信息

1. {
   
2.     "source": {
   
3.         "include":["src"],
   
4.         "includePattern": ".js[        DISCUZ_CODE_0        ]quot;,
   
5.         "excludePattern": "(node_modules/|docs)"
   
6.     },
   
7. 
   
8.     "plugins": ["plugins/markdown"],
   
9.     "templates": {
   
10.        "cleverLinks":true,
    
11.        "monospaceLinks":true
    
12.     },
    
13.     "opts":{
    
14.         "recurse":true,
    
15.         "destination": "./docs/",
    
16.         "template":"custom-template",
    
17.         "tutorials":"./tutorials",
    
18.         "readme":"./readme.md"
    
19.         
    
20.     }
    
21. }

复制代码

4、创建一个Src文件夹，放一个空的js文件
5、终端运行jsdoc –c jsdoc.json

运行完成后，会根据上面的配置生成一个docs，你写的注释会通过JSDoc生成的HTML


添加定制的模板也比较简单，只需在根目录下添加文件夹放置模板，然后在jsdoc.config配置好对应的路径即可。这样，JSDoc就会按照你定制的模板创建API的HTML。
另附JSDoc的github链接
https://github.com/jsdoc/jsdoc

怎么样，学“废”了吗？