How to document a function that returns specific values?

Question

I'm trying to document the following method that returns only three values : 'active', 'inactive' or 'blocked' .

Javascript code :

/**
 * 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';
}

Is there a way to specify the returned value ? Maybe something like :

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

If not, how should I do that ?

Answer 1

Unfortunately, there is no such thing in JSDoc, and the only solution that I can think of is using the @enum tag like so :

/**
 * 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 result :