JSDoc：如何为父级“类”文档化“options”对象文字？

Question

我正在使用jQuery的$.widget()基本“类”，它提供了一个option()方法。由于该方法不在我的代码中，我没有地方记录参数。

我尝试在默认选项文字中放置jsDoc字段，但是它们根本没有被捕获。然后，我尝试在同一对象文字上使用@class和@lends标签，但是这可能会非常令人困惑，因为对象文字实际上并不是一个类。

我尝试的另一种选择是在构造函数的jsDoc中放置类似@param options.field description的内容。但是，这样做的缺点是将文档与代码分离。此外，构造函数实际上没有名为options的参数，因为所有这些都由jQuery处理。

JavaScript高手们如何处理这个问题？是否应该提出一个新的标签？

- billc.cn

---

你的问题听起来非常类似于这个：https://dev59.com/Omw15IYBdhLWcg3wqNuM - Levi Hackwith

@LeviHackwith 是的，它是相似的，但正如我在问题中所描述的那样，我没有一个可以使用 @param 标签的地方，因为 jQuery 的开发人员已经实现了所有的样板代码（包括通常会使用 @param 标签的 options() 函数）。 - billc.cn

/** @param {Object.<string,*>} options */ 看起来是一种实现的方式。 - Paul Sweatte

我认为这不是与链接问题重复的内容，因为这是特定于jQuery小部件的。我有同样的问题，并推断由于通常（至少在我们的情况下）在实例化小部件时指定选项，所以我将@param {Object} [options]放置在小部件声明$.widget("myWidget", {...})中，如下面的答案所示。 - d4kris

Answer 1

如果我正确理解您的问题，您有一个接受选项对象的函数，并且您想记录其所有成员变量？

JSDoc 中如何完成这个任务的简单示例如下：

/**
 * @description
 * Compliment someone on their something.
 *
 * @param {Object} options
 * @param {String} options.name    A person's name
 * @param {String} options.feature A person's property
 */
function flatter (options) {
  options = options || {};
  console.log('%s, loving your %s!', options.name, options.feature);
}

- Jamie Mason

---

有没有可能记录一个带空格的属性，例如 options['some property']？ - M Miller

这不是我尝试过的，尝试几种引用该值的变体并运行jsdoc生成器以查看结果。之后请告知我们所有人。 - Jamie Mason

既然这个问题一直被推到前面，我在这里澄清一下：这不是我的具体问题的答案，因为正如我所说，jQuery提供了“option”方法，所以我没有一个选项文字是参数的方法。 - billc.cn

我们实际上需要 @description 吗？我从未看到过它被使用。当我看到它时，通常认为第一行就是描述。 - pcatre

你说得对，@pcatre。我倾向于使用它，因为它符合我的偏好，但是如果没有它也不会有问题。 - Jamie Mason