如何让Python文档字符串同时兼容Doxygen与VSCode？

有两种可靠的方案能同时满足VSCode悬浮提示正常显示、Doxygen正确解析参数生成文档的需求：

方案一：使用Google风格文档字符串 + 配置Doxygen识别 #

VSCode的Python插件原生支持Google风格的文档字符串，按规范编写后，悬浮提示能正常展示参数、返回值信息。同时只需修改Doxygen配置，就能让它识别这种格式。

示例代码 #

def calculate_sum(a: int, b: int) -> int:
    """计算两个整数的和

    Args:
        a: 参与计算的第一个整数
        b: 参与计算的第二个整数

    Returns:
        两个整数相加的结果
    """
    return a + b

Doxygen配置修改 #

在你的Doxyfile中添加或修改以下配置项：

# 关闭C语言优化，适配Python解析
OPTIMIZE_OUTPUT_FOR_C = NO
# 开启Google风格文档解析支持
GOOGLE_DOCS = YES
# 允许自动提取文档首行作为简要描述
JAVADOC_AUTOBRIEF = YES

配置完成后，Doxygen就能正确解析Args和Returns分段，生成规范的HTML文档；VSCode也能正常展示悬浮提示。

方案二：混合双格式标签 #

如果偏好保留Doxygen的@param、@return标签，同时要VSCode正常识别，可以在文档字符串中同时包含两种格式：

def calculate_sum(a: int, b: int) -> int:
    """计算两个整数的和

    Args:
        a: 参与计算的第一个整数
        b: 参与计算的第二个整数

    Returns:
        两个整数相加的结果

    @param a 参与计算的第一个整数
    @param b 参与计算的第二个整数
    @return 两个整数相加的结果
    """
    return a + b

这种写法下，VSCode会优先识别Args/Returns分段展示悬浮提示，Doxygen则会解析@param/@return标签生成文档。缺点是存在内容冗余，但能兼容两者的解析逻辑。

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