What is the canonical pattern for exporting enums

2019-08-10 22:53发布

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

0条回答
登录 后发表回答