JSDoc 和 JavaScript 属性获取器和设置器答案

【问题标题】：JSDoc and JavaScript property getters and settersJSDoc 和 JavaScript 属性获取器和设置器
【发布时间】：2014-06-19 07:03:51
【问题描述】：

我希望我的代码（如下所示）可以使用 JSDoc(v2.4.0) 生成描述对象文字的每个属性的文档，但它不起作用。有谁知道如何使用 JSDoc 从使用 getter/setter 的代码生成文档？

/** Enum of days of week. */
var Day = {
    /** Sunday. */
    get Sun() { return 0; },
    /** Monday. */
    get Mon() { return 1; },
    /** Thuesday. */
    get Tue() { return 2; },
    /** Wednesday. */
    get Wed() { return 3; },
    /** Thursday. */
    get Thu() { return 4; },
    /** Friday. */
    get Fri() { return 5; },
    /** Saturday. */
    get Sat() { return 6; }
}

【问题讨论】：

标签： javascript getter-setter jsdoc

【解决方案1】：

使用 @type 记录 JavaScript get 和 set 访问器。像下面这样的东西应该适用于 JSDoc：

    /**
     * Sunday.
     * @type {number}
     */
    get "Sun"() { return 0; },
    /**
     * Monday.
     * @type {number}
     */
    get "Mon"() { return 1; },

这会将每个属性记录为具有number 类型的成员。

【讨论】：

解决了过度急切类型的警告，例如Argument type {get: (function(): number)} is not assignable to parameter type number

【解决方案2】：

您可以使用 jQuery 样式的 getter / setter 方法：

/**
 * Get colour of object
 * @returns {mixed}
 *//**
 * Set colour of object
 * @param {mixed} val
 * @returns {this}
 */
colour: function(val) {
    if (val === undefined)
       return this.colour;
    else {
       this.colour = val;
       return this;
    }
}

我刚刚与迈克尔本人讨论了这个问题。由于一个非常酷的特性，在 jsDoc3 (https://github.com/micmath/jsdoc) 中是可能的。可以堆叠多个文档块（一个用于getter，一个用于setter）：

http://groups.google.com/group/jsdoc-users/browse_thread/thread/d4c7794bc8f6648e/94df7339e1fc4c91#94df7339e1fc4c91

【讨论】：

这里演示的语法是 ES5 语法，现在它是完全标准的，完全不是特定于实现的。至于 get/set 不是关键字，在这里查看它们的正确方法是它们是 contextual 关键字。如果get 后面的标记是冒号，则它是一个数据属性。如果get 后面的标记是名称，则它是访问器属性。（当然，set 也是如此。）
@Jeff 这是一个有趣的注释。我玩过，这种语法似乎在 ie9、ff3.5、chrome15 和 node 中运行良好，但显然不适用于较旧的 IE。我已经阅读了 ES5 defineProperty（在 IE8+ 中工作），但我没有遇到 ES5 规范中的对象文字语法。我已经更新了我的答案。
@Jeff 作为一个附带问题，你知道是否可以定义一个落入式Object.defineProperty 函数来提供 IE6-IE7 中最基本的 getter/setter 功能？跨度>
@Jeff 我已经玩过了，这是我想出的支持早期版本的 FF、Chrome 但仍然坚持使用 IE9+ (jsfiddle.net/SZuyq)
您可以定义一个提供“最多”功能的功能，但这实际上取决于您如何定义“最多”。 Object.defineProperty 还可以更改属性的可配置性（是否可以粗略地删除）及其可枚举性（是否显示在for-in 循环中）。如果没有Object.defineProperty，这些（数据属性的可写性）都不能更改。因此，我通常建议人们不要半实施Object.defineProperty，因为不幸的是，不可能正确处理细微差别。