1

我想知道使用 require 和 jsdoc 从 JavaScript 模块导出枚举的规范模式。现有的示例和问题似乎只考虑本地私有枚举。我的目标是尽我所能拥有最优质的文档和智能感知/代码完成。

这是我目前最好的尝试：

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;

这里有一些细节导致我采用这种方法：

  1. 高度是枚举。它是静态的。
  2. Object.freeze 似乎是最佳实践。
  3. 执行 LawnMower.heights = Object.freeze(...) 会阻止 Visual Studio 的智能感知工作。因此，我分两步进行。
  4. 添加了@readonly，虽然我认为它没有任何作用
  5. mow() 函数引用了 LawnMower.height，但似乎没有任何工具对它有太大作用。

我们的团队正在使用 Visual Studio、Ace+Tern 和 Atom。使用上面的模式，当我们编写这样的代码时：

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

希望智能感知能够显示参数名称、类型和描述。如果填写“LawnMower.heights”，则可加分。为我们。（Visual Studio 为 C# 执行此操作）。

结果：

  • Atom 似乎在这里完全忽略了@param。
  • Visual Studio 告诉我们参数是高度，但没有提供类型或描述。
  • Ace/Tern 显示高度的 @jsdoc 注释行。

具体问题：我是否正确编写了@param 行？我相信名称路径“LawnMower.heights”是指代 LawnMower 的静态成员的正确方法。

参考：

  1. 如何用有限的可能值在 jsdoc 中记录字符串类型
  2. 枚举作为 JSDoc 中的 @param 类型
  3. 如何记录接受一组预定义值的参数？
  4. http://usejsdoc.org/tags-enum.html
  5. http://usejsdoc.org/about-namepaths.html
4

0 回答 0