jsdoc 和 vscode：记录作为参数传递给另一个函数的函数答案

【问题标题】：jsdoc and vscode: Documenting a function passed as an argument to another functionjsdoc 和 vscode：记录作为参数传递给另一个函数的函数
【发布时间】：2018-03-28 09:14:04
【问题描述】：

我正在尝试将输入参数记录到 javascript 中的函数中，但我不知道如何在 jsdoc 中执行此操作。

我查看了 jsdoc 文档，该文档建议使用 @callback 注释是必需的，但 Visual Studio Code (vscode) 并未按照屏幕截图突出显示它。

location 参数的智能感知显示它是 any 类型而不是 locator 类型（参数为 id 的函数返回 Location）。

显示函数调用作为参数传递的函数的示例代码：

class Location {
  constructor(position, count) {
    this.position = position;
    this.count = count;
  }
}

const items = {
  'USB Cable': new Location('Desk Drawer', 123),
  Keyboard: new Location('Desk Surface', 1),
};

/**
 * A locater.
 * @param {string} id 
 * @returns {Location}
 */
const locaterA = id => items[id];

/**
 * Finds the item by its unique id.
 * @callback locater
 * @param {string} id
 * @returns {Location}
 */

/**
 * Attempt to find the item with the given locater.
 * @param {string} id 
 * @param {locater} locater
 */
const locate = (id, locater) => locater(id);

const result = locate('USB Cable', locaterA);

console.log(result);

这是我在做什么的问题，vsdoc不支持用例，还是vscode不支持？

【问题讨论】：

标签： javascript node.js visual-studio-code jsdoc

【解决方案1】：

编辑：vscode似乎从TypeScript 2.9
开始支持@callback

Vscode 的 IntelliSense 不支持 @callback。它在这里被跟踪：https://github.com/Microsoft/TypeScript/issues/7515。

作为一种方便的解决方法，您可以使用@typedef：

/**
 * Finds the item by its unique id.
 * @typedef {function(string): Location} Locater
 */

/**
 * Attempt to find the item with the given locater.
 * @param {string} id 
 * @param {Locater} locater
 */
const locate = (id, locater) => locater(id);

【讨论】：

请注意，如果您不重用定义，则不需要@typedef。 * @param {function(string): Location} fn

【解决方案2】：

根据 JSDoc 本身，您似乎使用正确。但是，看起来 Visual Studio 可能只支持有限的 JSDoc 子集，其中不包括 @callback:https://msdn.microsoft.com/en-us/library/mt162307.aspx

我手边没有 Visual Studio，但你可以试试 Google Closure 样式，就是这样：

@param { function(string) : number } locator

这表示它是一个接受字符串并返回数字的函数。

您可以在此处找到该文档：https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler（搜索“函数返回类型”以跳转到相关部分）。

我至少注意到 JetBrains 的东西，它支持这种语法。

【讨论】：