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编码,然后重新生成帮助文档,这样就不会有编码问题。

 

posted on   烟火_  阅读(7331)  评论(1编辑  收藏  举报

编辑推荐:
· .NET Core内存结构体系(Windows环境)底层原理浅谈
· C# 深度学习:对抗生成网络(GAN)训练头像生成模型
· .NET 适配 HarmonyOS 进展
· .NET 进程 stackoverflow异常后,还可以接收 TCP 连接请求吗?
· SQL Server统计信息更新会被阻塞或引起会话阻塞吗?
阅读排行:
· 本地部署 DeepSeek:小白也能轻松搞定!
· 传国玉玺易主,ai.com竟然跳转到国产AI
· 自己如何在本地电脑从零搭建DeepSeek!手把手教学,快来看看! (建议收藏)
· 我们是如何解决abp身上的几个痛点
· 如何基于DeepSeek开展AI项目
< 2025年2月 >
26 27 28 29 30 31 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 1
2 3 4 5 6 7 8

导航

统计

点击右上角即可分享
微信分享提示