javascript - 让 JSDoc 正确记录嵌套闭包

Question

我有一个大的、结构良好的 JavaScript 对象，它是这样的:

/**
 * My 'class' begins here.  JSDoc barfs on this.
 */
var MyClass = (function(window, document, $) {

    return function(options) {

        "use strict";

        var
            x = 123,

            /**
             * This is a "public" function.
             */
            myFunc = function() { /*...*/ },

            /**
             * This is some other "private" function.
             */
            otherFunc = function() { /*...*/ };

        return {
            myFunc: myFunc
        };
    };

})(window, document, window.jQuery);

实际上，最外层闭包用于控制实现模块模式形式的内部闭包所看到的全局范围:内部函数实际上是构造函数，其嵌套函数是有效方法，返回的对象实际上是它的哪些部分是“公共(public)”的列表。

JSDoc 讨厌这个。

(作为记录，我使用的是 JSDoc 3.4。)

我在 @lend 上尝试了几种变体和 @export和 @namespace和 @memberof在这段代码的很多地方，但无论我做什么，JSDoc 都拒绝注意到任何内部函数——它不仅仅是“不将它们与正确的事物联系起来”；它根本不将它们包含在任何输出文件中。

这是紧密封装经典 JavaScript 的绝佳模式，不仅封装了它的内部结构，还封装了它的依赖项，我们的实际应用程序在数千行代码中使用了这种模式。所以我们的 JavaScript 本身不会很快改变结构:只有注释可以合理地改变。

我希望能够使用 JSDoc 来记录这个应用程序，但是无论我给它什么，JSDoc 在这方面都失败了。在 StackOverflow 上四处寻找已经确定了处理各种知名模块系统的方法，但我还没有找到使用多重嵌套闭包的纯 jane JavaScript 的可靠答案。

那么有没有人有办法让JSDoc正确生成 MyClass作为一个“类”结构，其中深层嵌套的函数作为该“类”的“方法”？我同意标记 otherFunc作为 @private或将其标记为隐藏，或必须标记 myFunc作为 @public或将其标记为可见的东西，但无论我尝试什么，JSDoc 似乎根本不想记录任何这些嵌套函数。

Answer 1

我知道这是一个死灵，但实际上没有任何好的文档，所以就在这里。我花了整整两天时间阅读其他人的代码并尝试弄清楚这一点。这是使用 3.6.7
基本上:

您必须使用命名空间，但 JSDoc 不喜欢命名空间与函数同名，因此您必须通过在所有函数命名空间前加上波浪号来隐藏命名空间相同的事实。 ~ 波浪线本身不会出现在文档中，但如果你没有它们，JSDoc 会感到困惑。这在我能找到的任何地方都没有真正记录，我从 JSDoc 处理返回值的方式推断它。

您需要有一个基于实际属性的“根”命名空间。 const ClosureDoc = {version: "1.0.0"};在下面的代码中，在 /** @namespace */ 下方大喊。试图删除实际对象并只拥有 /** @namespace ClosureDoc */不工作。不知道为什么，这在任何地方都没有记录。

您需要手动显式命名所有内部函数。所有作为函数的返回值也必须手动显式定义，但如果使用 * @returns {outerScope~innerScope}，则实际上不需要 @typedef (注意波浪号)

总而言之，这似乎是一个荒谬的手动操作，以获得非常合理的代码的非常简单的结果，但它可以完成。
`

'use strict';
/** @namespace */
const ClosureDoc = {version: "1.0.0"};

/**
 * Outer scope is used to enclose the inner scope
 * @function outerScope
 * @returns {outerScope~innerScope}
 * @returns {outerScope~logInnerMap}
 * @memberof ClosureDoc
 */
function outerScope () {
    /**@namespace ClosureDoc.~outerScope */
    const outerState = {
        innerMap: {}
    }

    const newInnerScope = (name) => (outerState.innerMap[name] = innerScope(name));
    const namedInnerScope = (name) => !(name in outerState.innerMap) ? newInnerScope(name) : outerState.innerMap[name];

    /**
     * Inner Scope is used inside the outer scope
     * @function innerScope
     * @param {string} name
     * @returns {innerScope~logScopeName}
     * @memberof ClosureDoc.~outerScope
     */
    function innerScope(name) {
        /**@namespace ClosureDoc.~outerScope.~innerScope */
        /**
         * Logs the name passed to the inner scope
         * @function logScopeName
         * @memberof ClosureDoc.~outerScope.~innerScope
         */
        function logScopeName() {
            console.log(name);
        }
        return {
            logScopeName
        }
    } 
    /**
     * Logs the map of all scope names
     * @function logInnerMap
     * @memberof ClosureDoc.~outerScope
     */
    function logInnerMap() {
        console.log(outerState.innerMap);
    }
   return {
       namedInnerScope,
       logInnerMap
    }
}

const outer = outerScope();
const inner_1 = outer.namedInnerScope("Bob");
const inner_2 = outer.namedInnerScope("Dole");
inner_1.logScopeName();
inner_2.logScopeName();
outer.logInnerMap();

`