JSDoc和JavaScript属性的getter和setter函数

Question

我希望我的代码（类似下面的代码）可以使用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; }
}

- enobufs

Answer 1

使用@type来记录JavaScript的get和set存取器。以下类似的内容应该适用于JSDoc：

使用@type来记录JavaScript的get和set存取器。以下类似的内容应该适用于JSDoc：

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

这份文档将每个属性都作为一个成员，类型为number。

- jackvsworld

---

解决了过于热心的类型警告，例如“参数类型{get: (function(): number)}不可分配给参数类型number”。 - Bob Stein

Answer 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;
    }
}

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

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

- Lea Hayes

---

那里展示的语法是ES5语法，现在已经完全标准化，不再是特定于实现的。至于get/set不是关键字，这里正确的看法是它们是上下文关键字。如果跟在get后面的令牌是冒号，那么它就是数据属性。如果跟在get后面的令牌是名称，那么它就是访问器属性。（当然，对于set也是一样的。） - Jeff Walden

@Jeff，这是一个有趣的笔记。我已经试过了，这个语法在ie9、ff3.5、chrome15和node中运行得非常好，但显然在旧版IE中不行。我已经阅读了关于ES5 defineProperty的内容（它在IE8+中有效），但我没有在ES5规范中找到对象字面量语法。我稍微更新了我的答案。 - Lea Hayes

@Jeff 顺便问一下，你知道在 IE6-IE7 中是否可以定义一个 fall-in 的 Object.defineProperty 函数来提供最基本的 getter/setter 功能吗？ - Lea Hayes

@Jeff，我已经试了一下，这是我为支持早期版本的FF、Chrome所想出来的方法，但仍然无法支持IE9+（http://jsfiddle.net/SZuyq/）。 - Lea Hayes

你可以定义一个提供“大多数”功能的对象，但这实际上取决于你如何定义“大多数”。Object.defineProperty也可以更改属性的可配置性（是否可以删除，粗略地说）和枚举性（是否在for-in循环中显示）。没有这些（对于数据属性，也没有可写性），就无法进行更改。因此，我通常建议人们不要半实现Object.defineProperty，因为不幸的是，很难掌握细微差别。 - Jeff Walden

这是一个有趣的评论，但并没有真正回答问题。最多只能作为一条评论有用。 - mgol