代码规范-代码注释,及注释辅助工具

文章目录

参考:https://knightyun.github.io/2020/03/13/js-comment-format

代码规范-代码注释,及注释辅助工具

1.常见代码块注释提示标签

  1. @desc
  2. @file
  3. @author
  4. @param
  5. @copyright
  6. @version
  7. @returns
  8. @example

含义:

@desc

描述当前注释对象的详细信息

@file

描述当前文件的相关信息

@author

作者相关信息

@param

描述函数的参数信息

@copyright

描述文件的版权相关信息

@version

描述当前项目的版本号

@returns

描述函数的返回值的信息

@example

描述指定代码的使用示例

2.JSDoc

JSDoc 是一个针对 JavaScript 的 API 文档生成器,类似于 Java 中的 Javadoc 或者 PHP 中的 phpDocumentor;在源代码中添加指定格式的注释,JSDoc 工具便会自动扫描你的代码并生成一个 API 文档网站(在指定目录下生成相关的网页文件);

实例:

js 复制代码
/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}

工具的使用:

  • 首先安装它
bash 复制代码
npm install -g jsdoc
  • 假设在一个名为 doc.js 的文件中书写以下代码
javascript 复制代码
/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}
/**
 * Return the diff fo a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function diff(a, b) {
    return a - b;
}
  • 在当前目录执行以下命令
bash 复制代码
jsdoc doc.js
  • 在当前目录下生成一个名为 out 的目录:
bash 复制代码
├── doc.js
└── out
    ├── index.html
    ├── doc.js.html
    ├── global.html
    ├── fonts
    │   ├── OpenSans-BoldItalic-webfont.eot 
    │   ├── OpenSans-BoldItalic-webfont.svg 
    │   ├── OpenSans-BoldItalic-webfont.woff
    │   ├── OpenSans-Bold-webfont.eot       
    │   ├── OpenSans-Bold-webfont.svg       
    │   ├── OpenSans-Bold-webfont.woff      
    │   ├── OpenSans-Italic-webfont.eot     
    │   ├── OpenSans-Italic-webfont.svg     
    │   ├── OpenSans-Italic-webfont.woff    
    │   ├── OpenSans-LightItalic-webfont.eot
    │   ├── OpenSans-LightItalic-webfont.svg
    │   ├── OpenSans-LightItalic-webfont.woff
    │   ├── OpenSans-Light-webfont.eot
    │   ├── OpenSans-Light-webfont.svg
    │   ├── OpenSans-Light-webfont.woff
    │   ├── OpenSans-Regular-webfont.eot
    │   ├── OpenSans-Regular-webfont.svg
    │   └── OpenSans-Regular-webfont.woff
    ├── scripts
    │   ├── linenumber.js
    │   └── prettify
    │       ├── Apache-License-2.0.txt
    │       ├── lang-css.js
    │       └── prettify.js
    └── styles
        ├── jsdoc-default.css
        ├── prettify-jsdoc.css
        └── prettify-tomorrow.css

通过浏览器访问这个 out 目录中的相关网页,就会展示类似于下面的页面内容;

指定函数页:

3.注释格式

完整的格式介绍请参考官网(https://jsdoc.app/index.html),目前版本是 JSDoc 3

VS Code 提供了相关的插件下载,直接在插件中搜索 jsdoc

相关推荐
豆包MarsCode3 小时前
我用豆包MarsCode IDE 做了一个 CSS 权重小组件
开发语言·前端·javascript·css·ide·html
战族狼魂5 小时前
html+js实现图片的放大缩小等比缩放翻转,自动播放切换,顺逆时针旋转
javascript·css·html
Komorebi⁼5 小时前
Vue核心特性解析(内含实践项目:设置购物车)
前端·javascript·vue.js·html·html5
daopuyun5 小时前
LoadRunner小贴士|开发Web-HTTP/HTML协议HTML5相关视频应用测试脚本的方法
前端·http·html
前端Hardy15 小时前
纯HTML&CSS实现3D旋转地球
前端·javascript·css·3d·html
emmm45917 小时前
html兼容性问题处理
html
我爱李星璇17 小时前
HTML常用表格与标签
前端·html
猫爪笔记1 天前
前端:HTML (学习笔记)【2】
前端·笔记·学习·html
风尚云网1 天前
风尚云网前端学习:一个简易前端新手友好的HTML5页面布局与样式设计
前端·css·学习·html·html5·风尚云网
佚先森1 天前
2024ARM网络验证 支持一键云注入引流弹窗注册机 一键脱壳APP加固搭建程序源码及教程
java·html