玩转微服务-技术篇-JSDOC教程

一. 简介

JSDoc 3 是一个用于 JavaScript 的API文档生成器，类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中。JSDoc 工具将扫描您的源代码并为您生成一个 HTML 文档网站。

JSDoc 是一种用于 JavaScript 代码文档注释的标记语言和工具。它不仅仅是一种文档编写方式，更是一种代码规范和团队协作工具。通过使用 JSDoc 注释，开发人员可以将关于函数、类、方法、参数、返回值等方面的信息嵌入到代码中，从而帮助其他开发人员更轻松地理解和使用代码。

文档地址：中文文档地址

英文地址：英文文档地址

二. 文档注释的意义

编写JavaScript的文档注释有助于提高代码的可读性、生成易于阅读的API文档、明确接口规范、辅助调试和维护工作，以及促进团队合作和知识共享。这是为了更好地组织和记录代码，并使其更易于理解和使用的最佳实践之一。

  • 提供代码的可读性：文档注释可以帮助其他开发人员更好地理解你的代码。通过提供清晰的注释，可以解释代码的目的、使用方法和重要细节，使代码更易于阅读和维护。

  • 自动生成文档：许多开发工具和框架可以根据代码中的文档注释来自动生成文档。例如，JSDoc 是一个常用的JavaScript文档生成工具，它可以解析文档注释并生成API文档。这样其他开发人员就可以轻松地查看代码的接口和用法。

  • 提供接口定义和规范：通过文档注释，可以明确说明函数、类、方法和参数的用途、类型和预期行为。这不仅帮助其他开发人员正确使用你的代码，还可以在团队协作中提供一致性和规范。

  • 辅助代码调试和维护：当你在调试和维护代码时，文档注释可以提供有关代码功能和实现细节的重要信息。这对于理解复杂的功能和排查问题非常有帮助，尤其是当你需要处理他人编写的代码或长时间未接触的代码时。

  • 促进团队合作和知识共享：文档注释可以为开发团队提供一个共享的知识库，使所有人都能理解代码的功能和实现细节。这有助于提高团队成员之间的沟通和协作，并促进代码质量和一致性。

三. 命令行参数

JSDoc 支持大量的命令行选项，其中许多选项有长和短两种形式。或者，JSDoc 命令行选项可以在配置文件中指定。命令行选项：

选项描述
-a <value>, --access <value>只显示特定 access 方法属性的标识符： private, protected, public, or undefined, 或者 all（表示所有的访问级别）。默认情况下，显示除 private 标识符以外的所有标识符。
-c <value>, --configure <value>JSDoc 配置文件的路径。默认为安装 JSDoc 目录下的 conf.json 或 conf.json.EXAMPLE。
-d <value>, --destination <value>输出生成文档的文件夹路径。JSDoc 内置的 Haruki 模板，使用 console 将数据转储到控制台。默认为 ./out。
--debug打印日志信息，可以帮助调试 JSDoc 本身的问题。
-e <value>, --encoding <value>当 JSDoc 阅读源代码时假定使用这个编码，默认为 utf8。
-h, --help显示 JSDoc 的命令行选项的信息，然后退出。
--match <value>只运行测试，其名称中包含 value。
--nocolor当运行测试时，在控制台输出信息不要使用的颜色。在 Windows 中，这个选项是默认启用的。
-p, --private将标记有@private 标签的标识符也生成到文档中。默认情况下，不包括私有标识符。
-P, --package包含项目名称，版本，和其他细节的 package.json 文件。默认为在源路径中找到的第一个 package.json 文件。
--pedantic将错误视为致命错误，将警告视为错误。默认为 false。
-q <value>, --query <value>一个查询字符串用来解析和存储到全局变量 env.opts.query 中。示例：foo=bar&baz=true。
-r, --recurse扫描源文件和导览时递归到子目录。
-R, --readme用来包含到生成文档的 README.md 文件。默认为在源路径中找到的第一 README.md 文件。
-t <value>, --template <value>用于生成输出文档的模板的路径。默认为 templates/default，JSDoc 内置的默认模板。
-T, --test运行 JSDoc 的测试套件，并把结果打印到控制台。
-u <value>, --tutorials <value>导览路径，JSDoc 要搜索的目录。如果省略，将不生成导览页。查看导览说明，以了解更多信息。
-v, --version显示 JSDoc 的版本号，然后退出。
--verbose日志的详细信息到控制台 JSDoc 运行。默认为 false。
-X, --explain以 JSON 格式转储所有的 doclet 到控制台，然后退出。

详细参见：https://jsdoc.bootcss.com/about-commandline.html

四. 配置说明

1. 配置文件的类型

