介绍
JSDoc 这是一个用于生成 JavaScript API 文档的开源工具。它允许开发者使用注释来编写代码文档。.
使用 JSDoc 编写文档的示例代码
以下是如何编写方法文档的示例：
/**
* یک فایل را بر اساس شناسه بازیابی میکند.
* @param {string} id شناسه فایل.
* @returns {File} شی فایل.
*/
const getFileById = (id) => {
// کد...
}安装 JSDoc
您可以使用以下方式全局使用 JSDoc npm 安装：
npm install -g jsdoc或者按如下方式为特定项目安装：
npm install --save-dev jsdoc如何使用 JSDoc
添加文档
要开始为你的代码添加文档，只需添加一条注释即可。 /** 在每个代码块（模块、方法、类、函数等）的顶部添加：
/**
* کاربر را با استفاده از ایمیل بازیابی میکند.
*/
const getByEmail = async (email) => {
// کد...
}您还可以使用 JSDoc 标签添加更多信息：
/**
* کاربر را با استفاده از ایمیل بازیابی میکند.
* @async
* @method
* @param {String} email - ایمیل کاربر
* @returns {User} شی کاربر
* @throws {NotFoundError} اگر کاربر پیدا نشود.
*/
const getByEmail = async (email) => {
// کد...
}文档制作
添加注释后，要将文档生成为网站，只需运行以下命令：
jsdoc path/to/my/file.js进阶技巧
使用配置文件
如果您的项目很大，包含许多文件和文件夹，您可以使用配置文件来自定义 JSDoc 的行为：
{
"source": {
"includePattern": ".+\\.js(doc|x)?$", // فقط فایلهای با پسوند .js، .jsdoc یا .jsx پردازش شوند.
"include": ["."], // تمام پوشهها بررسی شوند.
"exclude": ["node_modules"] // پوشه node_modules نادیده گرفته شود.
},
"opts": {
"destination": "./docs/", // مقصد تولید مستندات.
"recurse": true // پوشهها به صورت بازگشتی بررسی شوند.
}
}VSCode 支持
VSCode 编辑器默认支持 JSDoc，提供诸如注释结构自动完成和显示函数信息等功能。.
使用自定义模板
您可以通过创建文件来覆盖默认的 JSDoc 格式。 布局模板 在配置文件中进行自定义和指定。.
结果
JSDoc 是一款功能强大的 JavaScript 代码文档工具，它不仅可以帮助开发者更好地理解他们的代码，还可以自动生成 API 文档。.
