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和包装器。这是一些问题。

callAnotherFunction（）然后将Object作为参数，它应返回一些HTML。

src的类型是什么？考虑到它的JSON，{Object}？
什么是包装的类型？考虑到它的值是"#myId"，String？
这个函数的返回类型是什么？它是一个无效功能，但我不知道我将其称为返回类型。它会返回null吗？
您可以附加到元素的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。
是的，这是一个字符串。
如果函数没有返回值，请不要在JSDoc中提及它。
根据JQuery documentation，它是：

键入：htmlString或Element或Array或jQuery

要在匹配元素集中的每个元素末尾插入的DOM元素，元素数组，HTML字符串或jQuery对象。

因此，这取决于您希望将您的功能记录为接受的内容。如果您想将其记录为接受多种类型，请use parentheses and the | character（示例如下）。

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

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

把自己放在别人的鞋子里。在尝试对某人的代码进行任何更改之前，您需要快速了解什么。

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

4 个答案: