javascript - 如何在 JavaScript 中记录返回值

Question

我正在为浏览器应用程序的工作项目编写自己的库，但我在决定如何注释代码时遇到了同样的老问题。

我正在尝试关注 JsDoc语法，但可能会继续 Google Closure Compiler方法。我可能最终会在文档中使用两个 @return 和 @returns 标签，只是为了可移植性(当我设置文档的自动生成时)。

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

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

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

Answer 1

Closure 编译器使用 JSDoc annotations 的一个子集(并添加了一些自己的)。查看annotation reference for the compiler对于完整的集合。 JSDoc注解类似于JavaDoc注解，是以/**(两颗星)开头的注释 block 。虽然注释的每一行通常都以它自己的 * 开头，但这并不是必需的约定。每行只允许一个 JSDoc 标记，但标记的参数可以跨越多行。

注释通常适用于以下语句。以下是一些示例:

变量

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

类型转换

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 {{
 *             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 属性。其他有效的选择是在别处定义一个接口(interface)并将返回值强制转换为该接口(interface)。最不具体的注释是 Object 或 *。

要查看范围广泛的可能注释，请查看 extern files in the Compiler project .