如何记录 returns 特定值的函数？

Question

我正在尝试记录以下 returns 只有三个值的方法：'active'、'inactive' 或 'blocked'。

Javascript代码：

/**
 * Returns the current post status.
 * @return {string} the current status: 'inactive', 'active' or 'blocked'.
 */
function getStatus() {
    if (this.status === 0) return 'inactive';
    if (this.status === 1) return 'active';
    if (this.status === 2) return 'blocked';
}

有没有办法指定返回值？也许是这样的：

@return {string=('inactive'|'active'|'blocked')} the current status.

如果没有，我应该怎么做？

Answer 1

不幸的是，JSDoc 中没有这样的东西，我能想到的唯一解决方案是像这样使用 @enum 标签：

/**
 * Post status.
 * @readonly
 * @enum {string}
 */
var STATUS = {
    /** The post is inactive. */
    INACTIVE: 'inactive',
    /** The post is active. */
    ACTIVE: 'active',
    /** The post is blocked. */
    BLOCKED: 'blocked'
};

/**
 * Returns the current post status.
 * @return {STATUS} the current status.
 */
function getStatus() {
    if (this.status === 0) return STATUS.INACTIVE;
    if (this.status === 1) return STATUS.ACTIVE;
    if (this.status === 2) return STATUS.BLOCKED;
}

JSDoc 结果：

如何记录 returns 特定值的函数？

How to document a function that returns specific values?

javascript

documentation

jsdoc

jsdoc3