标签：jsdoc javascript documentation
给出以下示例：
/**
* 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
本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享； 2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关； 3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关； 4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除； 5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。