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

How to document return value of function that calls another function

本文关键字：函数 另一个 返回值 调用 何记录 记录      更新时间：2023-09-26

给定以下示例：

/**
 * 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
}

则CCD_ 1返回另一个函数的结果。

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

  • @returns {number}-我们知道addTen返回一个数字，但是如果这个数字改变了呢？我们将不得不同时更新这两个（或者每次返回时都要更新，这可能会很多），这是不可维护的。

  • @returns {function}-我不确定JsDoc中是否有此功能。我哪儿也找不到。这也没有提供太多信息。

  • @returns {any}或-@returns {*}-这对阅读文档的人没有特别的帮助。

由于上述原因，我觉得这些都不正确。

我想我想要像一样的东西

@returns {addTen.return}

因此，我本质上是在说"outerFunction返回addTen所做的任何类型"。

注意：在这个例子中，它们在同一个地方，但可能包含在多个文件中，所以使用这种方法是行不通的，除非可以在多个档案中执行。

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

是否存在与我的建议类似的内容？

outerFunction的调用方将对该函数作为参数接受的内容以及它将返回的内容有一定的期望。outerFunction0的调用者并不关心outerFunction做什么，只关心它的接口按照描述工作。outerFunction的调用方不知道或不关心，也不应该关心某个名为addTen的函数参与了outerFunction所做的任何事情。事实上，有一天您可能会重写outerFunction的整个实现，不再调用addTen，而是保持它的行为完全相同。

将每个功能单独视为一个黑盒。你在描述outerFunction的接口，所以描述它做什么/应该做什么。不要用其他可能相关或不相关的功能来描述它。如果outerFunction预计会返回一个数字，请这样描述它。如果addTen碰巧也返回了一个数字，那么，这真是巧合。

我理解隐含地将一个函数的返回值与另一个函数返回值联系起来的动机，因为这就是它的实际实现方式，你知道。。。DRY和所有。。。但在这种情况下，这会适得其反。在两个不同的函数上"重复"关于返回类型的"相同信息"并不重要；因为你不是在描述一个相连的东西。这两个功能都是独立的黑盒，具有各自的特定签名；它们的实现恰好是耦合的，这与此无关，事实上明天可能会发生变化。重要的是签名保持原样。

事实上，如果addTen确实更改了它的返回类型（并且outerFunction也隐式地更改了它），那么无论如何，这将是一件大事，而不仅仅是通过隐式更新一些文档来破坏它。通过更改任何函数的返回类型，您就打破了以前建立的契约，这将对该函数的每个用户产生一连串的影响。在这种情况下，隐式自动更新outerFunction的返回类型是最不担心的，因为您可能需要重写大量代码以符合新合同。

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

因此，在本例中，如果您只需要编辑器中的一些类型提示，则不需要向outerFunction:添加任何返回类型

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

以上代码将自动工作（如果正确键入addTen）。但如果您真的需要引用addTen的返回类型，例如：

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

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

/**
 * @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的人，我希望这会有所帮助。

相关文章：