在实际开发中,我们在定义一些类或组件时,经常要写一些注释。前端注释如下:
/**
* @property {String} 日程拥有者的ID
* @desc 用于加载日程信息时指定 拥有者
* ### 示例:'T001'
*/
ownerID: null,
/**
* @property {Array} 日程拥有者的ID 数组
* @desc 用于加载日程信息时指定 拥有者
* # 示例:['T001']
*/
ownerArr: [],
/**
* @property {String} 日程显示及添加类型
* @desc 用于加载日程信息时指定类型 以及 新建时固定类型
* @value `plan` 计划 `act` 活动
* ### 示例:'plan'
*/
type: null,
当鼠标悬浮在其上时,可以看到这些注释信息
可以看到有 @property @desc 等等标签 还有些是 ###
为什么会有这些?主要由于有一种参考规范
注释语法规范
1.jsDoc
整体js注释规范参照的是 jsDoc
像是参数注释说明可以用 @param
/**
* @func
* @desc 一个需要string类型参数的函数
* @param {string} a - 参数a
*/
function bar(a) {}
其他的具体规范可以参考 jsDoc 规范导航
2.markDown
在实际写一些描述时,用到的是markDown语法来标记
例如,想声明 示例时 可以用 ###
/**
* @property {String} 日程拥有者的ID
* @desc 用于加载日程信息时指定 拥有者
* ### 示例:'T001'
*/
### 就是markDown 里 用于声明标题信息的
具体MarkDown语法 可以参考 markDown语法大全简版
js注释
1.前端在VS Code开发的话,可以使用Document This 插件
2.在扩展里搜“Document”,然后安装,安装好后,重启VS Code,
3.然后将鼠标光标放置在需要添加注释说明的方法前(或上部),使用 Ctrl + Alt + D ,生成模板后填写必要信息
ps:快捷键 也可以自己去 Vs Code【快捷键】设置调整
服务端方法添加说明注释
有时我们经常会在一些服务端的方法里看到一些注释,像如下c#例子:
#region 重载公告的缓存
/// <summary>
/// 重载公告的缓存
/// </summary>
/// <param name="reload"></param>
public static void WriteNoticeMemory(bool reload)
{
}
#endregion
这些注释的作用啥?
#region + #endregion
仅是用来包裹方法体的,可以将一段很长的包裹起来,方便整体阅读
summary
用于外部调用方法时,显示提示,
当鼠标悬浮在方法名上 就会显示的提示
summary的添加方式:
在方法名前输入 /// 后点回车即可