一. 简介
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 提供配置文件:
要使用配置文件运行 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
); - @link标签呈现在纯文本(
templates.cleverLinks
,templates.monospaceLinks
)。 - opt: 可以将 JSDoc 的许多命令行选项放入配置文件中,而不是在命令行中指定它们。为此,将相关选项的长名称添加到配置文件的
opts
部分,并将值设置为该选项的值。
五. 标签
JSDoc支持两种不同类型的标签:
块标签通常会提供有关您的代码的详细信息,如一个函数接受的参数。内联标签通常链接到文件的其他部分,类似于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
原文地址:https://blog.csdn.net/sxlesq/article/details/134649864
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。
如若转载,请注明出处:http://www.7code.cn/show_3736.html
如若内容造成侵权/违法违规/事实不符,请联系代码007邮箱:suwngjj01@126.com进行投诉反馈,一经查实,立即删除!