网站关键字设置格式/免费的网站推广软件下载
文章目录
- 1. 前言
- 2. [jsdoc](https://jsdoc.app/)
- 2.1 创建配置文件
- 2.2 配置执行命令
- 3. [生成 markdown 文档](https://github.com/jsdoc2md/jsdoc-to-markdown)
- 3.1 配置执行命令
- 4. DEMO
1. 前言
在编码的过程中，很多情况下我们都有输出 api 文档的需求，因此本文将介绍如何使用 jsdoc 输出 api 文档。
2. jsdoc
JSDoc 是一个用于 JavaScript 的 API 文档生成器，类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中，就在代码本身旁边。 JSDoc 工具将扫描源代码并生成 HTML 文档。
安装依赖包：
npm i -D jsdoc@3
2.1 创建配置文件
// jsdoc.js
module.exports = {recurseDepth: 10,source: {include: ['dist'],exclude: [],includePattern: '.+\\.js$',excludePattern: '.+\\.ts$',},sourceType: 'module',tags: {allowUnknownTags: true,dictionaries: ['jsdoc', 'closure'],},templates: {cleverLinks: true,monospaceLinks: true,},opts: {destination: './docs/',encoding: 'utf8',recurse: true,},
}
2.2 配置执行命令
// package.json
{// ..."scripts": {"jsdoc": "jsdoc -R README.md -c jsdoc.js tsc-out/**/*.js --verbose"}// ...
}
执行npm run jsdoc即可在“docs”生成 html 文档。
3. 生成 markdown 文档
从 jsdoc 注释的源代码生成 Markdown API 文档。用于将 API 文档注入项目 README 文件中。
安装依赖包：
npm i -D jsdoc-to-markdown@7
3.1 配置执行命令
// package.json
{// ..."scripts": {"jsdoc2md": "jsdoc2md tsc-out/**/*.js > docs.md"}// ...
}
4. DEMO
本小节将演示如何使用 jsdoc 语法编写 js 文件，详细用法请参阅 jsdoc 官方文档。
const os = require('os')
const path = require('path')const LOCAL_OS_TYPE = os.type()
const LOCAL_HOSTNAME = os.hostname().toLowerCase()
const LOCAL_HOME_DIR = os.homedir()/*** @class OSUtils* @classdesc OSUtils*/
class OSUtils {/*** 定义操作系统类型* @static* @memberof OSUtils*/static OS_TYPE = {MAC_OS: 'Darwin',LINUX: 'Linux',WINDOWS: 'Windows_NT',}/*** 判断是否是macOS* @static* @return {boolean}* @memberof OSUtils*/static isMacOS() {return LOCAL_OS_TYPE === OSUtils.OS_TYPE.MAC_OS}/*** 判断是否是 linux* @static* @return {boolean}* @memberof OSUtils*/static isLinux() {return LOCAL_OS_TYPE === OSUtils.OS_TYPE.LINUX}/*** 判断是否是 windows* @static* @return {boolean}* @memberof OSUtils*/static isWindows() {return LOCAL_OS_TYPE === OSUtils.OS_TYPE.WINDOWS}
}module.exports = OSUtils