专注国内外云服务器
分享建站技术教程

JSDoc 注释规范

立即购买

阿里云服务器 ¥102元/年 云数据库37.5元/年 限时

个人、企业均可购买 | 更多配置0.8折特惠

吾上云WORDPRESS教程最新“JSDoc 注释规范”

什么是 JSDoc

JSDoc 是一个根据 JavaScript 文件中注释信息,生成 JavaScript 应用程序或模块的API文档的工具。你可以使用 JSDoc 标记如:命名空间方法方法参数等。从而使开发者能够轻易地阅读代码,掌握代码定义的类和其属性和方法,从而降低维护成本,和提高开发效率。

JSDoc 注释规则

JSDoc注释一般应该放置在方法或函数声明之前,它必须以/ **开始,以便由JSDoc解析器识别。其他任何以/*/***或者超过3个星号的注释,都将被JSDoc解析器忽略。如下所示:

/**
* 一段简单的 JSDoc 注释。
*/

JSDoc 的注释效果

假如我们有一段这样的代码,没有任何注释,看起来是不是有一定的成本。

function Book(title, author) {
    this.title=title;
    this.author=author;
}
Book.prototype={
    getTitle:function(){
        return this.title;
    },
    setPageNum:function(pageNum){
        this.pageNum=pageNum;
    }
};

如果使用了 JSDoc 注释该代码后,代码的可阅读性就大大的提高了。

/**
 * Book类,代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book(title, author) {
    this.title=title;
    this.author=author;
}
Book.prototype={
    /**
     * 获取书本的标题
     * @returns {string|*} 返回当前的书本名称
     */
    getTitle:function(){
        return this.title;
    },
    /**
     * 设置书本的页数
     * @param pageNum {number} 页数
     */
    setPageNum:function(pageNum){
        this.pageNum=pageNum;
    }
};

@constructor 构造函数声明注释

@constructor 明确一个函数是某个类的构造函数。

@param 参数注释

我们通常会使用 @param 来表示函数、类的方法的参数,@param 是JSDoc中最常用的注释标签。参数标签可表示一个参数的参数名参数类型参数描述的注释。如下所示:

/**
 * @param {String} wording 需要说的句子
 */
function say(wording) {
  console.log(wording);
}

@return 返回值注释

@return 表示一个函数的返回值,如果函数没有显示指定返回值可不写。如下所示:

/*
 * @return {Number} 返回值描述
 */

@example 示例注释

@example 通常用于表示示例代码,通常示例的代码会另起一行编写,如下所示:

/*
 * @example
 * multiply(3, 2); 
 */

其他常用注释

  • @overview 对当前代码文件的描述。
  • @copyright 代码的版权信息。
  • @author [] 代码的作者信息。
  • @version 当前代码的版本。

更多参考

如果想了解更多的 JSDoc 注释的内容,可参考下面的链接。

文章来源于互联网WORDPRESS教程:JSDoc 注释规范,
阿里云服务器89元起,点击购买
腾讯云服务器95元/年起 点击购买

相关推荐: 编辑WordPress的functions.php 文件有哪些注意事项呢?

吾上云WORDPRESS教程最新“编辑WordPress的functions.php 文件有哪些注意事项呢?”functions.php 文件中如何添加代码是很多新手朋友都会遇到的问题,大家都害怕添加错误导致网站不能访问了,那么编辑WordPress的func…

赞(0)
未经允许不得转载:吾上云 » JSDoc 注释规范
分享到: 更多 (0)
  • 阿里云
    基础型云服务器

    1核CPU

    2G内存

    40G硬盘

    1M带宽

    独立IP

    分布式存储

    适合企业官网、个人站长类网站

    ¥89/1年 原价¥903.40

  • 阿里云
    超值型云服务器

    2核CPU

    4G内存

    40G硬盘

    3M带宽

    独立IP

    分布式存储

    适合企业官网、行业门户类网站

    ¥899/3年 原价¥8281

  • 阿里云
    高性能云服务器

    2核CPU

    8G内存

    40G硬盘

    5M带宽

    独立IP

    分布式存储

    适合电商、数据库等企业级应用

    ¥1399/3年¥14765

  • 腾讯云
    基础型云服务器

    1核CPU

    2G内存

    50G硬盘

    1M带宽

    独立IP

    分布式存储

    适合企业官网、个人站长类网站

    ¥95/1年 原价¥834

  • 腾讯云
    超值型云服务器

    1核CPU

    2G内存

    50G硬盘

    1M带宽

    独立IP

    分布式存储

    适合企业官网、行业门户类网站

    ¥288/3年 原价¥2502

  • 腾讯云
    高性能云服务器

    4核CPU

    8G内存

    50G硬盘

    5M带宽

    独立IP

    分布式存储

    适合电商、数据库等企业级应用

    ¥2188/3年¥13986

  • 阿里云
    基础型云服务器

    1核CPU

    2G内存

    40G硬盘

    1M带宽

    独立IP

    分布式存储

    适合企业官网、个人站长类网站

    ¥89/1年 原价¥903.40

  • 阿里云
    超值型云服务器

    2核CPU

    4G内存

    40G硬盘

    3M带宽

    独立IP

    分布式存储

    适合企业官网、行业门户类网站

    ¥899/3年 原价¥8281

  • 阿里云
    高性能云服务器

    2核CPU

    8G内存

    40G硬盘

    5M带宽

    独立IP

    分布式存储

    适合电商、数据库等企业级应用

    ¥1399/3年¥14765

  • 腾讯云
    基础型云服务器

    1核CPU

    2G内存

    50G硬盘

    1M带宽

    独立IP

    分布式存储

    适合企业官网、个人站长类网站

    ¥95/1年 原价¥834

  • 腾讯云
    超值型云服务器

    1核CPU

    2G内存

    50G硬盘

    1M带宽

    独立IP

    分布式存储

    适合企业官网、行业门户类网站

    ¥288/3年 原价¥2502

  • 腾讯云
    高性能云服务器

    4核CPU

    8G内存

    50G硬盘

    5M带宽

    独立IP

    分布式存储

    适合电商、数据库等企业级应用

    ¥2188/3年¥13986

评论 抢沙发

评论前必须登录!

 

吾上云 专注服务器选购

购买云服务器联系我们