让 JSDoc 为模块中的私有（非导出）函数生成文档

Question

我正在使用 JSDoc 生成器为我正在使用 AMD 模块的项目生成一些好看的文档。

在我的项目中，我有一些模块包含未导出的函数，因此无法从模块外部使用它们。生成 JSDoc 时，这些函数不包含在文档中。

我创建了以下示例模块来说明我的示例：

/**
 * Example foobar module
 * @module foobar
 */
define([], function () {

    /**
     * Returns foo
     * @returns {string} - The string "foo"
     */
    function foo() {
        return "foo";
    }

    return {
        /**
         * Returns bar
         * @returns {string} - The string "bar"
         */
        bar: function(){
            return "bar";
        }
    }
});

当我为上述模块生成文档时，文档中只包含 bar 函数，而我还希望将 foo 函数包含在我的文档中并标记为私有。

有什么方法可以实现吗？谢谢。

Answer 1

注意：这是在 JSDoc 3 上测试的

这有两个部分：

• 获取 JSDoc 为嵌套函数生成代码
• 获取 JSDoc 为私有成员生成代码

获取 JSDoc 为嵌套函数生成代码

/**
 * Returns foo
 * @memberOf module:foobar
 * @returns {string} - The string "foo"
 */
function foo() {
    return "foo";
}

默认情况下，嵌套函数没有文档记录。为此，请添加 @memberOf 指令。这迫使 JSDoc 将函数记录为模块的成员。注意 module: 前缀 - 这是一个标准。

这应该使foo 显示在模块foobar 的Methods 部分下。

获取 JSDoc 为私有成员生成代码

现在，只需将该函数标记为私有。为此，请使用@private 指令。

/**
 * Returns foo
 * @private
 * @memberOf module:foobar
 * @returns {string} - The string "foo"
 */
function foo() {
    return "foo";
}

您会注意到现在文档再次不包含方法foo。这是因为 JSDoc 默认忽略私有成员。要同时为私有成员生成代码，请使用-p 命令行选项。

jsdoc foobar.js -p

现在 foo 在foobar 中显示为(private, static) 方法，而bar 只是(static)。