Docstring Formatting in autocomplete suggestion

[sagarchalise]

Is your feature request related to a problem? Please describe.
Currently the autocomplete docstring format is not that readable. Is it possible to show docstrings as is ? I am using google style.

Describe the solution you'd like
I think docstring shown by vscode-python is nice. It would be nice if some formatting could be done to docstring when shown in suggestion.

[erictraut]

Thanks for the suggestion.

Could you provide a more detailed example that includes some original docstrings and what you think they should look like when displayed in completion results?

We are somewhat limited by the way in which VS Code and other language clients display completion results, which are provided in markdown format.

[sagarchalise]

@erictraut Basically here is the suggestion on same definition from vscode-python. As you can see the docstring is formatted as is and not stripped.

Here is some example taken from sphinx napolean extension

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
   """Example function with PEP 484 type annotations.

   Args:
       param1: The first parameter.
       param2: The second parameter.

   Returns:
       The return value. True for success, False otherwise.

   """
   return bool(param1 + param2)

this is rendered as

(method) function_with_pep484_type_annotations: (param2: str) -> bool
Example function with PEP 484 type annotations.

Args: param1: The first parameter. param2: The second parameter.

Returns: The return value. True for success, False otherwise.

[jakebailey]

FWIW that image is taken with the vscode-python extension with Jedi enabled; in this case no special processing is done (the text is copied 1:1), which has its own downsides. E.g., you can see that the indention of the block means it's being treated as a markdown code block with a monospaced font and awkward text wrapping. If you enable the language server, the tooltips will look the same as your original screenshot (which uses the same heuristical conversion to attempt to make any docstring into somewhat-good looking markdown).

The numpy/google/sphinx format's section block (like args) is one case that doesn't look so good with the conversion, and does stand to be improved.

[msfterictraut]

As Jake said, there are pros/cons to both approaches. To me, the JEDI formatting looks worse (is harder to read) than the formatting used by MPLS and Pyright. I agree that neither of them are ideal.

[sagarchalise]

It seems it is being discussed in vscode-python as well.

[erictraut]

This is a duplicate of feature request being discussed in the pylance-release repo. microsoft/pylance-release#48
Also related to this issue: microsoft/pylance-release#41
I'm going to close this bug and use the others to track this issue.