Nodejs 求一个文档工具，jsdoc?

Nodejs 求一个文档工具，jsdoc?

希望可以，方便生成文档，方便webstorm里面提示的的方案 如果函数的传入 传出是json,希望生成工具可以把这个传入json的结构表示出来

10 回复

Node.js 文档工具推荐：JSDoc

如果你正在寻找一个可以帮助你生成高质量文档的工具，并且希望这个工具能够很好地集成到你的开发环境中（例如 WebStorm），那么 JSDoc 是一个非常不错的选择。JSDoc 是一个基于注释的 JavaScript 文档生成器，它允许你在代码中添加特定格式的注释来描述你的代码结构和功能。

为什么选择 JSDoc？

  1. 强大的注释语法：JSDoc 提供了一套丰富的注释语法，可以让你详细地描述函数、类、属性等。
  2. 易于集成：JSDoc 可以很容易地与现代 IDE 集成，如 WebStorm，从而提供更好的代码提示和自动完成功能。
  3. 灵活的输出格式：JSDoc 支持多种输出格式，包括 HTML、Markdown 等，可以根据需要定制输出样式。

示例代码

假设你有一个简单的 Node.js 函数，该函数接受一个 JSON 对象作为参数，并返回一个 JSON 对象。你可以使用 JSDoc 注释来描述这些输入和输出。

/**
 * 计算两个数字的总和。
 *
 * @param {Object} data - 输入数据对象。
 * @param {number} data.num1 - 第一个数字。
 * @param {number} data.num2 - 第二个数字。
 * @returns {Object} - 输出结果对象。
 * @returns {number} results.sum - 两数之和。
 */
function sum(data) {
    return {
        sum: data.num1 + data.num2
    };
}

在这个例子中：

  • @param 注释用于描述函数的输入参数 data，并进一步说明了 data 中包含的字段 num1 和 num2。
  • @returns 注释用于描述函数的返回值，包括返回的对象结构。

如何生成文档

安装 JSDoc：

npm install -g jsdoc

运行 JSDoc 命令来生成文档：

jsdoc yourfile.js -d docs

这将会在 docs 目录下生成 HTML 文档，其中包含了你代码中的所有注释信息。

通过这种方式，JSDoc 不仅可以帮助你生成详细的文档，还能提升你在 WebStorm 中的开发体验，因为这些注释可以被 IDE 解析，从而提供更好的代码提示和自动完成功能。


最近在公司做后天管理的接口开发，目前最烦的就是写文档，同求一个文档生成工具。

Sphinx 挺不错的，可惜是 Python 写的。有 node 写的就好了。 https://pypi.python.org/pypi/Sphinx

gulp 和 grunt 都有文档生成插件 使用略复杂

yuidoc，我最近在用的，我个人觉得比jsdoc要好一些

使用代码注释生成文档…不怎么看好…

sphinx 蛮好的, 写完发到 readthedocs , 做个CNAME转发到自己域名

ASP.NET 现在就是用的这个 see http://aspnet.readthedocs.org/en/latest/ http://docs.asp.net/en/latest/

类似的gitbook 可以试试…

感觉markdown写作还是弱了些.

可以试试 fireball-x/firedoc 是我们内部基于yuidoc做的文档生成工具，增加了markdown的主题(https://github.com/fireball-x/firedoc/tree/master/docs)以及多语言、枚举、函数参数定义、模组方法等特性。

最近研究了几个 最后选了这个 http://apidocjs.com/

Node.js 文档工具：使用 JSDoc

JSDoc 是一个用于生成 JavaScript 库文档的工具。它可以解析源代码中的注释，并生成 HTML 文档，这些文档包含了类、方法、属性等的信息。这对于提高代码可读性和提供更好的 IDE 提示非常有帮助。

安装 JSDoc

首先需要安装 JSDoc，可以使用 npm 进行安装：

npm install -g jsdoc

基本用法

  1. 添加注释：在代码中添加适当的 JSDoc 注释来描述你的函数、变量和其他元素。
  2. 生成文档：使用 JSDoc 工具根据注释生成文档。
示例代码

假设我们有一个简单的 JavaScript 文件 example.js，其中包含一个函数，该函数接收一个 JSON 对象作为参数并返回另一个 JSON 对象。

/**
 * 计算两个数字的总和。
 *
 * @param {Object} data - 包含两个数字的对象。
 * @param {number} data.num1 - 第一个数字。
 * @param {number} data.num2 - 第二个数字。
 * @returns {Object} 包含计算结果的对象。
 * @returns {number} result - 两个数字的总和。
 */
function addNumbers(data) {
    return {
        result: data.num1 + data.num2
    };
}

module.exports = addNumbers;

生成文档

在命令行中运行以下命令以生成文档：

jsdoc example.js -d docs

这将在当前目录下创建一个名为 docs 的文件夹，其中包含生成的 HTML 文档。

在 WebStorm 中使用

在 WebStorm 中，可以通过安装插件（如 JSDoc Code Navigator）来增强对 JSDoc 的支持。这将使你在编写代码时能够看到函数参数和返回值的详细信息，从而提高开发效率。

总结

JSDoc 可以帮助你为项目生成详细的文档，并且可以在 IDE 中提供更好的代码提示。通过正确地使用 JSDoc 注释，你可以更好地描述你的代码结构和功能，使代码更容易理解和维护。

回到顶部