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所做的任何类型”。

注意：这些在这个示例中位于相同位置，但可以包含在多个文件中，因此使用this approach不起作用，除非可以在多个文件中执行此操作文件。

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

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

Answer 1

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

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

我理解想要隐含地将一个函数的返回值与另一个函数的返回值联系起来的动力，因为它实际上是如何实现的，并且你知道... DRY和所有......但在这种情况下，这会产生反作用。你重复＆＃34;重要的事情并不重要。＆＃34;相同的信息＆＃34;关于两个不同功能的返回类型;因为你没有描述连接的东西。这两个功能都是独立的黑盒子，有自己特定的签名;它们的实现恰好是耦合的，与此无关，事实上可能明天改变。重要的是签名保持如上所述。

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

如何记录调用另一个函数

1 个答案: