Python类函数文档字符串空行致Doxygen命令解析失效如何解决？

问题说明 #

在Python类的成员函数docstring里加空行分隔功能描述和参数说明时，Doxygen会直接忽略@param这类特殊命令；但普通函数（非类成员）的docstring里加空行却完全没问题，这种不一致的情况让人没法兼顾文档美观和解析正确性。

解决办法 #

1. 用Doxygen段落标记替代空行 #

不用原生空行，改用@par标记来划分区块，既能保持内容分隔的可读性，又不会干扰Doxygen解析：

class Foo:
    def __init__(self, val):
        """! This is a public member
        @par 参数说明
        @param val (int): integer input
        """
        self.bar = val

2. 修改Doxygen配置 #

调整Doxygen配置文件的两个关键选项，让它支持跨空行解析特殊命令：

• 把JAVADOC_AUTOBRIEF设为YES：这个选项会让Doxygen自动识别docstring开头的简要描述，空行后的内容依然会被正常解析
• 确保AUTOLINK_SUPPORT设为YES：保证@param这类命令能被正确识别和关联

3. 显式使用@brief和@details标记 #

通过显式标记区分简要描述和详细内容，空行可以正常保留，Doxygen也能正确解析：

class Foo:
    def __init__(self, val):
        """! @brief This is a public member

        @details
        @param val (int): integer input
        """
        self.bar = val

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