Javascript注释规范

Javascript注释规范Javascript注释规范

大家好,又见面了,我是你们的朋友全栈君。如果您正在找激活码,请点击查看最新教程,关注关注公众号 “全栈程序员社区” 获取激活教程,可能之前旧版本教程已经失效.最新Idea2022.1教程亲测有效,一键激活。

Jetbrains全家桶1年46,售后保障稳定

最近查看代码,看其他人的代码确实很让人头疼,由于没有任何注释规范,导致代码里很少有注释,或者注释写的很简练,今天对于注释规范进行总结。
js注释规范基于jsdoc,写出的代码注释能够成功生成注释文档。
由于jsdoc的规范太多,为了项目的可用性,对jsdoc的某些属性进行提取形成文档,供开发人员使用。

方法注释

基本方法块注释

如果描述不能描述清楚,添加例子来描述。

/** * @method * @param {Type} data 目标对象 * @returns {Type} 运营商名称 * @desc 根据目标对象获取运营商 */
function matchedNumber(data){
    return '返回对象'
}

Jetbrains全家桶1年46,售后保障稳定

基本方法块注释,注释过长

/** * @method * @param {Type} data 目标对象<br/> * 例: * { * target:手机号 * } * @returns {Type} 运营商名称 * @desc 根据目标对象获取运营商 */
function matchedNumber(data){
    return '返回对象'
}

如果需要折行则在文本中使用<br/>标签

基本方法块注释,参数可选

/** * @method * @param {Type} [data] 目标对象 * 例: * { * target:手机号 * } * @returns {Type} 运营商名称 * @desc 根据目标对象获取运营商 */
function matchedNumber(data){
    return '返回对象'
}

基本方法块注释,带默认值

/** * @method * @param {Type} data={} 目标对象 * 例: * { * target:手机号 * } * @returns {Type} 运营商名称 * @desc 根据目标对象获取运营商 */
function matchedNumber(data){
    return '返回对象'
}

方法块注释特殊参数

如果描述不能描述清楚,添加例子来描述。
如果方法中有异常处理,标记异常处理注释

/** * @method * @param {Type} data 目标对象 * @returns {Type} 运营商名称 * @desc 根据目标对象获取运营商 * @throws {string} 抛出'Error'异常 * @example * add(1, 2); // 返回3 */
function matchedNumber(data){
    return '返回对象'
}

如果有返回值增加@returns 如果没有省略此属性
参数和返回值类型Type:string、boolean、number、object、array、function

文件注释

在文件头部增加文件注释

/** * @file LBS控制器 * @author limingle * @copyright Synway SFE * @createDate 2017-10-16 09:40:11 */

变量注释

将关键的变量进行特殊注释,生成到文档中

/** * @var {object} * @desc 变量定义 * @property {string} a 属性a * @property {string} b 属性b */
var foo = {
    a: 'a',
    b: 'b'
}

常量注释

将关键常量进行特殊注释,生成到文档中,如果有默认值增加@default属性

/** * @constant {string} * @default #000 * @desc 常量定义 */
const COLOR_WHITE = '#fff';

枚举注释

用于url列表或者颜色枚举值,一般用于配置文件中

/** * @enum {number} * @desc cgi常见的返回码 */
var RETCODE = {
    /** * @desc 未登录 */
    NOT_LOGIN: 100000,
    /** * @desc 参数错误 */
    PARAM_ERROR: 100001,
    /** * @type {string} * @desc 未知错误 */
    UNKOWN_ERROR: 'unkown'
}

类的注释

默认情况先一个function就是一个类
ES6中使用Class来表示一个类
我们项目中使用class.js来实现类,在我们项目中使用类注释时需要在@class后边增加类名,不要jsdoc无法自动识别类名

/** * @class * @classdesc 这是对myClass类的描述 * @desc 这是对myClass类的构造函数的描述 */
function myClass() {
    ...
}

或者

/** * @class LBSControllerCom * @classdesc LBS控制类 * @desc 初始化ws */
var LBSControllerCom = Com.extends({})

类的属性

类的属性和变量都会生成到jsdoc文档的Member模块中,在类中使用属性标识

var LBSControllerCom = Com.extends({
    /** * @member {string} * @desc 这样标识类的属性 */
    foo1 : 'a',
    init: function() {}
})

参考链接:
JSDoc Guide

版权声明:本文内容由互联网用户自发贡献,该文观点仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 举报,一经查实,本站将立刻删除。

发布者:全栈程序员-用户IM,转载请注明出处:https://javaforall.cn/215562.html原文链接:https://javaforall.cn

【正版授权,激活自己账号】: Jetbrains全家桶Ide使用,1年售后保障,每天仅需1毛

【官方授权 正版激活】: 官方授权 正版激活 支持Jetbrains家族下所有IDE 使用个人JB账号...

(0)


相关推荐

  • HDU-1387-Team Queue

    HDU-1387-Team Queue

  • 笔记内容

    笔记内容

  • 20210225-1 Python错误与异常「建议收藏」

    20210225-1 Python错误与异常「建议收藏」一、什么是异常Python错误与异常什么是异常>异常是一个事件,该事件会在程序执行过程中发生,影响程序的正常执行。一般情况下,在Python无法正常处理程序时就会发生异常。异常是Pyth

  • Debian6安装fcitx4

    Debian6安装fcitx4http://ftp.tw.debian.org/debian/pool/main/f/fcitx/下载fcitx-data_4.0.1-6_i386.debhttp://ftp.tw.debian.org/debian/pool/main/f/fcitx下载fcitx_4.0.1-6_i386.debdpkg-ifcitx-data_4.0.1-6_i386.debfcitx_4.0.1-6_i386.deb但是fcitx-sunpinyin都没有进入Debian可以从ubuntu实验区下载http

    2022年10月19日
  • pycharm 换行_pycharm自动换行快捷键

    pycharm 换行_pycharm自动换行快捷键python脚本有时一行代码写的非常长,一个屏幕塞不下,左右拉动滚动条视觉不友好。第一种方法:python里有换行标识”\”,如jfdb=spark.read.format(“jdbc”).option(“driver”,mysql_driver).option(“url”,mysql_url).option(“dbtable”,”xxxxxxxxxxxxxxxxxxxxxxxx”).option(“user”,mysql_acount).option(“password”,mysql_pa

  • java多线程–同步锁、

    java多线程–同步锁、同步代码块:语法:synchronized(同步锁){     需要同步操作的代码}—————————————————同步锁:为了保证每个线程都能正常执行原子操作,Java引入了线程同步机制.同步监听对象/同步锁/同步监听器/互斥锁:对象的同步锁只是一个概念,可以想象为在对象上标记了一个锁….

发表回复

您的电子邮箱地址不会被公开。

关注全栈程序员社区公众号