JSDoc support for @yields

[SergioMorchon]

It would be nice to be able to use the @yields JSDoc tag.

We work with JS and JSDoc, but taking advantage of TSC and VSCode.
We also use the valid-jsdoc eslint rule.

We have:

/** @typedef Thing (...) */

function* walkThings() {
//... some yield here and there
}

We want to

/**
 * @yields {Thing}
 */
function* walkThings() {
//... some yield here and there
}

We can't do

/**
 * @returns {IterableIterator<Something>}
 */
function* walkThings() {
//... some yield here and there
}

Because it doesn't return, but yields, and eslint complains about it. We can disable the rule here, but it is not the desirable scenario.

[DanielRosenwasser]

Just to weigh in here, sounds like a bug on the ESLint side as well.

[SergioMorchon]

Just to weigh in here, sounds like a bug on the ESLint side as well.
I'm not really confident about that @DanielRosenwasser :

• return means something different from yield at a syntactic level.
• The IterableIterator<T> is an implementation detail, the code does not return an iterable iterator, nor the developer wrote that. Just multiple yields.
• I couldn't find any standard documentation about what typescript defined as IterableIterator, so I wouldn't expect from eslint to know about it. Just curious about it: where does it comes from? Is it an internal definition for typescript generators?

[weswigham]

Is it an internal definition for typescript generators?

It's an interface (well, suite of them) defining the shape of a generator or IterableIterator spec object:

interface IteratorResult<T> {
    done: boolean;
    value: T;
}

interface Iterator<T> {
    next(value?: any): IteratorResult<T>;
    return?(value?: any): IteratorResult<T>;
    throw?(e?: any): IteratorResult<T>;
}

interface Iterable<T> {
    [Symbol.iterator](): Iterator<T>;
}

interface IterableIterator<T> extends Iterator<T> {
    [Symbol.iterator](): IterableIterator<T>;
}

[SergioMorchon]

Thank you @weswigham for the response. I already noticed that (that's the reason why I used it in the JSDoc part). I wanted to know if there were such definition in a standard way, just like HTMLElement does, or if it was a definition made by the typescript developers to model the iterable iterator instances (thinking about PromiseLike<T>).

You solved my question anyway, thanks again!