JS API文檔[，參數] VS [參數]

當閱讀各種API的文檔我注意到，有時一個函數的定義將被寫成這樣：JS API文檔[，參數] VS [參數]

jQuery.getJSON(url [, data ] [, success(data, textStatus, jqXHR) ])

，有時是這樣的：

jQuery.getJSON(url, [data], [success(data, textStatus, jqXHR)])

是否將括號內的逗號與括號外的含義不同？

來源

2014-03-26 Robby Allsopp

意思沒有區別。前者更爲正確，因爲如果傳遞參數，則只需要逗號（方括號表示方法簽名的可選部分）。 –

你有第二個例子嗎？第一個由'getJSON'使用。第二個可能意味着參數必須是一個數組，但我需要看一個具體的例子。 –

我不知道任何描述這種表示法的標準。如果確實沒有，則意義由創建文檔的開發人員定義。如果有這樣的標準，那麼這並不一定意味着開發人員遵循標準。 –

繼utility argument syntax公約和nested arguments像docopt，與位置參數的小轉移：

jQuery.getJSON(url [, data ] [, success(data, textStatus, jqXHR) ]) 
getjson url [--data=…] [--success=function]

這意味着，該參數可以省略，success回調可能出現在第二個地方。 $.getJSON(url),$.getJSON(url, {}),$.getJSON(url, function(){})和$.getJSON(url, {}, function(){})均爲有效。 API可以確定第二個參數是否爲data對象或第三個參數是否作爲第二個參數傳遞。

jQuery.getJSON(url, [data], [success(data, textStatus, jqXHR)]) 
getjson url --data[=…] --success[=function]

這意味着，參數值可以被省略，但success回調（如果表觀的）必須總是放在第三。所有的$.getJSON(url, undefined, undefined),$.getJSON(url, {}, undefined),$.getJSON(url, undefined, function(){})和$.getJSON(url, {}, function(){})都是有效的（儘管您當然可以忽略尾隨undefined）。

記錄可變參數的顯式方法是使用嵌套和替代方法，另請參見Documentation for optional parameters in JavaScript。

但是，如果不知道開發人員使用的文檔風格的標準或參考，我們永遠不會知道他的實際意圖。他可能也認爲他們是平等的。

來源

2014-03-26 17:14:47 Bergi

在解釋第二種語法時，是否提到了一些特定的文檔語料庫？例如。這是在jQuery文檔中使用？ –

如果這是真的，很高興知道！我將不得不測試它。我認爲jQuery幾乎總是使用前面的語法，爲了方便起見，我只爲後面的語法示例使用了相同的定義，但下面是實際文檔中後一種語法的示例：http：//api.highcharts。 com/highcharts＃圖表 –

不，這是我個人的解釋。實際上，它也可能意味着'data'是一個數組（就像'[data ...] would）： - 也許我會在通用的文檔指南中找到一個參考。 – Bergi

JS API文檔[，參數] VS [參數]

回答

相關問題