Question

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

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

理想情况下，我想在c ++标题中使用doxygen格式的注释填充python类/方法中的docstrings。

或者，生成单独的文档（在ascii，html ...中）也很有用。看起来支持这种功能在早期版本的swig（1.3及更早版本）中，但我没有办法它与2.0。

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

Answer 1

为了让你的doxygen评论进入python文件，网上有一个名为doxy2swig.py的python工具，如here所述。

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

doxy2swig.py index.xml documentation.i

并通过

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

％import＆＃34; documentation.i＆＃34;

完成了。

Answer 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

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