JSDoc 3 生成javascript API文档
一、javascript注释规范
我们在编写javascript文件的时候,一般会添加一些注释。例如一些文件、类、方法和属性都应该用合适的标记和类型进行注释。这里不但方便我们的阅读,也能养成一个好的习惯。更大的好处是,我们可以根据这些注释生成帮助文档。如下就是一个比较规范的javascript注释例子。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 | /** * MyClass类 * @class MyClass * @constructor */ function MyClass() { /** * a属性 * @property a * @type int **/ var a = 0; /** 获得A的值 @memberof MyClass @method getA @param returnType {int} 要设置的值 @example ele.setReturnType('0000'); **/ function setA(a) { this .a = a; } /** 设置A的值 @memberof MyClass @method getA @param returnType {int} 要设置的值 @example ele.setReturnType('0000'); **/ function getA() { return a; } } |
二、JSDoc 3
JSDoc 3是一个生成为Javascript生成API文档的工具。下载地址为:https://github.com/jsdoc3/jsdoc 。使用JSDoc 3 我们需要有Node.js环境。Node.js安装好之后,我们可以通过如下命令,可以按照最好的alpha版本:
1 | npm install jsdoc@ "<=3.3.0" |
在cmd输入该命令,回车。当显示如下结果的时候,说明JSDoc 3已经安装完成
不过此时JSDoc 3并没被添加到系统环境下。此时我们可以在cmd中进入C:\Users\user\node_modules\.bin该目录下,输入jsdoc -v,会显示安装的版本。我们将要生成文档的js文件拷贝到这个文件夹下,在cmd里面输入命令jsdoc test.js,目录下会生成out文件目录,该目录里面就是生成的API 文档。
文件上面的代码保存到test.js中,生成的API文档如下图所示
三、JSDoc 3相关配置了解
1、我们使用JSDoc生成javascriptAPI文档,必须要使用规范的注释。该注释可以参考 http://usejsdoc.org/.
2、为多个文件生成帮助文档
此时我们可以配置C:\Users\user\node_modules\jsdoc目录下的conf.json.EXAMPLE文件。为这个文件source里面添加一行如下图所示:
将要生成API文档的JS文件名称配置进入,然后将这写配置了的JS文件拷贝到C:\Users\user\node_modules\.bin这个文件夹里面。在cmd里面运行jsdoc,即可生成API文档。
注意:可能我们生成的API文档会有乱码,因为JSDoc 3生成的API文档默认是使用utf8编码格式生成文档。当我们的js文件内容不是使用utf8的时候,就会产生乱码。此时我们将JS文件都改成utf8编码,然后重新生成帮助文档,这样就不会有编码问题。
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· .NET Core内存结构体系(Windows环境)底层原理浅谈
· C# 深度学习:对抗生成网络(GAN)训练头像生成模型
· .NET 适配 HarmonyOS 进展
· .NET 进程 stackoverflow异常后,还可以接收 TCP 连接请求吗?
· SQL Server统计信息更新会被阻塞或引起会话阻塞吗?
· 本地部署 DeepSeek:小白也能轻松搞定!
· 传国玉玺易主,ai.com竟然跳转到国产AI
· 自己如何在本地电脑从零搭建DeepSeek!手把手教学,快来看看! (建议收藏)
· 我们是如何解决abp身上的几个痛点
· 如何基于DeepSeek开展AI项目