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

【问题标题】：Documenting a non-existing member with Doxygen用 Doxygen 记录一个不存在的成员
【发布时间】：2012-10-18 14:47:24
【问题描述】：

我正在尝试使用 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.

我可以忍受警告，但不幸的是，该属性未能出现在为该类生成的文档中，因此它不仅是警告，而且还被静音。

所以，我的问题是，如果可以的话，如何让不存在的属性成员出现在生成的文档中？

【问题讨论】：

标签： python properties doxygen

【解决方案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 语句及其主体。

【讨论】：

【解决方案2】：

我之前研究过类似的东西，但找不到直接的方法来诱使 Doxygen 记录未定义的成员。您可以在这里使用两个基本的组合：

1.) 为 doxygen 生成一个虚拟对象（或虚拟成员）以清点实际代码中不存在的虚拟对象。

2.) 如果您需要的调整是相当可预测和定期的，您可以为 doxygen 编写一个INPUT_FILTER，它会在解析之前获取您的文件并转换它们。这种方法存在一些问题——主要是如果您计划在文档中包含代码并且过滤器必须从文件中添加/删除行，它指示的行号将被关闭，并且任何代码窗口都显示为文档将按该行数关闭。您还可以选中过滤显示的来源以对此进行调整的选项，但根据您的文档的使用者是谁，Doxygen 中的副本与真实来源中的内容不完全匹配可能会令人困惑。

在我们的例子中，我们使用 Doxygen 从命令行以文件路径作为参数运行的 python 脚本。我们读取指示的文件并将我们希望 Doxygen 解释的内容写入标准输出。如果您还需要过滤 doxygen 中显示的源副本，您可以将 FILTER_SOURCE_FILES 设置为 YES。

【讨论】：