47

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?

alex
  • 479,566
  • 201
  • 878
  • 984
billc.cn
  • 7,187
  • 3
  • 39
  • 79
  • 2
    Your question sounds very similar to this one: http://stackoverflow.com/questions/6460604/how-to-describe-object-arguments-in-jsdoc – Levi Hackwith Jun 09 '12 at 22:13
  • @LeviHackwith Yes, it is similar, but as I have described in the question it iself, I don't have a place where I can use the @param tag because the jQuery guys have implemented all the boiler plate code (including the `options()` function where the @param tag would normally be used.) – billc.cn Jun 14 '12 at 21:54
  • 1
    [`/** @param {Object.} options */`](http://code.google.com/p/closure-compiler/source/browse/trunk/contrib/externs/jquery-1.7.js) seems to be one way to do it. – Paul Sweatte Aug 23 '12 at 19:26
  • I do not think this is a duplicate to the linked question as this is specific to jQuery Widgets. I have the same problem and have reasoned that since the options are usually (at least in our case) specified when instantiating the widget, I put the @param {Object} [options] as seen in the answer below at the widget declaration $.widget("myWidget", { ... }) – d4kris Nov 16 '16 at 16:41

1 Answers1

103

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);
}
Dan Dascalescu
  • 143,271
  • 52
  • 317
  • 404
Jamie Mason
  • 4,159
  • 2
  • 32
  • 42
  • Is it possible to document a property that has a space in it, e.g. `options['some property']`? – M Miller Dec 15 '14 at 19:35
  • Not something I've tried, try a couple of variations of quoting the value and run the jsdoc generator to see. Please let us all know after. – Jamie Mason Dec 20 '14 at 11:04
  • Well since this question kept get bumped, I'll just clarify here: this is not the answer for my specific quesiton because as I've said, jQuery provides the "option" method so I do not have a method where the options literal is the argument. – billc.cn Dec 22 '14 at 21:27
  • 5
    @fold_left do we actually need @description? Never saw it being used. When I see it it is assumed that the first line is the description. – pcatre Jan 23 '15 at 15:27
  • 2
    You're right about that @pcatre, I tend to use it anyway because it suits my preference but it can be omitted without issue. – Jamie Mason Jan 23 '15 at 19:05