microsoft / microsoft/language-server-protocol

textDocument/references is more strict but textDocument/documentHighlight delivers more information while being fuzzy

Open
#1,563 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

feature-request references
Dominant language
TypeScript
Stars
13k
Forks
1k
Avg merge
6d 1h
Merged PRs (30d)
10

Description

The result of textDocument/documentHighlight is defined as null or an array of:

export interface DocumentHighlight {
	range: Range;
	kind?: DocumentHighlightKind; /* one of Text, Read, Write */
}

and the result of textDocument/references is defined as null or an array of:

interface Location {
	uri: DocumentUri;
	range: Range;
}

The spec states:

However we kept ‘textDocument/documentHighlight’ and ‘textDocument/references’ separate requests since the first one is allowed to be more fuzzy. Symbol matches usually have a DocumentHighlightKind of Read or Write whereas fuzzy or textual matches use Textas the kind.

I don't understand why textDocument/documentHighlight is allowed to be fuzzy while actually delivering more information. It's result data type is richer and I would expect it to be the result of textDocument/references instead. Why not return DocumentHighlightKind in both?

Contributor guide

No contributing guide indexed for this repository

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.

Research direction

Start with the textDocument/documentHighlight and textDocument/references definitions in the LSP specification, including the linked DocumentHighlightKind section. Compare the stated fuzziness and result shapes, then determine whether the distinction needs a rationale or clarified specification text. Done would be an agreed explanation or a documented specification change.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.