Clarify position semantics in textDocument/hover request

[Copilot]

The textDocument/hover specification was ambiguous about which character the position parameter refers to, since Position is defined as being "between two characters like an 'insert' cursor."

Changes

• Added clarification to hover request documentation (LSP 3.17 and 3.18) that position typically refers to the position immediately to the left of the character being hovered over
• Noted that server interpretation remains language and implementation specific

Example

When hovering over character c at offset n:

a b c d
  ^   <- Position n is sent (before 'c')

This clarifies client behavior while preserving server flexibility for language-specific hover logic.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Clarify the meaning of position in textDocument/hover request</issue_title>
<issue_description>### Context

• This issue is not a bug report. (please use a different template for reporting a bug)
• This issue is not a duplicate of an existing issue. (please use the search to find existing issues)

Description

Problem Statement

The textDocument/hover request uses a position: Position parameter, which according to the LSP specification refers to:

A position is between two characters like an 'insert' cursor in an editor.

However, hover interactions typically occur on characters rather than between them. This creates ambiguity: when a position refers to a gap between characters, which symbol should the language server return hover information for?

An old issue discusses this, but the situation has not improved.

Current Implementation Inconsistencies

Most language server implementations handle this ambiguity inconsistently:

1. Default behavior: Return hover information for the symbol to the right of the position
2. Special case: When the position is at the end of a symbol, return hover information for the symbol to the left

This behavior is observed in TypeScript language server, gopls, and other major implementations.

Editor Implementation Mismatch

Code editors like VS Code exacerbate this issue. When a user hovers over a character, the editor typically sends the position before that character to the language server. This creates a chain reaction:

1. User hovers over a character (e.g., space) after a symbol
2. Editor sends position at the end of the preceding symbol
3. Language server applies special case handling
4. Hover information displays for the preceding symbol

Result: Hovering over whitespace unexpectedly shows information for adjacent symbols, creating unintuitive user experience.

Concrete Example

This ambiguity becomes critical when adjacent symbols have different hover information:

a+1

Scenario: Position (0,1) (between a and +)

• User expectation: Hover information for + operator (if available)
• Actual result: Hover information for variable a

This inconsistency makes hover behavior unpredictable and potentially misleading for developers.

Proposed Solutions

To resolve this ambiguity, I propose two complementary approaches:

1. Clarify Position Semantics in Specification

The LSP specification should explicitly define the expected behavior for textDocument/hover positions:

• Primary rule: Standardize which symbol (left or right of position) takes precedence
• Edge cases: Define consistent handling of whitespace, punctuation, and symbol boundaries
• Implementation guidelines: Ensure uniform behavior across all language server implementations

2. Support Range Parameter

Introduce an optional range: Range parameter in the textDocument/hover request:

interface HoverParams {
  textDocument: TextDocumentIdentifier;
  position: Position;
  range?: Range;  // NEW: Specify exact character(s) being hovered
}

Advantages:

• Eliminates ambiguity: Precisely identifies which character(s) the user is hovering over
• Maintains compatibility: Existing implementations continue working with position parameter
• Enhances flexibility: Enables editors to send exact hover targets
• Enables future features: Supports multi-character hover scenarios (e.g., hovering selected text)

This solution eliminates guesswork for language servers and ensures predictable, intuitive hover behavior for developers. And it may be related to #2027.
</issue_description>

Comments on the Issue (you are @copilot in this section)

@dbaeumer I will double check but it is the position left to the character you hover over. @dbaeumer The LSP specification in general doesn't try to enforce things like this since this might be language dependent. I think what we can add to the spec is that on hover the position is the one left to the hover character. What servers do with this for their specific language is IMO up to the server.

• Fixes Clarify the meaning of position in textDocument/hover request #2184

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.