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

文章目录

参考: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

相关推荐
轻语呢喃2 小时前
Cookie详解:从原理到实战,彻底搞懂用户身份识别机制
javascript·http·html
小宁爱Python4 小时前
FastAPI+Sqlite+HTML的登录注册与文件上传系统:完整实现指南
sqlite·html·fastapi
网络点点滴6 小时前
Vue如何处理数据、v-HTML的使用及总结
前端·vue.js·html
Rubin936 小时前
浏览器一帧做些什么?
html
G等你下课6 小时前
如何进行DOM操作?
javascript·html
然我7 小时前
打工人必看!Flex “驯服” 前端面试,让代码像整理工位一样顺
前端·面试·html
veminhe10 天前
HTML5 浏览器支持
前端·html·html5
訾博ZiBo10 天前
开源分享:我开发了一个智能文本提取浏览器插件,彻底解决复制粘贴的烦恼
前端·react.js·html
A5资源网10 天前
为WordPress 网站创建一个纯文本网站地图(Sitemap)
前端·数据仓库·html·php
伍哥的传说11 天前
Node.js爬虫 CheerioJS ‌轻量级解析、操作和渲染HTML及XML文档
爬虫·node.js·html