關於記錄JavaScript的問題：JS類型

Question

考慮到我將來會與一個更大的團隊合作，我正在嘗試自學一些前端語言的基本注釋和文檔原則。 目前我正在研究JS。

在大多數情況下，我使用Google的風格指南作為首選，但我仍然有一些問題。

假設我有一個像這樣的ajax函數：

function initFunction(src, wrapper) {
  $.getJSON(src, {
    format: "json"
  }).done(function(data) {
    var wrapper = $(wrapper),
      contents = callAnotherFunction($(data)[0]);

    // Populates the wrapper element.
    wrapper.append(contents );

  }).fail(function(jqXHR, textStatus, errorThrown) {
    alert(textStatus + ": " + errorThrown);
  });
}

該函數有兩個@ @param ，src和wrapper。 這是一些問題。

然后，callAnotherFunction（）將Object作為參數，它應該返回一些HTML。

1. 什么是src的類型？ 考慮到它是JSON， {Object} ？
2. 什么是包裝類型？ 考慮到它是一個諸如"#myId"之類的值，String？
3. 這個函數的返回類型是什么？ 這是一個無效函數，但我不知道我稱之為返回類型 。 它會返回null嗎？
4. 你可以附加到元素的HTML類型是什么？ 它是一個String ？
5. 顯示所有這些的JSDoc約定是什么？ 像這樣的東西？

/** * This is a description of this function. It gets a JSON file, uses it as * a jQuery object, and then call another function with the new data. * @param {Object} src JSON file to parse. * @param {String} wrapper HTML element to use as a wrapper for the output. * @return {Null} */

Answer 1

1. 參數的類型與它所代表的內容無關，而是參數的JavaScript類型。 在你的情況下， src是一個包含url的字符串（檢索url並不重要，檢索JSON），因此類型是字符串。 更多信息在這里 。
2. 是的，這是一個字符串。
3. 如果函數沒有返回值，請不要在JSDoc中提及它。
4. 根據JQuery文檔，它是：

鍵入：htmlString或Element或Array或jQuery

DOM元素，元素數組，HTML字符串或要在匹配元素集中的每個元素末尾插入的jQuery對象。

因此，這取決於您想要將您的功能記錄為接受的內容。 如果要將其記錄為接受多種類型，請使用括號和| 角色 （下面的例子）。

5. 關閉，但您不需要返回類型。 有些人還在描述和參數之間加了一個空行，但解析器並不需要這樣做。

    /** * This is a description of this function. It gets a JSON file, uses it as * a jQuery object, and then call another function with the new data. * * @param {Object} src JSON file to parse. * @param {(String|jQuery|DOMElement)} wrapper HTML element to use as a wrapper for the output. */ function initFunction(src, wrapper) { // ... 

   在上面，我們已經指出wrapper可以是字符串，jQuery對象或DOMElement。 我們沒有深入了解它可能是一個數組，也不知道字符串是選擇器還是HTML片段。 描述需要處理。 有很多選擇，你可能不得不依賴{*} 。

   如果解析器可能無法判斷這是否是函數，那么您還要添加@function標記 ：

    /** * This is a description of this function. It gets a JSON file, uses it as * a jQuery object, and then call another function with the new data. * * @function * * @param {Object} src JSON file to parse. * @param {(String|jQuery|DOMElement)} wrapper HTML element to use as a wrapper for the output. */ var initFunction = function(src, wrapper) { // ... 

   根據上下文，您可能更喜歡@method到@function （他們是同義詞）。

Answer 2

正如Emanuele已經說過的那樣，第一個參數只能是一個字符串，它代表一個URL。

但是，第二個參數（包裝器）可以是string或DOM element 。 不只是一個字符串。

我不知道你怎么能指示JSDoc變量可能有兩種不同的類型。

Answer 3

首先，您應該使用jQuery JSDoc extern文件。
相應地注釋函數，由於jQuery extern文件，函數以這種方式注釋。

/**
* @param  {!string} src
* @param {(jQuerySelector|Element|Object|Array<Element>|jQuery|string|function())=} wrapper 
*/
function initFunction(src, wrapper) {
    $.getJSON(src, {
       format: "json"
    }).done(function(data) {
        var wrapper = $(wrapper),
            contents = callAnotherFunction($(data)[0]);

       // Populates the wrapper element.
       wrapper.append(contents);

    }).fail(function(jqXHR, textStatus, errorThrown) {
       alert(textStatus + ": " + errorThrown);
    });
}

/**
* @param {!Object} obj
* @return {(string|Element|Array<Element>|jQuery|function(number,string))}
*/
function callAnotherFunction(obj) {
     .
     .
     .
}

Answer 4

我通常做的最小功能文檔是：

/**
 Purpose:  state the purpose of the function
 parameters:
  src: string, required: the url to the api service.  [paramName: type, option: purpose.
 {list individual parameters}
 Assumption: describe any dependencies. Any callback, etc.
 Return: string, json format.
*/
function foo(src, param) {}

把自己放在別人的鞋子里。 在嘗試對某人的代碼進行任何更改之前，您需要快速了解什么。