使用Doxygen记录一个不存在的成员

Question

我正在尝试使用Doxygen文档记录一个Python类。该类在d-bus上公开了一组属性，但是在Python类中没有相应的公共getter/setter方法。相反，它们是通过d-bus属性接口（Set/Get/GetAll/Introspect）实现的。

我的目标是能够使用以下方式记录这些属性：

## @property package::Class::Name description

整个package::Class都可以正常工作（同样的方法找到函数，因此也可以找到正确的类）。

运行doxygen时，我会收到以下错误：

warning: documented function ``package::Class::Name' was not declared or defined.

我可以忽略这个警告，但不幸的是，在为该类生成的文档中，该属性未出现，因此它不仅是一个警告，而且还被忽略了。

因此，我的问题是，如果可能的话，如何使不存在的属性成员出现在生成的文档中？

- e8johan

Answer 1

在 if 0: 块内定义属性：

## @class X
## @brief this is useless
class X:
    if 0:
        ## @brief whatevs is a property that doesn't exist in spacetime
        ##
        ## It is designed to make bunny cry.
        whatevs = property

这将导致它在文档中存在（在 debian-squeeze 上测试了 doxygen 1.8.1.2-1）。该属性永远不会在运行时存在，实际上，看起来 Python 字节码优化器会完全消除 if 语句及其主体。

- Jeff Epler

Answer 2

我之前研究过类似的问题，但无法找到直接的方法来让Doxygen记录未定义的成员。这里有两种基本的解决方法：

1.) 生成一个虚拟对象（或虚拟成员）供Doxygen进行清单记录，但实际上在实际代码中并不存在。

2.) 如果你需要的调整是相当可预测和规律的，你可以为Doxygen编写一个INPUT_FILTER，在解析之前将文件转换。这种方法存在一些问题--主要是如果你计划在文档中包含代码，并且过滤器必须添加/删除文件中的行，它指示的行号将不正确，并且任何显示在文档中的代码窗口都会偏移那么多行。你也可以检查选项以过滤显示的源代码以进行调整，但根据你的文档使用者是谁，Doxygen中的副本与实际源代码不完全匹配可能会令人困惑。

在我们的情况下，我们使用一个Python脚本，Doxygen从命令行运行，并将文件路径作为参数。我们读取指定的文件，并将我们想要Doxygen解释的内容写入标准输出。如果您需要在Doxygen中显示源代码副本时进行过滤，您可以将FILTER_SOURCE_FILES设置为YES。

- abathur