有没有一种很好的方法来生成swig接口的文档？

Question

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

我正在使用swig构建一个从c ++代码到python的接口; 大多数情况下,我只是包括c ++头文件.我正在处理至少几十个类和100个函数,因此首选自动化工具.

理想情况下,我想在c ++头文件中使用doxygen格式的注释来填充python类/方法中的文档字符串.

或者,生成单独的文档(在ascii,html ...中)也很有用.看起来早期版本的swig(1.3及更早版本)支持这种功能,但我没有看到用2.0做的方法.

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

Answer 1

为了让您的Doxygen注释到Python文件存在所谓doxy2swig.py描述Web上的蟒蛇工具在这里.

从代码中创建xml文档.然后使用该工具:

doxy2swig.py index.xml documentation.i

并在你的swig界面文件中导入documentation.i

%import"documentation.i"

它完成了.

Answer 2

SWIG 2.0已经取得了一定的进展%feature("autodoc")，我认为这就是目前的进展。

例如：

%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 后替换它们，从而找到这些函数。