直接从源代码生成JavaScript文档

Question

我正在寻找一种工具来生成JavaScript函数和属性的文档,即使没有与这些函数或属性相关的适当格式化的注释块(如Doxygen那样).

JSDoc和其他一些文档工具之间的比较提到JSDoc可以解析源代码以生成文档,即使没有注释块(像Doxygen,如上所述).他们说所有其他工具只解析注释块.

我根据这条指令从npm(在节点上)安装了JSDoc 3.3.0-alpha4 ,我正在尝试为我的项目生成文档.据我所知,JSDoc不会为没有相关JSDoc标志的正确注释的函数或属性生成任何文档.

我知道JSDoc经历了多次迭代,是否已删除此功能或我没有使用正确的交换机？我试图检查命令行选项,但找不到任何开关.我只是这样使用它:

./node_modules/.bin/jsdoc -r -l my_project --destination doc/

我知道还有其他工具可以自动为代码添加文档块,例如smartcomments,但这并不是我想要的.任何人都可以对此有所了解吗？

Answer 1

我在我的项目中使用了Yuidoc。它不读取代码，只读取像 @class、@module、@method 等这样的 Yuidoc 标签...包含在注释块中，如下所示： /** */ 您可以将其用作 NodeJs 扩展并通过输入来生成 api使用 Node cmd 访问 javascript 文件夹并运行命令：

yuidoc .

如果您不知道如何使用它，一开始会有点棘手。

例如，如果您有一个像这样的 yuidoc 标签：

/**
 * @class Claculator
 * @method claculate
 * @param {Number} a
 * @param {Number} b
 * @return {Number}
 */
function calculate(a, b) {

}

/**
 * @class Graphics
 * @method drawGUI
 * @param {Number} x
 * @param {Number} y
 * @param {Number} z
 * @return {Number}
 */
function drawGUI(x, y, z) {

}

@class 标签后面的所有方法/属性在生成后都将成为 Calculator 类的一部分。因此，如果在calculate(a, b)之后有一个名为drawGUI()的方法，并且它应该属于其他类，例如Graphics，那么您应该在另一个@class标签中注意到这一点，就像上面的例子一样。

注意：从我的角度来看，编写注释块可以帮助您在开发时提高代码质量，还可以帮助您在问题发生之前发现问题。