电子商务网站建设 名词解释,创建网站大约多少钱,适合学生做网页练习的网站,校园网子网站建设管理意见或策划一. 简介 JSDoc 3 是一个用于 JavaScript 的API文档生成器#xff0c;类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中。JSDoc 工具将扫描您的源代码并为您生成一个 HTML 文档网站。 JSDoc 是一种用于 JavaScript 代码文档注释的标记语言和工具。它不仅…一. 简介 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 valueJSDoc 配置文件的路径。默认为安装 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 中。示例foobarbaztrue。-r, --recurse扫描源文件和导览时递归到子目录。-R, --readme用来包含到生成文档的 README.md 文件。默认为在源路径中找到的第一 README.md 文件。-t value, --template value用于生成输出文档的模板的路径。默认为 templates/defaultJSDoc 内置的默认模板。-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/defaultencoding: utf8, // same as -e utf8destination: ./out/, // same as -d ./out/recurse: true, // same as -rtutorials: 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 modulessourceTypeJSDoc 允许您使用无法识别的标签tags.allowUnknownTags,该属性影响 JSDoc 如何处理无法识别的标签。如果将此选项设置为 falseJSDoc发现它不能识别例如,fooJSDoc 将记录一个警告。默认情况下此选项设置为 true。标准 JSDoc 标签和 closure 标签被启用tags.dictionaries 属性控制 JSDoc 识别哪些标签以及 JSDoc 如何解析它识别标签。在 JSDoc3.3.0 或更高版本中有两个内置的标签词典 jsdoc: 核心JSDoc标签closure: Closure Compiler 标签 link标签呈现在纯文本templates.cleverLinkstemplates.monospaceLinks。opt: 可以将 JSDoc 的许多命令行选项放入配置文件中而不是在命令行中指定它们。为此将相关选项的长名称添加到配置文件的 opts 部分并将值设置为该选项的值。 五. 标签 JSDoc支持两种不同类型的标签 块标签(Block), 这是在一个JSDoc注释的最高级别。内联标签(inline), 块标签文本中的标签或说明。 块标签通常会提供有关您的代码的详细信息如一个函数接受的参数。内联标签通常链接到文件的其他部分类似于HTML中的锚标记a。 块标签总是以 at 符号开头。除了 JSDoc 注释中最后一个块标记每个块标签后面必须跟一个换行符。 内联标签也以 at 符号开。然而内联标签及其文本必须用花括号{ and }括起来。 { 表示行内联标签的开始而 } 表示内联标签的结束。如果你的标签文本中包含右花括号}则必须用反斜线 \ 进行转义。在内联标签后,你并不需要使用一个换行符。 1. 块级标签 块级标签使用说明 2. 内联标签 内联标签使用说明 六. 使用 1. 安装 npm install -g jsdoc2. 生成文档 jsdoc -r src -d doc-r表示源目录-d表示生成的目标目录或者使用配置文件生成 jsdoc -c /path/to/conf.json