如何用JavaScript记录返回-HowtodocumentreturninJavaScript

13  

The Closure-compiler uses a subset of the JSDoc annotations (and adds a few of its own). See the annotation reference for the compiler for the complete set. A JSDoc annotation is similar to a JavaDoc annotation and is a comment block that begins with /** (two stars). While each line of the comment often begins with it's own *, that is a convention that is not required. Only one JSDoc tag is allowed per line, but the arguments for a tag can span multiple lines.

Closure-compiler使用JSDoc注释的一个子集(并添加一些自己的注释)。查看完整集的编译器的注释引用。一个JSDoc注释类似于JavaDoc注释，是一个以/**(两颗星)开头的注释块。尽管注释的每一行通常以它自己的*开头，但这是一个不需要的约定。每行只允许有一个JSDoc标记，但是标记的参数可以跨多行。

The annotation typically applies to the following statement. Here are some examples:

注释通常应用于以下语句。下面是一些例子:

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

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

note the extra parenthesis

注意额外的括号

/**
 * @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; }

Complex types (including unions, and record types) can be aliased for convenience and maintainability using a typedef. These annotations can be long, but can be split over multiple lines for readability.

使用typedef可以为方便和可维护性提供复杂类型(包括工会和记录类型)。这些注释可以很长，但是为了可读性，可以在多行中进行分割。

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

For your original example, there are several possible ways to annotate such a function return value. One of the most specific and still convenient is the record type:

对于您的原始示例，有几种可能的方法来注释该函数的返回值。其中最具体也是最方便的是记录类型:

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

Note the extra {}. Also keep in mind that record types will not prevent property renaming.

注意额外的{ }。还要记住，记录类型不会阻止属性重命名。

This annotation tells the compiler that the function returns an anonymous type with username, password and enabled properties. Other valid options would be to define an interface elsewhere and typecast the return value to be that interface. The least specific annotation would be Object or *.

该注释告诉编译器该函数返回带有用户名、密码和启用属性的匿名类型。其他有效的选项是在其他地方定义接口，并将返回值类型转换为该接口。最不特定的注释将是Object或*。

To see a wide range of possible annotations, take a look at the extern files in the Compiler project.

要查看大量可能的注释，请查看编译器项目中的外部文件。

3  

One of the nice and portable ways to do it is like the following, using return as a keyword. https://github.com/senchalabs/jsduck/wiki/%40return

一种很好的、可移植的方法是使用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
      };
}

If you have to use it in multiple places, you would have to duplicate it, or use @typedef, but I haven't figured out how to add comments to @typedef so I use something like the following

如果必须在多个地方使用它，就必须复制它，或者使用@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
      };
}

You can also try the suggestion here How can I document a type in webstorm using just jsdoc?

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

1  

If put this in top of the function

如果把它放在函数的上面。

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

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