microsoft / microsoft/TypeScript

JSDoc @this does not propagate to the actual type of a function

Open
#44,461 2 comments 1 reaction 1 assignee View on GitHub

@sandersn is already working on this.

Since Jun 10, 2021.

Needs Investigation
Dominant language
Go
Stars
111k
Forks
14.4k
Avg merge
1d 19h
Merged PRs (30d)
117

Description

Bug Report

When using @this to annotate a function, the underlying type of that function does not reflect the TypeScript equivalent properly when used as a type elsewhere.

🔎 Search Terms

function this jsdoc

🕗 Version & Regression Information
  • This is the behavior in every version I tried, and I reviewed the FAQ for entries about JSDoc
⏯ Playground Link

Playground link with relevant code

💻 Code

You should test this out in VSCode, as the Play link appears to handle a few things incorrectly.

// Note: hovering over `someCallback` shows in annotation that
// the type of `this` is *, which is weird
// Also note a secondary bug that `someCallback` is assumed to be
// a constructor, even though it isn't, and there is no way
// to override it.
/**
 * @this {HTMLElement}
 * @param {MouseEvent} e
 */
function someCallback(e)
{
    this.textContent = 'hello';
}

// Note: this does not seem to work in Play, but VSCode
// seems to handle @type properly here. The only issue is
// that someCallback does not seem to have a proper `this` type.
/** @type {typeof someCallback} */
function equivalentType(e)
{
    // `this` is "any". In VSCode, `e` has the correct type,
    // but `this` is untyped.
    someCallback.call(this, e);
}

// This should be equivalent to the function above & to someCallback, but is not.
// This is the correct type for `typeof someCallback`, however.
/** @type {(this: HTMLElement, e: MouseEvent) => void} */
function actualEquivalentType(e)
{
    // "this" is typed properly
    someCallback.call(this, e);
}
🙁 Actual behavior

typeof someCallback does not include the this JSDoc component, and is typed as (e: MouseEvent) => void

🙂 Expected behavior

typeof someCallback should be (this: HTMLElement, e: MouseEvent) => void

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.