如何记录调用另一个函数的函数的 return 值

Question

给定以下示例：

/**
 * An outer function
 * @param {number} age - The age to pass to outerFunction
 * @returns {#What goes here?#}
 */
function outerFunction(age){
    return addTen(age)
}

/**
 * Adds 10 to the age
 * @param {number} age - The age to add 10 to
 * @returns {number} - The age + 10
 */
function addTen(age){
    return 10 + age
}

outerFunction returns 另一个函数的结果。

我想了几种方法来记录这个：

@returns {number} - 我们知道 addTen returns 是一个数字，但是如果这个数字发生变化呢？我们将不得不更新两者（或者每次返回时，可能会很多），这是不可维护的。
@returns {function} - 我不确定这在 JsDoc 中是否可用。我到处都找不到。这也感觉它提供的信息不多。
@returns {any} 或 - @returns {*} - 这对阅读文档的任何人都不是特别有帮助。

None 出于上述原因，我觉得这些是正确的。

我想我想要

@returns {addTen.return}

所以我基本上是在说“outerFunction returns 类型 addTen 所做的任何事情”。

注意：在这个例子中它们在同一个地方，但可能包含在多个文件中，所以使用不起作用，除非它是可能的跨多个文件执行此操作。

我们如何编写 JsDoc 注释来记录函数 returns 另一个函数？

是否存在与我的建议类似的东西？

Answer 1

outerFunction 的调用者对该函数接受什么作为参数以及它将接受什么有一定的期望 return。 outerFunction 的调用者不关心 outerFunction 做了什么，只关心它的接口如描述的那样工作。 outerFunction 的调用者不知道或不关心也不应该关心 addTen 的某个函数参与了 outerFunction 所做的任何事情。事实上，有一天你可能会重写 outerFunction 的整个实现，不再调用 addTen，但保持它的行为完全相同。

将每个函数单独视为一个黑盒子。您正在描述 outerFunction 的界面，因此请描述它 does/is 应该做什么。不要用可能相关或不相关的其他功能来描述它。如果 outerFunction 预计 return 一个数字，请这样描述。如果 addTen 也恰好 return 一个数字，好巧啊。

我理解想要隐式地将一个函数的 return 值与另一个函数的值联系起来的动力，因为这就是它的实际实现方式，而且你知道......干......但是在这种情况适得其反。您 "repeat" 关于 return 类型的 "same information" 在两个不同的函数上并不重要；因为你不是在描述一个相关的东西。这两个函数都是独立的黑盒，具有自己的特定签名；它们的实现恰好是耦合的与此无关，而且明天可能实际上会改变。重要的是签名保持所描述的那样。

事实上，如果 addTen 确实改变了它的 return 类型（而且 outerFunction 也隐含地改变了它），那将是一件大事，不会被隐式更新一些文档。通过更改 any 函数的 return 类型，您将打破先前建立的契约，这将对该函数的每个用户产生连锁反应。在这种情况下，隐式和自动更新 outerFunction 的 return 类型是您最不用担心的，因为您可能必须重写大量代码以符合新合同。

Answer 2

这是个老问题了，最近刚遇到类似的问题。我将我的解决方案留给有此问题的任何人参考。但请注意，我所需要的只是 VS Code 中的一些类型提示。如果您正在使用一些 docgen 工具，或者您只能使用官方的 jsdoc 语法，那么这个答案可能不适合您。

所以在这个例子中，如果你只需要编辑器中的一些类型提示，你不需要添加任何 return 类型到 outerFunction:

/**
 * An outer function
 * @param {number} age - The age to pass to outerFunction
 */
function outerFunction(age){
  return addTen(age)
}

以上代码将自动运行（如果 addTen 键入正确）。但是如果确实需要引用addTen的return类型，例如：

// The param `addedAge` is definitely something returned by `addTen`
function outerFunction(addedAge) {
  return addedAge + addTen(10) // becomes `any`
}

在此示例中，如果 addedAge 是一个数字，则 outerFunction return 是一个数字；如果 addedAge 是一个字符串，那么它 return 也是一个字符串。在这种情况下，您可以：

/**
 * @param {ReturnType<addTen>} addedAge
 * @returns {ReturnType<addTen>}
 */
function outerFunction(addedAge) {
  return addedAge + addTen(10)
}

同样，这不是官方的 jsdoc 语法，但对于像 VS Code 这样的编辑器，打字系统构建在 TypeScript 之上，因此您可以直接使用 TypeScript 功能。

此外，您甚至可以在 jsdoc 中导入类型（或函数）：

/**
 * @param {ReturnType<import('../fn').addTen>} addedAge
 */
function outerFunction(addedAge) {
  return addedAge + addTen(10)
}

对于想要某些类型但还不能迁移到 TypeScript 的任何人，我希望这会有所帮助。

如何记录调用另一个函数的函数的 return 值

How to document return value of function that calls another function

javascript

documentation

jsdoc