如何在JavaScript中记录返回

Question

我正在为浏览器应用程序的工作编写自己的库,我遇到了同样的问题,决定如何评论代码.

我正在尝试遵循JsDoc语法,但可能会继续使用Google Closure Compiler方式.我可能最终在文档中使用了两个@return和@returns标签,只是为了便携(当我设置文档的自动生成时).

现在,问题是,如何记录函数中自定义匿名对象的返回？例如:

return {
    username: 'username',
    password: 'password',
    enabled:  true
};

JsDoc有一个示例,说明如何记录@param以期望具有某些字段的对象,而不是@returns标记.同样,Google Closure Compiler记录类型的文档也很模糊,没有示例可以解决.

Answer 1

Closure-compiler使用JSDoc注释的一个子集(并添加了一些自己的注释).请参阅完整集的编译器的注释参考.JSDoc注释类似于JavaDoc注释,是一个以/**(两颗星)开头的注释块.虽然评论的每一行通常都是以它自己开头的*,但这是一种不需要的约定.每行只允许一个JSDoc标记,但标记的参数可以跨越多行.

注释通常适用于以下语句.这里有些例子:

变量

/** @type {string} */ var a;

输入Cast

var b = /** @type {string} */ (window['foo']);

注意额外的括号

命名功能

/**
 * @param {string} bar
 * @return {boolean}
 */
function foo(bar) { return true; }

功能表达

/** @type {function(string):boolean} */
var foo = function(bar) { return true; }

var foo2 =
  /**
   * @param {string} bar
   * @return {boolean}
   */
  function(bar) { return true; }

的typedef

为了方便和使用typedef的可维护性,可以为复杂类型(包括联合和记录类型)设置别名.这些注释可能很长,但可以分成多行以便于阅读.

/** @typedef {{
 *             foo:string,
 *             bar:number,
 *             foobar:number|string
 *           }}
 */
var mytype;

对于您的原始示例,有几种可能的方法来注释这样的函数返回值.其中一个最具体但仍然方便的是记录类型:

/** @return {{username:string, password:string, enabled:boolean}} */
function() {
  return {
    username: 'username',
    password: 'password',
    enabled:  true
  }
}

请注意额外的{}.另请注意,记录类型不会阻止属性重命名.

该注解告诉该函数返回一个匿名类型与编译器username,password和enabled属性.其他有效选项是在其他地方定义接口,并将返回值强制转换为该接口.最不具体的注释将是Object或*.

要查看各种可能的注释,请查看Compiler项目中的extern文件.

Answer 2

一种很好且可移植的方法如下所示，使用 return 作为关键字。https://github.com/senchalabs/jsduck/wiki/%40return

/**
 * @return {object} return An object with the following properties
 * @return {string} return.username Some username
 * @return {string} return.password Some password
 * @return {boolean} return.enabled Is the user enabled?
 */
function getObj () {
     return {
         username: 'username',
         password: 'password',
         enabled:  true
      };
}

如果你必须在多个地方使用它，你将不得不复制它，或者使用@typedef，但我还没有想出如何添加评论，@typedef所以我使用类似以下的东西

/**
 * @typedef {username:string, password:string, enabled:boolean} MyType
 *  
 *  username: The name of the user 
 *  password: Some password
 *  enabled: Is the user enabled?
 */

/**
 * @return {MyType}
 */
function getObj () {
     return {
         username: 'username',
         password: 'password',
         enabled:  true
      };
}

您也可以尝试这里的建议如何仅使用 jsdoc 在 webstorm 中记录类型？

Answer 3

如果把它放在函数的顶部

function myFunction() {
    /**
     * Description of my function
     * @return {!Object.<string, string|boolean>} Returns an object containing username, password and enabled information
     */

    // Do stuff
    return {
        username: 'username',
        password: 'password',
        enabled:  true
    }
}