@returns with simmilar syntax to @param?

[StephenR]

Hi all,

I'm using JSDoc in a project to document a fairly substantial JS
library, and i've come across a small thing i'd like to be able to
document:

If a function or method returns an Object, how can I document what the
properties of that object will be (simmilar to if one of it's
arguments accepts an object)?

Cheers

Stephen

[Michael Mathews]

Hi Stephen,

(This is a frequent question, so I'll add it to the FAQ.)

You can use the @type tag in the doclet for your function to document
what the type of the thing being returned will be. For example:

/**
* @type Color
*/
function getColor() {
return new Color();
}

If you want to document what properties (and possibly methods, etc)
the returned thing will have, you have two options:

1) If it's simple, like it's an object literal with one or two
primative properties, you can just describe it, like so:

/**
* @returns {Object} A size object with members "w" and "h",
representing the width and height in pixels.
*/
function getSize() {
return {w: "100px", h: "100px"};
}

2) If it's any more complex than that, you should really have another
class, documented separately, like so:

/**
* @class
*/
function Color(rgbValue) {
/**
* The rgb value.
* @type String
*/
this. rgbValue = rgbValue;
}

/**
* @type Color
*/
function getColor() {
return new Color();
}

In the case of a complex return object, the latter method improves
your documentation but also improves the reusability and encapsulation
of your code elements, so is recommended.

However, if you really don't have the option of the second method, you
can accomplish the same thing purely in your documentation:
/**
* @name Color
* @class
* @property {String} rgbValue The rgb value.
*/
// Color is a "virtual class" for documentation purposes only,
// it isn't actually implemented.

/**
* @type Color
*/
function getColor() {
return {rgb: "220,20,60"}; // our virtual instance of the Color class
}

See:
http://code.google.com/p/jsdoc-toolkit/wiki/TagReturns
http://code.google.com/p/jsdoc-toolkit/wiki/TagType
http://code.google.com/p/jsdoc-toolkit/wiki/TagName
http://code.google.com/p/jsdoc-toolkit/wiki/TagProperty

Let me know if you have any further questions about that.

Regards,
Michael