Style variables in docstring shown on hover

[thomasaarholt]

Does pylance attempt to parse variables present in the docstring (under Args in the following example), like the variable name (a), type (int) and comment (My really long...)?

def my_func(a: int, b: str, c: bool) -> int:
    """My awesome function.

    Args:
        a (int): My really long description about this important variable that just keeps going.
        It is super important so I'm gonna spend two lines on this.
        b (str): Just a short string.
        c (bool): Another long description that just keeps going and going making guessing
        where things start and stop a bit challenging.

    Returns:
        int: Very integral.
    """
    ...

This docstring is shown as follows on hover (or Cmd + Shift + Space). It can sometimes be challenging for the reader to distinguish whether a new line marks the beginning of a variable's docs, or the continuation of the previous line.

It would be wonderful if these could be styled by font or colour to make them more clearly distinguishable when reading the docstring. If these properties could be accessed through VSCode json settings, it could allow people to customize the view themselves.

I realise that pylance probably can't do this, but I thought I'd check, since I can't work out from the docs how pylance parses it. (I've read #1848)

[judej]

Moving this issue to discussion as an enhancement request for comments and upvotes.

[diepala]

That would be awesome! I find it difficult to read the docs of a function on the hover view. Specially because the docstring is parsed as markdown, which results in function arguments not being separated in a separate line (maybe this is already solved?). I also wish it could be easier to distinguish the documentation of the different attributes of a function.

Using a different color or bold text for the function arguments in the docstring would be very helpful.

[lobsterkatie]

All I really want is for VSCode to render Python docstrings the same way it renders JSDoc comments - italicizing the param label, converting parameter names into <code>-style, and placing appropriate space between the lines so everything is readable. Compare:

JSDoc:

Python docstring:

[lobsterkatie]

FWIW, I got curious and went digging, and the code turning '@param someName' into @param someName for JS hovers appears to be here: https://github.com/microsoft/vscode/blob/f9db0056398ae3f24ebd0a6b38be13b212f95c6e/extensions/typescript-language-features/src/languageFeatures/util/textRendering.ts#L97. The m-dash between those two and the description is a few lines below it, where \u2014 is added. Haven't found the line spacing code yet, though. Might just be CSS.

Seems like this would be the place to add it, yeah? https://github.com/microsoft/pyright/blob/main/packages/pyright-internal/src/analyzer/docStringConversion.ts

[rchiodo]

I believe the source for our rendering of this is actually in Pyright (it's not closed source):

https://github.com/microsoft/pyright/blob/57f018c2adcf80fa27c9cf4d895871654054bbcf/packages/pyright-internal/src/analyzer/docStringConversion.ts#L23C6-L23C6

Meaning if you were so inclined, you could submit a PR to add this support.

[rchiodo]

Ha, you added that too. I missed that.

[lobsterkatie]

To be fair, I think I confirmed my edit adding that about 30 sec before your comment posted.

In any case, yeah, at least that bit (the non-line-spacing bit) of it I maybe could take a stab at. I'll give it a shot when I get a chance.

[lobsterkatie]

Update for anyone who's following along at home: The line spacing is indeed CSS, specifically this CSS: https://github.com/microsoft/vscode/blob/b8c413b68a99c8dc03a6e270586bf509d4e723ab/src/vs/base/browser/ui/hover/hover.css#L39

The problem with the Python docstrings is that the entire list of parameters, return value, etc is a single paragraph, whereas for JS each entry in that list is its own paragraph.