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

给出以下示例：

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

outsideFunction返回另一个函数的结果.

我想到了几种记录方法：

> @returns {number}-我们知道addTen返回一个数字,但是如果这个改变了怎么办？我们将不得不同时更新这两个更新(或每次返回时更新),这是无法维护的.
> @returns {function}-我不确定JsDoc是否可用.我在任何地方都找不到.这也不会让您获得太多信息.
> @returns {any}或-@returns {*}-这对阅读文档的人没有特别帮助.

由于上述原因,这些对我来说都不正确.

我想我想要类似的东西

@returns {addTen.return}

因此,我实际上是说“ outerFunction返回addTen所做的任何类型”.

注意：这些文件在此示例中位于同一位置,但可能包含在多个文件中,因此除非可以跨多个文件执行操作,否则使用this approach无效.

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

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

解决方法:

externalFunction的调用者将对该函数接受什么作为参数以及返回什么有一定的期望. externalFunction的调用者并不关心externalFunction的作用,只是它的接口按描述的那样工作. externalFunction的调用者不知道也不在乎,也不必在乎externalFunction所做的任何事情都涉及到名为addTen的函数.实际上,总有一天,您可能会重写outerFunction的整个实现,以不再调用addTen,而是使其行为保持完全相同.

将每个功能分别视为一个黑匣子.您正在描述externalFunction的接口,因此请描述它的功能/应该执行的操作.不要用可能相关或不相关的其他功能来描述它.如果期望externalFunction返回一个数字,则将其描述为数字.如果addTen也碰巧返回一个数字,那真是巧合.

我理解将一个函数的返回值隐式绑定到另一个函数的动力,因为那是它的实际实现方式,并且您知道… DRY和所有…但是在这种情况下适得其反.您可以在两个不同的函数上“重复”关于返回类型的“相同信息”,这并不重要.因为您不是在描述关联的事物.两种功能都是具有各自特定签名的独立黑匣子.它们的实现恰好是耦合的,与此无关紧要,实际上明天可能会改变.重要的是签名保持不变.

实际上,如果addTen确实更改了其返回类型(隐式地更改了externalFunction),那么无论如何这都将是一件大事,这不仅仅是通过隐式更新一些文档来解决.通过更改任何函数的返回类型,您正在破坏先前建立的合同,该合同将对该函数的每个用户产生一系列影响.在这种情况下,隐式自动更新outerFunction的返回类型是您的后顾之忧,因为您可能不得不重写大量代码以符合新合同.

标签：jsdoc,javascript,documentation
来源： https://codeday.me/bug/20191027/1941452.html