自定义 JSDoc 的行为，可以使用以下格式之一向 JSDoc 提供配置文件：

  • 一个JSON文件。在JSDoc 3.3.0及更高版本中，此文件可能包含注释。
  • 导出单个配置对象的 CommonJS 模块。JSDoc 3.5.0及更高版本支持这种格式。

要使用配置文件运行 JSDoc，请使用 -c 命令行选项（例如，jsdoc -c /path/To/conf.json 或 jsdoc -c /path/To/conf.js）。

2. 默认配置说明

默认配置内容

{"plugins": [],"recurseDepth": 10,"source": {"include": [ /* array of paths to files to generate documentation for */ ],"exclude": [ /* array of paths to exclude */ ],"includePattern": ".+\\.js(doc|x)?$","excludePattern": "(^|\\/|\\\\)_"},"sourceType": "module","tags": {"allowUnknownTags": true,"dictionaries": ["jsdoc", "closure"]},"templates": {"cleverLinks": false,"monospaceLinks": false},"opts": {"template": "templates/default",  // same as -t templates/default"encoding": "utf8",               // same as -e utf8"destination": "./out/",          // same as -d ./out/"recurse": true,                  // same as -r"tutorials": "path/to/tutorials", // same as -u path/to/tutorials}
}
  • 无插件加载（plugins）;
  • 如果使用 -r 命令行标志启用递归，JSDoc 将搜索 10 层深的文件（recurseDepth）；
  • 只有以 .js、.jsdoc 和 .jsx 结尾的文件将会被处理（source.includePattern）；
  • 任何文件以下划线开始或开始下划线的目录都将被忽略（source.excludePattern）；
    • source.include：可选的路径数组，JSDoc应该为它们生成文档。JSDoc 将会结合命令行上的路径和这些文件名，以形成文件组，并且扫描。如果路径是一个目录，可以使用 -r 选项来递归。
    • source.exclude：可选的路径数组，JSDoc 应该忽略的路径。在 JSDoc3.3.0 或更高版本，该数组可包括 source.include 路径中的子目录。
    • source.includePattern：一个可选的字符串，解释为一个正则表达式。如果存在，所有文件必须匹配这个正则表达式，以通过 JSDoc 进行扫描。默认情况下此选项设置为.+.js(doc)?$，这意味着只有以 .js、.jsdoc 和 .jsx 结尾的文件将被扫描。
    • source.excludePattern：一个可选的字符串，解释为一个正则表达式。如果存在的话，任何匹配这个正则表达式的文件将被忽略。默认设置是以下划线开头的文件（或以下划线开头的目录下的所有文件）将被忽略。
  • JSDoc 支持使用 ES2015 modules（sourceType）；
  • JSDoc 允许您使用无法识别的标签（tags.allowUnknownTags）,该属性影响 JSDoc 如何处理无法识别的标签。如果将此选项设置为 false，JSDoc发现它不能识别（例如,@foo），JSDoc 将记录一个警告。默认情况下，此选项设置为 true。；
  • 标准 JSDoc 标签和 closure 标签被启用（tags.dictionaries）；
    • 属性控制 JSDoc 识别哪些标签，以及 JSDoc 如何解析它识别标签。在 JSDoc3.3.0 或更高版本中，有两个内置的标签词典：
      • jsdoc: 核心JSDoc标签
      • closure: Closure Compiler 标签
  • @link标签呈现在纯文本（templates.cleverLinks，templates.monospaceLinks）。
  • opt: 可以将 JSDoc 的许多命令行选项放入配置文件中，而不是在命令行中指定它们。为此，将相关选项的长名称添加到配置文件的 opts 部分，并将值设置为该选项的值。

五. 标签

JSDoc支持两种不同类型的标签：

  • 块标签(Block), 这是在一个JSDoc注释的最高级别。
  • 内联标签(inline), 块标签文本中的标签或说明。

块标签通常会提供有关您的代码的详细信息，如一个函数接受的参数。内联标签通常链接到文件的其他部分，类似于HTML中的锚标记（<a>）。

块标签总是以 at 符号（@）开头。除了 JSDoc 注释中最后一个块标记，每个块标签后面必须跟一个换行符。

内联标签也以 at 符号（@）开。然而，内联标签及其文本必须用花括号（{ and }）括起来。 { 表示行内联标签的开始，而 } 表示内联标签的结束。如果你的标签文本中包含右花括号（}），则必须用反斜线（ \ ）进行转义。在内联标签后,你并不需要使用一个换行符。

1. 块级标签

块级标签使用说明

2. 内联标签

内联标签使用说明

六. 使用

1. 安装：

npm install -g jsdoc

2. 生成文档

jsdoc -r src -d doc

-r表示源目录，-d表示生成的目标目录，或者使用配置文件生成：

jsdoc -c /path/to/conf.json

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.mzph.cn/news/175888.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

【Leetcode】907. 子数组的最小值之和

