14

I'm writing my own library for the project at work for a browser application and I am having the same old problem deciding how to comment the code.

I'm trying to follow the JsDoc syntax, but will probably continue the Google Closure Compiler way. I may end up using two @return and @returns tags in the documentation, just for portability sake (when I setup the auto-generation of the documentation).

Now, the question, how do you document the return of a custom anonymous object from a function? For example:

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

JsDoc has an example of how a @param can be documented to expect object with certain fields, but not the @returns tag. Similarly, the Google Closure Compiler documentation of a Record Type is vague and has no example to work it out.

4

3 回答 3

15

闭包编译器使用JSDoc 注释的子集（并添加了一些自己的注释）。有关完整集，请参阅编译器的注释参考。JSDoc 注释类似于 JavaDoc 注释，是一个以/**（两颗星）开头的注释块。虽然注释的每一行通常都以它自己的开头，*但这是一个不需要的约定。每行只允许一个 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属性的匿名类型。其他有效的选项是在别处定义一个接口并将返回值类型转换为该接口。最不具体的注释是Objector *。

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

于 2012-06-20T12:02:29.020 回答
5

一种很好且可移植的方法如下所示，使用 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 中记录类型？

于 2013-08-23T19:04:36.307 回答
1

如果把它放在函数的顶部

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
    }
}
于 2012-06-20T10:21:08.233 回答