Document the inline object syntax for @returns

[dandv]

http://usejsdoc.org/tags-returns.html doesn't specify how returned objects with constant keys can be documented, and there has been speculation about this on StackOverflow for 4+ years.

@return {{x:Number, y:Number}}

(moved here from jsdoc/jsdoc#1045)

[PhiLhoSoft]

The @return {{x:Number, y:Number}} syntax is fine for such simple example, with self-explaining key names. But it fails if the object is complex, and if we need to indicate optional properties, to document them, etc.
@typedef can be another solution, although perhaps a bit to much for a one-time object (not reused elsewhere).

I have seen indented @param to document properties of an object (instead of obj.prop), but I don't know if it is official. If so, perhaps it can be a solution after @return.

[cscott]

I've also seen (and used):

@return {Object}
@return {any} return.value The value of the attribute
@return {boolean} return.modified If the value has been changed
etc

That seems to work fine (although perhaps not in all themes?) and is consistent with other jsdoc-variants, such as jsduck: https://github.com/senchalabs/jsduck/wiki/%40return