【Leetcode】907. 子数组的最小值之和

给定一个整数数组 arr&#xff0c;找到 min(b) 的总和&#xff0c;其中 b 的范围为 arr 的每个&#xff08;连续&#xff09;子数组。 由于答案可能很大&#xff0c;因此 返回答案模 10^9 7 。 示例 1&#xff1a; 输入&#xff1a;arr [3,1,2,4] 输出&#xff1a;17 解释&…
阅读更多...
类 —— 封装、四类特殊成员函数、this指针、匿名对象、深浅拷贝问题

类 —— 封装、四类特殊成员函数、this指针、匿名对象、深浅拷贝问题

类 将同一类对象的所有属性都封装起来。 类中最基础的内容包括两部分&#xff0c;一个是属性、一个是行为。 ● 属性&#xff1a;表示一些特征项的数值&#xff0c;比如说&#xff1a;身高、体重、性别、肤色。这些属性都是名词。属性一般都以名词存在。属性的数值&#xff0c…
阅读更多...
Kubernetes之kubeadm集群优化篇—harbor添加更新SSL证书

Kubernetes之kubeadm集群优化篇—harbor添加更新SSL证书

docker 从docker 仓库中推送或获取镜像都是默认走https协议的。需要配置ssl证书&#xff0c;否则将无法方面&#xff0c;为了解决这以问题&#xff0c;我们有2个方案&#xff1a; 修改docker配置文件&#xff0c;关闭证书 “insecure-registries”。关闭证书校验 配置ssl证书&a…
阅读更多...
前端实现留言板

前端实现留言板

留言板的主要使用场景是为用户提供一个在网站或应用上留言的平台&#xff0c;这样他们可以分享自己的想法、意见或建议。这些留言可以帮助开发者收集用户反馈&#xff0c;从而改进产品或服务。 使用HTML、CSS和JavaScript实现的留言板&#xff1a;这种方法的优点是简单易实现&a…
阅读更多...
算法基础之食物链

算法基础之食物链

食物链 核心思想&#xff1a;带权并查集 用距根节点和距离表示与根节点的关系 求距离 #include<iostream>using namespace std;const int N50010;int n,m;int p[N],d[N];//找到祖宗节点(路径压缩) 并求出对应距离int find(int x){if(p[x]!x){int up[x]; //保存旧父节点…
阅读更多...
如何使用 Java 在Excel中创建下拉列表

如何使用 Java 在Excel中创建下拉列表

下拉列表&#xff08;下拉框&#xff09;可以确保用户仅从预先给定的选项中进行选择&#xff0c;这样不仅能减少数据输入错误&#xff0c;还能节省时间提高效率。在MS Excel中&#xff0c;我们可以通过 “数据验证” 提供的选项来创建下拉列表&#xff0c;但如果要在Java程序中…
阅读更多...
mysql账户密码获取

mysql账户密码获取

数据库安装目录 MySQL\data\mysql 里面的user.MYD文件&#xff0c;需要编译查看 数据库里的user表 库下面的user表拿到后&#xff0c;直接解密密码即可 网站配置文件 conn、config、data、sql、common 、inc这些文件 比如pikachu\inc目录下的config.inc.php文件的内容会显示…
阅读更多...
uniapp的vue3的模版的setup函数内使用uniapp内置方法

uniapp的vue3的模版的setup函数内使用uniapp内置方法

