Czy istnieje dobry sposób na tworzenie dokumentacji dla interfejsów Swig?

Question

Chciałbym wiedzieć, czy istnieją dobre techniki do konstruowania/utrzymywania dokumentacji w interfejsie.

Buduję interfejs z kodu C++ do Pythona za pomocą swig; przeważnie jestem tylko % łącznie z plikami nagłówkowymi C++. Mam do czynienia z co najmniej kilkadziesiąt klas i 100 z funkcji, więc preferowane są narzędzia automatyczne.

Idealnie chciałbym użyć sformatowanych doxygen komentarzy w nagłówkach C++ do zapełnić docstrukcje w klasach/metodach Pythona.

Alternatywnie, przydatne byłoby również wygenerowanie oddzielnej dokumentacji (w ascii, html ...) . Wygląda na to, że tego rodzaju funkcjonalność była wspierana we wcześniejszych wersjach swig (1.3 i wcześniejszych), ale nie widzę sposobu na zrobienie go z 2.0.

Czy są jakieś przydatne (zautomatyzowane) techniki dokumentowania interfejsu?

Answer 1

W modelu %feature("autodoc") jest trochę kilometrów z SWIG 2.0, co moim zdaniem jest tak daleko, jak obecnie.

Na przykład

%module test 

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

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

powoduje pewne niejasno sane dokumentację do wstawienia.

Jeśli to nie wystarczy, myślę, że w przyszłym Najprostszym krokiem byłoby wykorzystanie %pythonprepend aby znacznik, który jest unikalny na tyle sed lub podobne mogą być wykorzystane do wstawienia dokumentację do interfejsu po SWIG prowadzi automatycznie:

%pythonprepend foo "MARKER" 

, a następnie:

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

Gdzie można znaleźć funkcje do %pythonprepend patrząc na wyjściu Doxygena użyciu (Python?) skrypt do generowania znaczników i zastąpić je po r unning SWIG.

Answer 2

Aby uzyskać komentarze doxygen do plików Pythona istnieje narzędzie Pythona o nazwie doxy2swig.py w Internecie, jak opisano here.

Utwórz dokumentację XML z kodu. Następnie użyj narzędzia:

doxy2swig.py Index.xml documentation.i

i import documentation.i w ty haust plik interfejsu, przez

% importu "documentation.i"

I gotowe.