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

收藏

本帖最后由 DerrickJiao 于 2020-9-27 21:23 编辑

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

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

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

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

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

另外，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文件配置相关信息

{
"source": {
"include":["src"],
"includePattern": ".js[ DISCUZ_CODE_0 ]quot;,
"excludePattern": "(node_modules/|docs)"
},
"plugins": ["plugins/markdown"],
"templates": {
"cleverLinks":true,
"monospaceLinks":true
},
"opts":{
"recurse":true,
"destination": "./docs/",
"template":"custom-template",
"tutorials":"./tutorials",
"readme":"./readme.md"
}
}

复制代码

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

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

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

怎么样，学“废”了吗？

		自动登录	找回密码
密码			立即注册

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

0 个回复

SpreadJS 高级认证

讲师达人

GrapeCity

悬赏达人

SpreadJS 认证