vue2使用方式直接在method同级使用就行,但是在vue3的setup函数内直接使用会报错,本人找了好久,发现vue3需要导入uniapp模块才能使用,具体如下 使用uniapp上拉加载更多方法 <script>import {onReachBottom} from dcloudio/uni-apponReachBottom(() > {console.log(&qu…
阅读更多...
速通CSAPP（一）计算机系统漫游入门

速通CSAPP（一）计算机系统漫游入门

CSAPP学习 前言 一门经典的计组课程&#xff0c;我却到了大四才学。 anyway&#xff0c;何时都不会晚。 博主参考的教程&#xff1a;本电子书信息 - 深入理解计算机系统&#xff08;CSAPP&#xff09; (gitbook.io)&#xff0c;非常感谢作者的整理。 诚然去看英文版可以学…
阅读更多...
【开源】基于Vue和SpringBoot的木马文件检测系统

【开源】基于Vue和SpringBoot的木马文件检测系统

项目编号&#xff1a; S 041 &#xff0c;文末获取源码。 \color{red}{项目编号&#xff1a;S041&#xff0c;文末获取源码。} 项目编号&#xff1a;S041&#xff0c;文末获取源码。 目录 一、摘要1.1 项目介绍1.2 项目录屏 二、功能模块2.1 数据中心模块2.2 木马分类模块2.3 木…
阅读更多...
软著项目推荐 深度学习中文汉字识别

软著项目推荐 深度学习中文汉字识别

文章目录 0 前言1 数据集合2 网络构建3 模型训练4 模型性能评估5 文字预测6 最后 0 前言 &#x1f525; 优质竞赛项目系列&#xff0c;今天要分享的是 &#x1f6a9; 深度学习中文汉字识别 该项目较为新颖&#xff0c;适合作为竞赛课题方向&#xff0c;学长非常推荐&#xf…
阅读更多...
【Vue】Linux 运行 npm run serve 报错 vue-cli-service: Permission denied

【Vue】Linux 运行 npm run serve 报错 vue-cli-service: Permission denied

问题描述 在Linux系统上运行npm run serve命令时&#xff0c;控制台报错&#xff1a; sudo npm run serve project50.1.0 serve vue-cli-service serve sh: 1: vue-cli-service: Permission denied错误截图如下&#xff1a; 原因分析 该错误是由于vue-cli-service文件权限不…
阅读更多...
flutter开发实战-为ListView去除Android滑动波纹

flutter开发实战-为ListView去除Android滑动波纹

flutter开发实战-为ListView去除Android滑动波纹 在之前的flutter聊天界面上&#xff0c;由于使用ScrollBehavior时候&#xff0c;当时忘记试试了&#xff0c;今天再试代码发现不对。这里重新记录一下为ListView去除Android滑动波纹的方式。 一、ScrollBehavior ScrollBehav…
阅读更多...
线性转换函数S_RTR(SCL和ST代码)

线性转换函数S_RTR(SCL和ST代码)

模拟量转换函数S_ITR详细公式和算法源代码请查看下面文章链接： PLC模拟量输入 模拟量转换FC S_ITR_博途模拟量转换程序_RXXW_Dor的博客-CSDN博客文章浏览阅读5.4k次，点赞4次，收藏7次。模拟量采集、工业现场应用特别广泛、大部分传感器的测量值和输出信号都是线型关系，所以…
阅读更多...
Rocky Linux 9.3 为 PowerPC 64 位带回云和容器镜像

Rocky Linux 9.3 为 PowerPC 64 位带回云和容器镜像

RHEL 克隆版 Rocky Linux 9.3 今天发布了&#xff0c;作为红帽企业 Linux 发行版 CentOS Stream 和 Red Hat Enterprise Linux 的免费替代版本&#xff0c;现在可供下载。 Rocky Linux 9.3 是在 Rocky Linux 9.2 发布 6 个月之后发布的&#xff0c;它带回了 PowerPC 64 位 Lit…
阅读更多...
4D雷达目标检测跟踪算法设计

4D雷达目标检测跟踪算法设计

1.算法流程 4D雷达点云跟踪处理沿用3D毫米波雷达的处理流程&#xff0c;如下图&#xff1a; 从接收到点云开始&#xff0c;先对点云做标定、坐标转换、噪点剔除、动静分离&#xff0c;再分别对动态目标和静态目标做聚类&#xff0c;然后根据聚类结果做目标的特征分析和检测等&a…
阅读更多...
数据源网站汇总（持续更新）

数据源网站汇总（持续更新）

数据源网站汇总 1、背景2、数据源网站汇总 1、背景 大数据是信息化发展到一定阶段的产物。随着信息技术和人类生产生活深度融合&#xff0c;互联网快速普及&#xff0c;全球数据呈现爆发增长、海量集聚的特点&#xff0c;对经济发展、社会进步、国家治理、人民生活都产生了重大…
阅读更多...
leetcode42接雨水问题

leetcode42接雨水问题

接雨水 题目描述 题目分析 核心思想&#xff1a; 代码 java版本&#xff1a; package com.pxx.leetcode.trapRainWaterDoublePoniter;public class Solution1 {public int trap(int[] height) {if (height.length 0) {return 0;}int n height.length;int left 0;int righ…
阅读更多...
LabVIEWL实现鸟巢等大型结构健康监测

LabVIEWL实现鸟巢等大型结构健康监测

LabVIEWL实现鸟巢等大型结构健康监测 管理国家地震防备和减灾的政府机构中国地震局(CEA)选择了七座新建的巨型结构作为结构健康监测(SHM)技术的测试台。这些标志性建筑包括北京2008年夏季奥运会场馆&#xff08;包括北京国家体育场和北京国家游泳中心&#xff09;、上海104层的…
阅读更多...
Eureka简单使用做微服务模块之间动态请求

Eureka简单使用做微服务模块之间动态请求

创建一个eureka模块,引入eureka 为启动项加上EnableEurekaServer注解 配置信息 orderService和userService的操作是一样的 这里以orderService为例: 引入eureka客户端 加上 LoadBalanced注解 配置 orderService和userService都配置好了之后 启动 这样我们在http://localhos…
阅读更多...
最新文章

Copyright @ 2022~2023