JS with Types Start

JSDoc tag

@yields

  • Not checked by TypeScript
  • Tested with TypeScript 5.9
  • Alias @yield

@yields {Type} is the JSDoc documentation tag for the values a generator produces. TypeScript does not support it; the handbook lists it as unsupported, with an open issue. In TypeScript 5.9 a generator tagged @yields {number} that yields strings passes without an error.

Declare the generator's return type instead: @returns {Generator<number>}. TypeScript then checks every yield against number and types the values a for...of loop receives.

At a glance

Use JSDoc in a .js file TypeScript in a .ts file
A generator of numbers /** @returns {Generator<number>} */ function* ids() { … } function* ids(): Generator<number> { … }
All three type arguments /** @returns {Generator<number, void, unknown>} */ function* ids(): Generator<number, void, unknown> { … }

Examples

ids.js TypeScript 5.9.3 TypeScript 5.9.3, run 21 October 2026: No errors. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. No errors. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. No errors. checked 21 October 2026 
/** @yields {number} */
export function* orderIds() {
  // tsc says nothing: the generator's type comes from what it yields, a string.
  yield "A-100";
  yield "A-101";
}

for (const id of orderIds()) id.toUpperCase();
@yields is not read: a generator that yields the wrong type passes.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}
ids.js Error confirmed 5.9.3 TypeScript 5.9.3, run 21 October 2026: ids.js(5,9): error TS2322: Type 'string' is not assignable to type 'number'. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. ids.js(5,9): error TS2322: Type 'string' is not assignable to type 'number'. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. ids.js(5,9): error TS2322: Type 'string' is not assignable to type 'number'. checked 21 October 2026 
/** @returns {Generator<number>} */
export function* orderNumbers() {
  yield 100;
  yield "A-101";error TS2322: Type 'string' is not assignable to type 'number'.
}
Declare the yielded type with @returns {Generator<T>}.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}
ids.js ids.ts TypeScript 5.9.3 TypeScript 5.9.3, run 21 October 2026: No errors. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. No errors. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. No errors. checked 21 October 2026 
/**
 * @param {number} start
 * @param {number} count
 * @returns {Generator<number, void, unknown>}
 */
export function* orderNumbers(start, count) {
  for (let n = start; n < start + count; n++) yield n;
}

for (const n of orderNumbers(100, 3)) n.toFixed(0);
export function* orderNumbers(start: number, count: number): Generator<number, void, unknown> {
  for (let n = start; n < start + count; n++) yield n;
}

for (const n of orderNumbers(100, 3)) n.toFixed(0);
A typed generator, used in a for...of loop.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}

How we tested it

The first example tags a generator @yields {number} and yields strings, then calls toUpperCase() on each value. Both would fail if the tag were read. tsc reports nothing: the yielded type comes from the yield expressions alone. The second example uses @returns {Generator<number>}, and the string yield fails with TS2322.

Generator types

Generator<T, TReturn, TNext> has three type arguments: what each yield produces, what the final return gives, and what callers can pass to next(). Generator<number> leaves the last two at their defaults. Async generators use AsyncGenerator<T>, and Iterable<T> or IterableIterator<T> work when callers only loop over the values.

Gotchas

  • Without any tag, TypeScript infers the generator type from its body, which is often fine for private helpers.
  • Keep @yields for a documentation tool if you like, but nothing keeps it in step with the @returns type, so update both by hand.

Questions

How do I document a generator function with JSDoc for TypeScript?

Use @returns {Generator<T>} (or AsyncGenerator<T> for async function*). TypeScript reads that; it ignores @yields.

  • JSDoc tag

    @returns

    The JSDoc @returns tag declares a function's return type, and TypeScript checks every return against it. Async functions, void, and when to leave it out.

  • JSDoc tag

    @async

    The JSDoc @async tag does not make TypeScript treat a function as async. The async keyword does, and @returns {Promise<T>} gives the resolved type.

  • JSDoc tag

    @type

    The JSDoc @type tag gives a variable, property or expression a type that TypeScript checks: the syntax, casts with parentheses, and whole function types.

  • Type expression

    Function types

    Writing function types in JSDoc: TypeScript's arrow syntax (price: number) => string, the older function(number): string, and Function. Examples and errors.

Sources

Last reviewed 20 October 2026.