Methods returning `this` are documented as returning the class

[pjeby]

Search terms

Methods with "return this" are documented as returning the class; method chaining.

Question

I have just started using typedoc on a project and am noticing that the output is imprecise regarding methods that return this. In VSCode's hints, these methods are identified as such, but typedoc lists them as returning an arbitrary instance of the class. This makes it challenging to tell from the documentation which methods are returning the same instance rather than a new one. (As I have a class with both kinds of methods.)

(It does this even if I explicitly declare the method as returning this - i.e. someMethod(): this {...}, let alone implicitly.)

Is this intentional, an oversight, or something else? Is there any way to force the output to show this for such methods? Thanks.

[Gerrit0]

This is intentional-ish. TypeDoc asks the type checker for what type is in use on the class when doing documentation to handle generic parameters which should be resolved at that point (class Foo extends Array<number> should have a push method that takes a number, not T)

this is a special type parameter, which happens to fall into this same checks, though there's a reasonably good argument that we shouldn't be doing this.

[pjeby]

Well, my goal here is less "type" and more "doc". As in, what's the best way to indicate in the docs that methods are intended for chaining of the same instance, when some methods do return a different instance? (Preferably without typing out a sentence to that effect in each doc comment. 😉)

[Gerrit0]

I think it would be an improvement for TypeDoc to document these methods as returning this - no change should be necessary for your code ideally... I've added a fix locally to do this for methods with : this, but it doesn't work with implicit this return types, which I'd like to handle too.

[Gerrit0]

Looking at this again, I see why I didn't do it for implicit this types last week... it requires reaching into the compiler internals. I think I'll just accept that limitation for now and only do this for explicit : this return types.

[pjeby]

Thanks!