使用 JSDoc 记录原型扩展函数答案

【问题标题】：Documenting Prototype Extension Functions with JSDoc使用 JSDoc 记录原型扩展函数
【发布时间】：2021-04-30 22:43:30
【问题描述】：

我有以下代码：

/** @module Array */

/**
 * Returns this model's attributes as...
 *
 * @memberof Array.prototype
 * @function
 * @name each
**/
Array.prototype.each = function( callback ) {

    var context = this;

    for( var i = 0; i < context.length; i++ ) {
        callback( context[ i ] );
    }

}

当我用 JSDoc 记录这个时，我得到：

为什么？我在 Gulp 上使用 JSDoc。

【问题讨论】：

你有没有设法让它工作？我有同样的问题，任何帮助将不胜感激。谢谢
很遗憾，我做不到；本机接口不支持这一点。我最终为执行此操作的 JSDoc 编写了一个包装器。一个简单、直接的实现是使用基本级别（全局可用的）对象，然后定义它们的原型。一个简单的 hack，但仍然有效。
你的目的是什么？你没有写出预期的结果。似乎您应该编辑答案。但我猜你希望#each 被记录在案。为此，只需添加 /** @class Array */ 而不是 /** @module Array */。您还可以从#each 中删除所有标签。
@FreeLightman，从 JSDoc 的角度来看，预期的输出应该是显而易见的。这个问题没有答案，标记或其他，因为这是每个人正在/正在经历的事情。 /** @class **/ 用于 ES6 特定的类声明。当我们使用 prototype 属性时，这又回来了。
@weirdpanda 有什么明显的？为了首先获得帮助，您需要编写您期望的内容。这是本网站所必需的。据我所知，模块只能有私有和静态变量。它们不能有实例方法，因为它们远离实例。只有类可以有实例。那么您指出@class 是特定于ES6 的信息来源是什么？当我从 jsdoc 文档中阅读时，情况完全不同。如果您选择@class，prototype 的缺点是什么？正如我现在看到的，each 中的所有 3 个标签都可以用@class 省略。

标签： javascript gulp jsdoc

【解决方案1】：

我遇到了与原始海报相同的问题，但我使用 copy() 和 equals() 方法扩展了 JSON 全局。

（由于上面的 cmets 存在一些争论，我将澄清：当我说“有同样的问题”时，我的意思是我放在 JSON.copy() 和 JSON.equals() 方法之前的 JSDoc cmets 没有出现在任何地方在我生成的文档中，这是一个问题，不仅因为该文档丢失了，还因为没有其他文档可以链接到 JSON.copy() 或 JSON.equals() 方法。）

按照上面 cmets 中 FreeLightman 的建议，只需添加以下行，即可为我解决问题。

/** @class JSON */

通过“解决问题”，我的意思是现在在我生成的文档中有一个专门针对 JSON 对象的页面，它包含 copy() 和 equals() 成员所需的文档，我可以链接到我文档中其他地方的那些成员。

由于这是最初的问题多年后，我会指出我使用的是 JSDoc 版本 6.14.12。

【讨论】：