1

I want to know the canonical pattern for exporting enums from a JavaScript module using require and jsdoc. Existing examples and questions seem to only consider local private enums. My goal is to have the best quality documentation and intellisense/code completion I can.

Here is my current best attempt:

var LawnMower = function () {
};

/**
* Enums for the valid heights to mow
* @readonly
* @enum {number}
*/
LawnMower.heights = {
    Low: 0,
    Medium: 1,
    High: 2
};

// Doing this separately from above, or Visual Studio's intellisense won't recognize it as an enum :-(
LawnMower.heights = Object.freeze(LawnMower.heights);

/*
 * @param {LawnMower.heights} height - The height of the deck on the mower
 */
LawnMower.prototype.mow = function (height) {};

module.exports = LawnMower;

There are some particulars here that led me to this approach:

  1. heights is the enum. It is static.
  2. Object.freeze seems to be best practice.
  3. Doing LawnMower.heights = Object.freeze(...) prevents Visual Studio's intellisense from working. Hence, I do it in two steps.
  4. Added @readonly, although I don't think it does anything
  5. The mow() function references LawnMower.height, but none of the tools seem to do much with it.

Our team is using Visual Studio, Ace+Tern, and Atom. With the above pattern, when the we write code like this:

var lm = new LawnMower();
lm.mow(

The hope is that intellisense will show the parameter name, the type, and the description. Bonus points if it fills in "LawnMower.heights." for us. (Visual Studio does this for C#).

Results:

  • Atom seems to ignore @param completely here.
  • Visual Studio tells us the argument is height but provides no type or description.
  • Ace/Tern displays @jsdoc comment line for height.

Specific question: Did I write the @param line correctly? I believe the namepath "LawnMower.heights" is the correct way to refer to a static member of LawnMower.

References:

  1. How to document a string type in jsdoc with limited possible values
  2. Enum as @param type in JSDoc
  3. How to document a parameter that accepts a predefined set of values?
  4. http://usejsdoc.org/tags-enum.html
  5. http://usejsdoc.org/about-namepaths.html
Community
  • 1
  • 1
Moby Disk
  • 3,761
  • 1
  • 19
  • 38
  • Would this be better for codereview.stackexchange.com? – Moby Disk Sep 17 '15 at 20:56
  • If I understand your need : Ace/Tern works (it displays comment line height) for Atom if you use https://github.com/tststs/atom-ternjs I suggest you that you create an issue to suuport that (ternjs support that, because it works with Ace). And for "Bonus points if it fills in "LawnMower.heights." for us. " you mean that when you choose mow in the completion, it should generate mow(height) and display a second list with LawnMower.heights.Low, LawnMower.heights.Medium? – Angelo Sep 18 '15 at 12:16
  • @Angelo I didnt know atom used tern, whoops! yes to your question about mow completion. Does anything do that for javascript? – Moby Disk Sep 18 '15 at 12:30
  • I have created an issue for tern https://github.com/marijnh/tern/issues/644 if it is implemented, I could support completion and validation for @enum – Angelo Sep 22 '15 at 09:06

0 Answers0