3

I use standard docstring format, there is a useful example here: What are the most common Python docstring formats?

So here is example code:

def function(a: str, b:bool, c:int):
    ''' the function doc string. 
    Here is a bit more.
    
    args:
        a: a random string goes here (str)
        b: lets describe something binary (bool)
        c: we have a whole number (int)

    return:
        gives something back


    '''
    
    a = a + ' world'
    b = 5 * b
    c = 10 + c


    return c

When I hover over the function definition in VS Code, the description is nicely formatted. Each argument is on its own separate line:

enter image description here

But I like to add the types at the beginning, like this:

def function(a: str, b:bool, c:int):
    ''' the function doc string. 
    Here is a bit more.
    
    args:
        a: (str) a random string goes here
        b: (bool) lets describe something binary
        c: (int) we have a whole number

    return:
        gives something back


    '''
    
    a = a + ' world'
    b = 5 * b
    c = 10 + c


    return c

Now when I hover over the function definition the args are all merged onto one line:

enter image description here

I notice that this is caused by the parentheses around the types and removing them removes the problem.

I also note that if I print the docstring, it looks how it should be, so it is like VS Code has an issue with the parentheses:

print(function.__doc__)

returns this:

 the function doc string. 
    Here is a bit more.
    
    args:
        a: (str) a random string goes here
        b: (bool) lets describe something binary
        c: (int) we have a whole number

    return:
        gives something back

But why is this the case and how can I get it back to normal (keeping the parentheses)?

9
  • 1
    Shouldn't the type be before the colon? That's what the linked examples show. Commented May 4, 2023 at 10:58
  • 1
    @l4mpi, i hear what you say. however, i note that vscode is a major tag. If you do open an issue, it might be worth posting a link here. Commented May 4, 2023 at 11:29
  • 1
    @D.L I wouldn't even use that garbage editor if you offered to pay me for it, so no, I'm not going to open an issue. I'm just saying it's useless to ask this question on SO as this seems like a VSCode bug so it's unanswerable (the answer would be "it's a bug, wait for it to get fixed"). That we have a vscode tag doesn't change that fact. Commented May 4, 2023 at 11:38
  • 2
    @l4mpi, you are correct (aside from a bias against a particular editor). I treat this as a bug and have reported the issue here: github.com/microsoft/vscode/issues/181499 Commented May 4, 2023 at 11:48
  • 1
    Just an observation. (btw, i fully support opening the formatting issue) but isn't the extra text redundant? The type does also show up in the function prototype in the hover. Having it in the string too just gives you 2 places to maintain. Kind of violates the DRY principle. Commented May 4, 2023 at 11:58

1 Answer 1

2

This is fixed. The error was pylance and upgrading to version 2023.5.21 allows for the types before the colon like so (which is the normal google doc format).

So this format now works:

def function(a: str, b:bool, c:int):
    ''' the function doc string. 
    Here is a bit more.
    
    args:
        a (str): a random string goes here
        b (bool): lets describe something binary
        c (int): we have a whole number

    return:
        gives something back


    '''
    
    a = a + ' world'
    b = 5 * b
    c = 10 + c


    return c

The link to the github answer is here:

https://github.com/microsoft/pylance-release/issues/4377

Sign up to request clarification or add additional context in comments.

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.