有没有一种为 swig 接口生成文档的好方法？答案

【问题标题】：Is there a good way to produce documentation for swig interfaces?有没有一种为 swig 接口生成文档的好方法？
【发布时间】：2012-07-11 14:38:19
【问题描述】：

我想知道是否有任何构建/维护的好技术界面上的文档。

我正在使用 swig 构建从 c++ 代码到 python 的接口；大多数时候我只是 %包括 c++ 头文件。我正在处理至少几十个课程和 100 多个功能，因此首选自动化工具。

理想情况下，我想在 c++ 标头中使用 doxygen 格式的 cmets 在 python 类/方法中填充文档字符串。

或者，生成单独的文档（在 ascii、html...中）也会很有用。似乎支持这种功能在 swig 的早期版本（1.3 和更早版本）中，但我看不到办法它与 2.0。

是否有任何有用的（自动化的）技术来记录界面？

【问题讨论】：

【解决方案1】：

要将您的 doxygen cmets 放入 python 文件，网络上有一个名为 doxy2swig.py 的 python 工具，如 here 所述。

从您的代码创建 xml 文档。然后使用工具：

doxy2swig.py index.xml 文档.i

并通过

在你的 swig 接口文件中导入 documentation.i

%import "documentation.i"

它已经完成了。

【讨论】：

【解决方案2】：

%feature("autodoc") 使用 SWIG 2.0 有一些里程，我认为目前为止。

例如：

%module test

%feature("autodoc", "3");

void foo (int *a, void *bar, double epsilon);

导致插入一些模糊不清的文档。

如果这还不够，我认为下一个最简单的步骤是使用 %pythonprepend 制作一个足够独特的标记 sed 或类似的可用于在 SWIG 自动运行后将文档插入界面：

%pythonprepend foo "MARKER"

然后：

sed -ei 's/MARKER/some documentation' test.py

您可以在哪里找到%pythonprepend 的函数，方法是使用（Python？）脚本查看 Doxygen 输出以生成标记并在运行 SWIG 后替换它们。

【讨论】：