JSDoc shortcomings

[tmcw]

We know of a few JSDoc oddities with no clear solution. Let's keep track of them here.

• Overloaded functions Ideas for flexible formatting tmcw-up-for-adoption/doxme#10 (comment)

[tmcw]

• Documenting input object types: the tradition is multiple param tags with foo.bar - we need to support that fully.

[shawnbot]

I think this might be one: it seems really difficult to use JSDoc for d3-style functions that return configurable functions with attached methods. I've tried every combination of @memberof!, @instance and similar tags with no success. Something like this:

/**
 * an area chart generator
 * @class area
 */
var area = function() {
  /** @lends area# */
  var chart = function(selection) { };
  /** @method */
  chart.data = function(_) { };
  return chart;
};

Is @class just a bad fit for these or what?

[tmcw]

@shawnbot yeah: I don't think that the @class tag describes the object factory idea very well:

/**
 * area chart generator
 * @returns {chart}
 */
var area = function() {

  /**
   * Run a chart over a given selection
   * @param {Selection} selection
   */
  var chart = function(selection) {
  };

  /**
   * Sets the chart data.
   */
  chart.data = function(_) {
  };

  return chart;
};

This works perfectly fine in my testing - differentiating the factory function from the thing that it returns.

[shawnbot]

Nice, good call @tmcw.

[shawnbot]

Well, actually, not quite: I can't get the method (chart.data) to nest under the chart definition in the docs. It just goes into the main listing without a namespace. That's actually why I tried to do it with @class: I assumed you couldn't attach methods to functions any other way.

[tmcw]

Odd: it does so with my install, I'll test this again...

[mister-walter]

@shawnbot , did you ever get something working? @tmcw 's example doesn't compile right for me at all, it doesn't generate a class definition for 'chart'. I'm not sure if I'm not doing something right, or if JsDoc has changed its behavior.

[shawnbot]

Nope, sorry @mister-walter. I haven't used jsdoc in a while, so I don't have anything handy to test with. 😕

[tmcw]

Filing - upstream issue with JSDoc about the uncertain meaning and usage of @inner

[tmcw]

Moving discussion to dx-spec https://github.com/tmcw/dx-spec/issues