Page MenuHomePhabricator

Express chainable method (or "returns this") in JSDoc
Open, MediumPublic

Description

By default, JSDoc does not recognise @chainable. Which means these methods, with the old JSDuck comments, may get wrongly indexed as return void/undefined.

It seems JSDoc does not support @return {this}, either. So as workaround we'll probably have to hardcode the current class name.

This may become a problem given that it won't honour inheritance in that case. E.g. a subclass or composed class using EventEmitter would wrongly have its inherited on() method state that it returns EventEmitter when actually it returns the current self.

Upstream: https://github.com/jsdoc3/jsdoc/issues/991

Event Timeline

https://github.com/jsdoc/jsdoc/issues/669

advises

@returns {MyClass} this, chainable

Does that work with jsdoc3 as well ?

Jdlrobson triaged this task as Medium priority.Feb 1 2024, 10:42 PM

If I understand microsoft/TypeScript#4910 correctly, @return {this} should work in TypeScript (and it indeed seems to work in JS code in VS Code), so even though JSDoc doesn’t support it officially, it may be the way to go.

Change #1025350 had a related patch set uploaded (by Jforrester; author: Esanders):

[jsdoc/wmf-theme@master] Support @chainable

https://gerrit.wikimedia.org/r/1025350