doxygen 对 __init__.py 文件无效

Question

我正在用 Doxygen 来给一个 Python 模块写文档，但发现 __init__.py 文件的存在导致了一些问题。

现在这些 __init__.py 文件是空的（我尝试在里面加了一些注释，比如：

## Nothing here

但没有成功）。在 Doxygen 这边，模块的命名空间没有被识别。如果我的文件是这样的：

## @package stuff
#  @author me
#  Description
#
#  Some more description

## A class that does whatever
class whatever:
    ## A method that does stuff
    def dostuff(self):
        pass

那么它只会识别到 'Description' 和 'Some more description' 这两个字符串。即使文件里的类没有包含 __init__ 方法（我以为可能是命名冲突），Doxygen 也不会识别模块里的任何内容。

我尝试在 Doxyfile 里使用各种 'EXCLUDE' 指令，但都没有效果。

有没有人遇到过这个问题？如果删除 __init__.py 文件，一切就正常了，但这显然不是一个好的解决办法。

Answer 1

我也遇到过完全一样的问题，发现问题出在包的命名上。给定的名字需要是完整的名称。否则，你就是在为一个新包创建文档，这里这个包的名字是 stuff，但你的类会在一个没有文档的包里，除非你把 EXTRACT_ALL 设置为是，否则这个包是看不见的。

假设你的文件叫 stuff.py，并且在一个叫 mypackage 的文件夹里，同时还有一个 __init__.py 文件，那么 stuff.py 应该看起来像这样：

## @package mypackage.stuff
#  Description
#
#  Some more description
#  @author me

## A class that does whatever
class whatever:
    ## A method that does stuff
    def dostuff(self):
        pass

## A function that does whatever
def whatever:
    pass