Javascript 如何记录调用另一个函数的函数的返回值
给出以下示例:Javascript 如何记录调用另一个函数的函数的返回值,javascript,documentation,jsdoc,Javascript,Documentation,Jsdoc,给出以下示例: /** * 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
/**
* 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
返回另一个函数的结果
我想到了几种方法来记录这一点:
-我们知道@返回{number}
返回一个数字,但是如果这个数字改变了怎么办?我们必须同时更新这两个版本(或者每次返回时都要更新,这可能会非常多),这是不可维护的addTen
-我不确定这在JsDoc中是否可用。我到处都找不到。这也感觉不到它提供了多少信息@返回{function}
或-@returns{any}
-这对任何阅读文档的人都没有特别的帮助@returns{*}
@returns {addTen.return}
所以我基本上是说“outerFunction
返回addTen
所做的任何类型”
注意:在本例中,这些文件位于同一位置,但可能包含在多个文件中,因此使用不起作用,除非可以跨多个文件执行此操作
我们如何在函数返回另一个函数的文档中写入JsDoc注释
是否存在类似于我的建议的内容?outerFunction的调用方将对该函数接受的参数和返回的参数有一定的期望。
outerFunction
的调用者并不关心outerFunction
做了什么,只关心它的接口按照所描述的方式工作。outerFunction
的调用方不知道或不关心被调用的addTen
函数是否涉及outerFunction
所做的任何事情。事实上,有朝一日,您可能会重写outerFunction
的整个实现,不再调用addTen
,而是让它以完全相同的方式运行
将每个函数单独视为一个黑盒。您正在描述outerFunction
的接口,因此请描述它的功能。不要用可能相关或不相关的其他功能来描述它。如果期望outerFunction
返回一个数字,请将其描述为该数字。如果addTen
同时返回一个数字,那么,这真是巧合
我理解想要隐式地将一个函数的返回值与另一个函数的返回值联系起来的动机,因为它实际上就是这样实现的,你知道。。。干巴巴的。。。但在这种情况下,这是适得其反的。在两个不同的函数上“重复”关于返回类型的“相同信息”并不重要;因为你不是在描述一个相互关联的东西。这两个函数都是独立的黑匣子,具有自己的特定签名;它们的实现碰巧是耦合的,这与此无关,事实上明天可能会改变。重要的是,签名保持如所述
事实上,如果
addTen
确实改变了它的返回类型(而且outerFunction
也改变了它的返回类型),那将是一件大事,而不仅仅是隐式更新一些文档。通过更改任何函数的返回类型,您正在破坏先前建立的契约,这将对该函数的每个用户产生级联效应。在这种情况下,隐式自动更新outerFunction
的返回类型是您最不担心的,因为您可能需要重写大量代码以符合新合同。“outerFunction返回另一个函数”不,它没有。它返回调用另一个函数的结果,这完全是另一回事。从问题的剩余部分我想你知道,所以这不是一个答案,但是…啊,好的观点!我的问题仍然存在,虽然形式略有不同。。。我会编辑它。我仍然想知道如何正确地记录这一点。“我们知道,addTen
返回一个数字,但是如果这个数字发生了变化怎么办?我们必须同时更新两个(或多个),这是不可维护的。”嗯,outerFunction
与addTen
紧密绑定,因此,对addTen
的任何更改实际上都会影响到outerFunction
,它会对文档产生连锁反应,但更重要的是对其功能产生连锁反应。所以,您是说,当我更改addTen
的工作方式时,每次有任何东西返回它时,我也必须更改?我想我希望outerFunction
的文档引用addTen
。如果您希望outerFunction
的公共契约绑定到addTen
,而不仅仅是它的实现。