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

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 {number}- 我们知道addTen返回一个数字，但如果这改变了怎么办？我们将不得不更新两者（或每次返回时，这可能很多），这是不可维护的。

• @returns {function}- 我不确定这是否在 JsDoc 中可用。我在任何地方都找不到。这也不觉得它提供了太多信息。

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

由于上述原因，这些对我来说都不是正确的。

我想我想要类似的东西

@returns {addTen.return}

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

注意：在本示例中，它们位于同一位置，但可能包含在多个文件中，因此使用此方法不起作用，除非可以跨多个文件执行此操作。

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

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

Answer 1

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

将每个功能单独视为黑匣子。您正在描述 的接口outerFunction，因此请描述它的作用/应该做什么。不要用可能相关或不相关的其他功能来描述它。如果outerFunction预计返回一个数字，请对其进行描述。如果addTen也恰好返回一个数字，那么，多巧合啊。

我理解想要将一个函数的返回值隐式地与另一个函数的返回值联系起来的动机，因为这就是它的实际实现方式，而且你知道......干燥等等......但在这种情况下，这是适得其反的。在两个不同的函数上“重复”有关返回类型的“相同信息”并不重要；因为你没有描述一个相关的事物。这两个函数都是独立的黑匣子，有自己特定的签名；它们的实现恰好是耦合的，这与此无关，并且实际上可能明天就会改变。重要的是签名保持所描述的那样。

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