如何告诉 JSDoc 我将命名空间对象作为参数传递？答案

【问题标题】：How to tell JSDoc that I'm passing a namespace object as parameter?如何告诉 JSDoc 我将命名空间对象作为参数传递？
【发布时间】：2013-10-20 20:04:29
【问题描述】：

我正在使用匿名函数向命名空间对象添加方法。最后，我希望 JSDoc（版本 3.3）为MyNamespace.func1()、MyNamespace.func2() 等生成文档。我想我可以将此信息添加到函数中定义的每个方法中，但这会容易得多让 JSDoc3 识别 ns 与 MyNamespace 相同。我该怎么做？

/** @namespace */
var MyNamespace = {};

// (... some code that adds to MyNamespace ...)

(function (ns) {

    /** Method description 1 */
    ns.func1 = function (val) {};

    /** Method description 2 */
    ns.func2 = function (val) {};

    // ...etc

})(MyNamespace);

【问题讨论】：

标签： javascript namespaces documentation jsdoc

【解决方案1】：

您可以在 aliases 的 JSDoc 文档中看到类似场景的示例，请参阅“将@alias 用于命名空间的静态成员”部分

【讨论】：

谢谢，我有那个例子。这只有在我有一个 var anon 函数内部某个容器的声明而不是函数参数时才有效。最后，我放弃并重新构建了我的代码。恕我直言，文档工具不应该强迫我这样做，但这就是生活。我会为我最终使用的内容添加一个答案。

【解决方案2】：

显然，这在 JSDoc 3 中是不可能的（目前）。

我最终使用了一个合并/扩展/增强类型的辅助函数，如下所示：

(function (ns) {

    extend(ns, /** @lends ns */ {

        /** Method description 1 */
        func1: function (val) {},

        /** Method description 2 */
        func2: function (val) {},

        // ...etc
    });

})(MyNamespace);

这为 JSDoc 提供了创建正确文档所需的一切。一个小缺点是 func1 现在将在 Chrome 错误控制台堆栈跟踪中显示为 extend.func1。

【讨论】：