JSDoc: How do I document the "options" object literal for a parent "class"?
javascript, jsdoc
Solution
If I understand your question correctly, you have a function that takes an options object and you want to document all of its members?
A rough example of how to do that in JSDoc is as below:
/**
* @description
* Compliment someone on their something.
*
* @param {Object} options
* @param {String} options.name A person's name
* @param {String} options.feature A person's property
*/
function flatter (options) {
options = options || {};
console.log('%s, loving your %s!', options.name, options.feature);
}
Problem
I am using jQuery's `$.widget()` base "class" which provides an `option()` method. Since the method is not in my code, I don't have a place to document the argument. I tried to put jsDoc on the fields in the default options literal, but they're simply not picked up. Then I tried to use the `@class` and `@lends` tags on the same object literal, but this may be quite confusing as the object literal is not really a class. Another alternative I've experimented is to put something like `@param options.field description` in the constructor's jsDoc. However, this has the disadvantage of separating the documentation from the code. Also, the constructor don't actually have an argument called `options` as it's all handled by jQuery. How does you Javascript gurus handle this? Should a new tag be proposed?