Có cách nào tốt để tạo tài liệu cho các giao diện swig không?

Question

Tôi muốn biết liệu có bất kỳ kỹ thuật tốt nào để xây dựng/duy trì tài liệu trên giao diện hay không.

Tôi đang tạo giao diện từ mã C++ tới python bằng swig; chủ yếu tôi chỉ là % bao gồm các tệp tiêu đề C++. Tôi đang xử lý ít nhất hàng tá lớp học và 100 chức năng, do đó các công cụ tự động được ưu tiên.

Lý tưởng nhất, tôi muốn sử dụng các nhận xét doxygen đã định dạng trong tiêu đề C++ để điền các tài liệu vào các lớp/phương thức python.

Cách khác, tạo tài liệu riêng (trong ascii, html ...) cũng sẽ hữu ích. Có vẻ như loại chức năng này đã được hỗ trợ trong các phiên bản trước đó của swig (1.3 trở về trước) nhưng tôi không thấy cách nào để thực hiện với 2.0.

Có bất kỳ kỹ thuật hữu ích (tự động) nào để ghi lại giao diện không?

Answer 1

Có một số số dặm trong %feature("autodoc") với SWIG 2.0, mà tôi nghĩ là đến thời điểm hiện tại.

Ví dụ:

%module test 

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

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

gây ra một số tài liệu hướng dẫn mơ hồ lành mạnh để được chèn vào.

Nếu đó không phải là đủ Tôi nghĩ bước dễ nhất tiếp theo sẽ được sử dụng %pythonprepend để thực hiện một điểm đánh dấu đó là duy nhất đủ sed hoặc tương tự có thể được sử dụng để chèn tài liệu vào giao diện sau SWIG đã chạy tự động:

%pythonprepend foo "MARKER" 

và sau đó:

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

Nơi bạn có thể tìm thấy các chức năng để %pythonprepend bằng cách xem qua sản lượng Doxygen sử dụng một (Python?) kịch bản để tạo ra các dấu hiệu và thay thế chúng sau khi r thống nhất SWIG.

Answer 2

Để nhận các nhận xét doxygen của bạn vào tệp python, có một công cụ python được gọi là doxy2swig.py trên web như được mô tả here.

Tạo tài liệu xml từ mã của bạn. Sau đó sử dụng công cụ này:

doxy2swig.py index.xml documentation.i

và nhập khẩu documentation.i trong bạn uống một lân tập tin giao diện qua

% nhập khẩu "documentation.i"

Và hoàn tất.