search

palantir / python-language-server

An implementation of the Language Server Protocol for Python
MIT License
2.6k stars 282 forks source link

Should the result for textDocument/hover be markdown or plaintext? #836

Open rwols opened 3 years ago

rwols commented 3 years ago

There are a few python docstyles out in the wild. See: https://stackoverflow.com/a/24385103. Most notably, none of these are markdown.

The return type from pyls for a textDocument/hover request is a MarkedString[]. Usually this returns a list of 2 marked strings. The first MarkedString has the form {"language": "python", "value": "some content"}. The second MarkedString is a string.

The LSP spec states that clients should interpret MarkedString strings as markdown. This results in the docblocks being rendered odd for different requests. Here are some examples:

textDocument/hover rendering markdown: (never mind the added text, it's incorrect) https://cdn.discordapp.com/attachments/645268178397560865/738774901837660210/Snipaste_2020-07-31_23-05-05.png

textDocument/signatureHelp rendering plaintext: (this is correct rendering) https://cdn.discordapp.com/attachments/645268178397560865/738774912193265785/Snipaste_2020-07-31_23-03-44.png

textDocument/complete rendering plaintext: (this is correct rendering) https://cdn.discordapp.com/attachments/645268178397560865/738774915062169621/Snipaste_2020-07-31_23-06-57.png

The solution is to update textDocument/hover by making it return plaintext instead of markdown. Since Python has diverse doc-styles it's somewhat hard to translate docs to markdown, so let's just do plaintext for now.

ccordoba12 commented 3 years ago

Agreed. Please submit a pull request for that. Thanks!

krassowski commented 3 years ago

FYI: https://github.com/krassowski/docstring-to-markdown (now used on my fork and by jedi-language-server).