VS Code中Python Docstring带括号类型前置时Hover格式异常问题

问题重现 #

你使用的两种docstring格式对比：

格式1（正常显示） #

def function(a: str, b:bool, c:int):
    '''函数文档字符串。
    补充说明内容。
    
    args:
        a: 随机字符串参数 (str)
        b: 布尔型参数说明 (bool)
        c: 整数型参数说明 (int)

    return:
        返回值说明
    '''
    a = a + ' world'
    b = 5 * b
    c = 10 + c
    return c

VS Code悬停时参数正常分行显示。

格式2（参数合并） #

def function(a: str, b:bool, c:int):
    '''函数文档字符串。
    补充说明内容。
    
    args:
        a: (str) 随机字符串参数
        b: (bool) 布尔型参数说明
        c: (int) 整数型参数说明

    return:
        返回值说明
    '''
    a = a + ' world'
    b = 5 * b
    c = 10 + c
    return c

VS Code悬停时所有参数合并为一行显示。

原因 #

VS Code默认使用的Pylance语言服务，在解析docstring参数列表时依赖固定格式规则识别参数项。当参数描述以(类型)开头时，Pylance会误将其判定为上一个参数描述的换行延续内容，而非独立参数项，最终导致参数合并显示。而纯文本打印docstring不受该解析规则影响，因此格式正常。

保留括号的解决方案 #

改用Google风格的标准docstring格式，这是Pylance原生支持的格式，既能保留类型的括号标注，又能保证参数正常分行：

修正后的代码 #

def function(a: str, b:bool, c:int):
    '''函数文档字符串。
    补充说明内容。
    
    Args:
        a (str): 随机字符串参数
        b (bool): 布尔型参数说明
        c (int): 整数型参数说明

    Returns:
        返回值说明
    '''
    a = a + ' world'
    b = 5 * b
    c = 10 + c
    return c

效果 #

这种格式下，VS Code悬停函数时每个参数会单独分行显示，类型标注的括号也被完整保留，完全满足需求。

内容的提问来源于stack exchange，提问作者darren