Syntax for parameters with properties

[nene]

Having Markdown support already alleviates this issue, but it would be nice to have a special syntax for this.

One possibility is to adopt the same syntax that jsdoc-toolkit supports:

/**
  * @param userInfo Information about the user.
  * @param userInfo.name The name of the user.
  * @param userInfo.email The email of the user.
  */
 function logIn(userInfo) {
        doLogIn(userInfo.name, userInfo.email);
 }

Another option I've been thinking is to re-use @cfg:

/**
  * @param userInfo Information about the user.
  * @cfg name The name of the user.
  * @cfg email The email of the user.
  */
 function logIn(userInfo) {
        doLogIn(userInfo.name, userInfo.email);
 }

This greatly reduces the amount of duplication. If the function accepts only one parameter (as such functions often do), maybe we could even skip the @param completely:

/**
  * @cfg name The name of the user.
  * @cfg email The email of the user.
  */
 function logIn(userInfo) {
        doLogIn(userInfo.name, userInfo.email);
 }

The only downside is that when you have just one @cfg then the doc-comment will be interpreted as class-level config option, but having a function parameter object with just one possible property is a bit silly and one can always force parsing doc-comment as method doc-comment by using @method.

The best would be to support both syntaxes.

[nene]

Thinking of taking the jsdoc-toolkit-style approach:

/**
 * @cfg {Function} handler A callback that gets passed the following parameters:
 * @cfg {Object} handler.userInfo A userinfo object:
 * @cfg {String} handler.userInfo.name The name of the user.
 * @cfg {String} handler.userInfo.email The email of the user.
 */
handler: Ext.emptyFn,

Same thing with method parameters:

/**
 * @param {Function} handler A callback that gets passed the following parameters:
 * @param {Object} handler.userInfo A userinfo object:
 * @param {String} handler.userInfo.name The name of the user.
 * @param {String} handler.userInfo.email The email of the user.
 * @param {Object} scope Scope for the callback.
 */
doSomething: function(handler, scope) {
},

The main question is how to document the return value of the function. We could simply treat the name "return" specially:

/**
 * @cfg {Function} handler A callback that gets passed the following parameters:
 * @cfg {String} handler.return The formatted value
 */
handler: Ext.emptyFn,

This shouldn't cause any conflicts because "return" is a reserved keyword and you can't use it as function parameter name.

[nene]

Finally, this is now implemented.