Repository: TypeScript
Issue: Expand find-all-references to more keywords
Labels: Suggestion,In Discussion,Domain: Symbol Navigation

# Background

Today, document highlights/occurrences has special support for when a developer's cursor is over a keyword.

For example, let's say you had your cursor `/*$*/` in the following code.

```ts
if (foo()) {
  // ...
}
else if (bar()) {
  // ...
}
else/*$*/ {
  // ...
}
```

TypeScript is able to provide what's called "document highlights" (formerly called "occurrences") for the editor to highlight as visual clues. Typically, these keywords will be displayed with a lighter background/foreground in the editor, and the highlights we provide in the above case are denoted with `[|`these range markers`|]`.

```
[|if|] (foo()) {
  // ...
}
[|else if|] (bar()) {
  // ...
}
[|else|] {
  // ...
}
```

> *Yes, the `else if` is specially highlighted together!*

It would be great if find-all-references worked similarly. Editors often has key bindings for iterating through the current set of document highlights (on VS Code this is Go to Next Symbol Highlight - for Windows, the keybinding is <kbd>F7</kbd> and <kbd>Shift</kbd>+<kbd>F7</kbd>, and in VS, it's <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Up/Down</kbd>); however, these keyboard shortcuts are pretty undiscoverable. Document highlights are a subtle enough hint that users may not even know they exist. So find-all-references has the potential to be a nice delighter for a more-often-used action.

# What Would it Support?

I don't know the full list of things document highlights currently supports; however, from what I do know, here's a list of what I think would be useful, ranked loosely by utility.

* [ ] `return` keywords in a specific function scope
* [ ] `throw` keywords in a specific function or `try` block scope
* [ ] `break` and `continue` keywords in a specific loop construct, `switch` statement, or labeled statement
* [ ] `await` keywords in a specific function scope
* [ ] `yield` keywords in a specific function scope
* [ ] `export` keywords in a module or namespace
* [ ] `case` and `default` clauses in a `switch` statement
* [ ] Chained `if`/`else` branches
* [ ] `import` keywords in a module or namespace
* [ ] Accessibility modifiers in a class (e.g. `public`, `private`, `protected`, `readonly`)

# Specifics

Many of these are already implemented in document highights/occurrences. The only place I could think that these might differ is whether find-all-references would include the "owning" node in many of these contexts.

For example, today, find-all-references on a `case` keyword in a `switch` highlights all of the following:

* All the other `case` clause keywords 
* The `default` keyword for the `default` clause
* The `switch` keyword itself
* All of the corresponding `break` statements

So in the following document highlights request

```ts
innerLabel: {
  outerLabel: switch (a) {
    case 0:
      break innerLabel;
    /*$*/case 1:
      break outerLabel;
    default:
      break;
  }
}
```

you would get

```ts
innerLabel: {
  outerLabel: [|switch|] (a) {
    [|case|] 0:
      [|break|] innerLabel;
    [|case|] 1:
      break outerLabel;
    [|default|]:
      [|break|];
  }
}
```

So should find-all-references on that `case` actually return all of those? Or should it provide only the other `case` clauses?