Search code examples
pythonvisual-studio-codedocstring

docstring not working in Python on VS Code


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)?


Solution

  • 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