JSDoc：在另一个@param中引用方法的参考

Question

我是新手，正在学习使用JSDocs，但找不到答案。

假设我想编写这个简单的函数：

function hasQ(array, item) {return array.includes(item);}

使用 JSDoc，我会进行标记，如下：

/**
* Another way to call array.includes(item);
* @param {Array} array
* @param {*} item to test if contained in array
* @returns
*/

有没有一种方法可以标记第二个 @param 语句中的 array，使其引用第一个 @param？

这只是一个玩具例子，但我希望它能清楚地说明概念。

- SumNeuron

Answer 1

叉引用参数

关于@param，就我所知，目前没有办法进行参数叉引用。如此处所建议的，您可以使用普通英语。

作为部分解决方案，您可以使用 markdown 的反引号来突出显示 param 名称（如这里所述），例如：

/**
 * @param {*} item to test if contained in `array`
 */

旁注：引用外部资源

JSDoc 中有内联 @link 到 外部 资源的概念，我认为在这里也会很有用。你可以在描述中明确指出，例如你正在谈论 Array 的 includes 函数：

/**
* Another way to call [Array's includes function]{@link external:Array#includes}
* @param {Array} array
* @param {*} item to test if contained in array
* @returns
*/
function hasQ(array, item) {
    return array.includes(item);
}

如果你想要一个没有 文本 的链接，则只需删除第一行中括号 [] 中的部分:

/**
 * Another way to call {@link external:Array#includes}
 */

阅读更多

如果您对以下内容感兴趣：

• @external标签
• 内联@link标签
• @see标签

- Babak

Answer 2

无法做到。来源：https://github.com/jsdoc/jsdoc/issues/1145

- Hernán Pentimalli

Answer 3

我没有看到编写相关参数的可能性（但请参见具有属性的参数）。但您可以编写描述；）

/**
 * @method
 * @param {Array} array - description for this param
 * @param {*} item - description for this param
 * @description Please write your description for Method
 * @returns {*|boolean}
 */
const hasQ = (array, item) => array.includes(item);

- Valera Checha

---

虽然答案在技术上是正确的，但表述相当混乱，可能是语言问题。我并不挑剔，但我不得不读很多遍才明白它所说的与我发布的答案相同。 - Hernán Pentimalli