Function's attached JSDoc is not preserved when using OmitThisParameter

[zaygraveyard]

Bug Report

🔎 Search Terms

JSDoc, types with docs, preserve docs, OmitThisParameter, bind, inherit description

🕗 Version & Regression Information

• This is the behavior in every version I tried, and I reviewed the FAQ for entries about "Something to do with this" and "Strong typing of Function members call/bind/apply"

⏯ Playground Link

Playground link with relevant code

💻 Code

/**
 * This description is lost
 * 
 * @param p As well as this decription
 */
function func(this: {}, p: string): void {}

const f = func as OmitThisParameter<typeof func>;
const g = func.bind({});

🙁 Actual behavior

Hovering over f (or g) shows the type but not the descriptions that were attached to func.

🙂 Expected behavior

f and g to inherit the descriptions of func.

Clarification

The problem mainly lies with OmitThisParameter as bind's declaration uses it.
I'm also not sure if this is considered a bug or a missing feature, so I apologize in advance if this is not the right way to report it.

Might be related to #50715

[RyanCavanaugh]

I'd say this is definitely a "missing feature". For any arbitrary type definition

type X<T, U> = // whatever

there aren't any rules for whether JS Doc should show what (if anything) is on X, T, U, or some combination thereof.

[zaygraveyard]

Although the general case would be awesome to have, it would be non-trivial to determine its resulting JS Doc.
In contrast to the limited case of OmitThisParameter, retaining the same JS Doc (and possibly removing the @this).
Correct me if I'm wrong but I feel the latter would be much simpler to implement than the former.

[fatcerberus]

It isn’t though because OmitThisParameter (TIL this exists) is implemented in userland, so it reduces to the much more difficult general case.

[zaygraveyard]

It can be changed into an intrinsic (like Uppercase, Lowercase, ...), or a new intrinsic can be added that preserves the JS Doc.
Alternatively, a marker type OmitThisType (analogous to ThisType) can be added. Which would be sufficient for my use case (of mapping an object of methods into an object of bound methods).

I would understand if this isn't a path the TypeScript team would like to take 😅

[zaygraveyard]

It looks like my test case above was misleading as it depends on having assignments that preserve the docs (which I believe is not supported).

I think the following code better demonstrates the issue:

const F = {
  /**
   * This description is lost
   */
  foo(this: string): void {},
};

const a: { [K in keyof typeof F]: OmitThisParameter<typeof F[K]> } = {} as any;
const b: { [K in 'foo']: OmitThisParameter<typeof F[K]> } = {} as any;
const c: { foo: OmitThisParameter<typeof F['foo']> } = {} as any;

a.foo(); // <- doc preserved ✅
b.foo(); // <- doc NOT preserved ❌
c.foo(); // <- doc NOT preserved ❌

⏯ Playground Link

Why is the description preserved in the case of a but not in case of the others b and c?

Note: The description is preserved in all three cases when not using OmitThisParameter or not specifying a this parameter type.