Documentation for how to format docstrings for correct tooltips using Jedi

[Lexicality]

From my understanding of reading things like DonJayamanne#38 and #107, it's possible for python to display function parameters like javascript:

However, I've tried every docstring format under the sun I can find (and tried both Jedi and the PLS) and I can't seem to cause this to happen. The entire docstring always ends up on one line:

I can't find any documentation for how docstrings are parsed, displayed or the "best" way to write them.

(PS I'm aware there are a huge number of conflicting opinions as to what the best docstring format is, however I don't have any skin in that game. I just want my code completion to work)

[brettcannon]

Specifically what are you after that isn't covered by DonJayamanne#38 and just supporting some docstring format to properly format it? You mention "code completion to work", so are you referring to the JavaScript screenshot only showing argument-specific docstring details compared to the Python one that shows everything?

[Lexicality]

Is showing argument-specific docstring details not a thing?

I opened this issue because I can't find any concrete explanation as to how docstrings are processed / supported. Possibly it's hidden in an issue comment somewhere that I've missed.

I am asking for an explanation in the readme / the extension page / the visualstudio.com python section / wherever that explains the current situation clearly.

[Brodersen]

The current hover info is not very practical.

It would be really helpful to see just some (even the unformatted) docstring, until a better solution has been found. Or at least make it an option.

[brettcannon]

As a general note, this issue is specifically targeted at Jedi (I have updated the title accordingly). If you are having issues with Pylance, then please report them at https://github.com/microsoft/pylance-release.

[Lexicality]

Is there documentation on how to format docstrings for Pylance somewhere?

[brettcannon]

@Lexicality not that I'm aware of (I don't believe they have added specific docstring format support yet; I would open an issue on their repo).

[trir262]

From what I can tell, the docstring is parsed as a markdown document.
so as long as you respect the extra blank lines, vscode will show it properly.

Example

def function(x : int):
"""
# Summary: function summary goes here

longer description goes here, really explaining the purpose

## Inputs:

    x : int

## Returns:

    int
"""

[varunagrawal]

@trir262 is correct, but that breaks from all standard docstring conventions, making it extra work and cost to update the documentation, when instead having an option for the docstring tooltip should suffice.

[karrtikr]

Thanks for your feedback! We have released a new and more performant language server called Pylance which likely solves these issues you are reporting.  You can download Pylance from the marketplace and install it alongside the core Python extension. Because our team's development efforts have shifted to support the new language server, we'd encourage you to try it out. If you try out Pylance and this issue persists, you can open an issue on the pylance-release repo.

[luabud]

I believe this behaviour has changed since we moved our Jedi support to https://github.com/pappasam/jedi-language-server, so I'm closing this. But let me know if you can still reproducing this and we can reopen!