microsoft/language-server-protocol

A generic method to get documentation string or `SignatureInformation`

Open

#2,031 opened on Sep 30, 2024

View on GitHub
 (4 comments) (2 reactions) (0 assignees)HTML (12,810 stars) (956 forks)batch import
feature-requesthelp wantednew request

Description

I need to build a feature that lists all functions, classes, and methods in a file (or workspace) including possible documentation strings.

Currently textDocument/documentSymbol returns documentSymbol that includes name, detail, and kind. But there's no way to get documentation strings.

In textDocument/signatureHelp, there already is support for docstrings: SignatureInformation includes all the necessary metadata about the signature, label, documentation, and parameters. However, as far as I understand, this request can only be triggered from a use (e.g., of a function), not via the function declaration itself.

There should be a generic way to obtain this information. I see three possibilities:

  1. A request for getting docstrings, similar to https://github.com/microsoft/language-server-protocol/issues/1034 or https://github.com/microsoft/language-server-protocol/issues/1508
  2. A request to get SignatureInformation from declaration or implementation location.
  3. Extend textDocument/documentSymbol to include SignatureInformation or documentation attribute.

In inclined to favor option 2. as it is generic and most backward compatible.

It seems that many LSP servers already support documentation strings (they're being included in hover results for example), so in most cases the server already has this information, it just cannot be easily accessed.

Contributor guide

Tech stack
None
Domain
apideveloper experiencetooling
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
5
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
over 1 week
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Understanding of LSP specificationFamiliarity with documentSymbol and signatureHelp
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
20
Research direction
Examine the current LSP specification for documentSymbol and signatureHelp. Review the related issues #1034 and #1508 for previous discussions on getting documentation strings. Consider the feasibility of option 2 (getting SignatureInformation from declaration location) by surveying how existing language servers like TypeScript's tsserver expose such data. Propose a new request or an extension to documentSymbol in the LSP specification.