How to document return in JavaScript

Question

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.

Accepted Answer

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.

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

Variable

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

Type Cast

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

note the extra parenthesis

Named Function

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

Function Expressions

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

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

Typedef

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 {{
 *             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 `*`.

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

How to document return in JavaScript

Solution

Problem

Related problems