关于记录 JavaScript 的问题：JS 类型

Question

考虑到我将来要和一个更大的团队一起工作，我正在尝试自学一些前端语言的基本注释和文档原则。目前我正在研究 JS。

在大多数情况下，我使用 Google's Style Guide 作为首选，但我仍然有一些问题。

假设我有一个像这样的 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()，然后，将对象作为参数，它应该 return 一些 HTML.

src 的类型是什么？考虑到它是 JSON、{Object}?
包装器的类型是什么？考虑到它是一个值，例如 "#myId"、String?
这个函数的 return 类型是什么？这是一个 void 函数，但我不知道如何称呼它的 return type。 return 是否为空？
可以附加到元素的 HTML 的类型是什么？是String吗？
显示所有这些内容的 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

参数的类型与它所代表的内容无关，而是JavaScript参数的类型。在您的情况下，src 是一个包含 url 的字符串（检索 url 与检索 JSON 无关紧要），因此类型为字符串。更多信息 here.
是的，它是一个字符串。
如果函数没有 return 值，请不要在 JSDoc 中提及它。
根据 JQuery documentation 是：

Type: htmlString or Element or Array or jQuery

DOM element, array of elements, HTML string, or jQuery object to insert at the end of each element in the set of matched elements.

所以这取决于您要将您的函数记录为接受的内容。如果您想将其记录为接受多种类型，您 use parentheses and the | character（下面的示例）。

关闭，但您不想要 return 类型。有些人还在描述和参数之间放了一个空行，但解析器不需要这样做。

/**
 * 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 tag:

/**
 * 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 外部文件。

/**
* @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) {}

设身处地为别人着想。在尝试对某人的代码进行任何更改之前，您需要快速了解什么。

关于记录 JavaScript 的问题：JS 类型

Questions on documenting JavaScript: JS types

javascript

naming-conventions

conventions