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

我正在尝试遵循JsDoc https://code.google.com/p/jsdoc-toolkit/w/list语法，但可能会继续谷歌闭包编译器 https://developers.google.com/closure/compiler/docs/js-for-compiler方式。我最终可能会在文档中使用两个 @return 和 @returns 标签，只是为了可移植性（当我设置文档的自动生成时）。

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

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

JsDoc 有一个示例，说明如何记录 @param 来期望具有某些字段的对象，但不包含 @returns 标记。同样，记录类型的 Google Closure Compiler 文档也很模糊，并且没有示例来解决它。

闭包编译器使用的一个子集JSDoc 注释 http://code.google.com/p/jsdoc-toolkit/（并添加了一些自己的）。请参阅编译器的注释参考 https://developers.google.com/closure/compiler/docs/js-for-compiler对于全套。 JSDoc 注释类似于 JavaDoc 注释，是一个注释块，开头为/**（两颗星）。虽然注释的每一行通常都以其自己的开头*，这是一个不需要的约定。每行只允许有一个 JSDoc 标记，但标记的参数可以跨越多行。

该注释通常适用于以下语句。这里有些例子：

Variable

/** @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 为复杂类型（包括联合和记录类型）添加别名。这些注释可能很长，但可以分为多行以提高可读性。

/** @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 and enabled特性。其他有效的选项是在其他地方定义一个接口并将返回值类型转换为该接口。最不具体的注释是Object or *.

要查看各种可能的注释，请查看编译器项目中的 extern 文件 http://code.google.com/p/closure-compiler/source/browse/#svn/trunk/contrib/externs.