如何記錄的函數調用另一個函數

考慮下面的例子返回值：如何記錄的函數調用另一個函數

/** 
* 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註釋來記錄函數返回另一個函數？

是否存在類似於我的建議的內容？

來源

2016-05-10 Matt Lishman

*「'outerFunction'返回另一個函數」*不，它不。它返回調用另一個函數的* result *，這完全是另一回事。從問題的其餘部分我想你知道，所以這不是一個答案，但... –

啊，好點！我的問題依然存在，雖然格式略有不同，但我會編輯它。我仍然想知道如何正確記錄這一點。 –

*「我們知道'addTen'返回一個數字，但是如果這個變化呢？我們將不得不更新兩個（或多個），這是不可維護的。」*好吧，'outerFunction'緊緊地綁定到'addTen' ，所以對addTen的任何修改的確會影響'outerFunction'，它對文檔有影響，但對其功能更重要。 –

outerFunction的調用者將對該函數接受哪些參數以及返回結果有一定的期望。 outerFunction的調用者並不在意outerFunction的作用，只是它的接口按所述方式工作。 outerFunction的調用者不知道或不在意，也不應該在乎某個函數addTen涉及outerFunction所做的任何事情。實際上，總有一天您可能會重寫outerFunction的所有實現，而不再調用addTen，但請保持其行爲完全相同。

將每個功能分別視爲黑匣子。您正在描述outerFunction的界面，因此請描述它做了什麼/應該做什麼。不要用可能相關或不相關的其他函數來描述它。如果outerFunction預計會返回一個數字，請如此描述。如果addTen也恰好返回一個數字，那麼這是多麼巧合。

我明白想要隱含地將一個函數的返回值與另一個函數的返回值聯繫起來的動力，因爲這就是它實際上的實現方式，而且您知道...... DRY和所有...但在這種情況下，。關於兩種不同功能的返回類型「重複」「相同信息」並不重要;因爲你沒有描述相關的事物。這兩個函數都是獨立的黑盒子，有自己的特定簽名;他們的實施恰恰是相互關聯的，並且實際上可能會在明天改變。重要的是簽名保持如上所述。

事實上，如果addTen確實改變了它的返回類型（並且隱含地改變了outerFunction），那麼這將是一個大問題，不僅僅是通過隱式地更新一些文檔而被打亂。通過更改任意函數的返回類型，您打破了先前建立的合同，該合同將對該函數的每個用戶產生級聯效果。隱式和自動更新outerFunction的返回類型是您在這種情況下最擔心的問題，因爲您可能不得不重寫大量代碼以符合新合同。

來源

2016-05-11 02:00:30 deceze

如何記錄的函數調用另一個函數

回答

相關問題