Esiste un buon modo per produrre documentazione per le interfacce swig?

Question

Vorrei sapere se esistono buone tecniche per la creazione/manutenzione della documentazione nell'interfaccia.

Sto costruendo un'interfaccia dal codice C++ a python usando swig; per lo più sono solo % compresi i file di intestazione C++. Ho a che fare con almeno dozzine di classi e 100 di funzioni, quindi sono preferiti gli strumenti automatici.

Idealmente, mi piacerebbe utilizzare i commenti formattati con doxygen negli header C++ su popolano le docstring nelle classi/metodi python.

In alternativa, generare documentazione separata (in ascii, html ...) sarebbe anche utile. Sembra che questo tipo di funzionalità fosse supportata nelle versioni precedenti di swig (1.3 e precedenti) ma non vedo un modo per fare con 2.0.

Esistono tecniche utili (automatizzate) per documentare l'interfaccia?

Answer 1

C'è qualche chilometraggio in %feature("autodoc") con SWIG 2.0, che a mio parere è tanto lontano va ora.

Ad esempio:

%module test 

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

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

provoca qualche documentazione vagamente sano da inserire.

Se questo non è sufficiente Penso che il prossimo passo più semplice sarebbe quella di utilizzare %pythonprepend per fare un marcatore che è unico abbastanza sed o simili può essere utilizzato per inserire la documentazione nell'interfaccia dopo SWIG ha eseguito automaticamente:

%pythonprepend foo "MARKER" 

e poi:

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

Dove si potrebbe trovare le funzioni a %pythonprepend, cercando sopra l'uscita Doxygen utilizzando un (Python?) script per generare i marcatori e sostituirli dopo r Unire SWIG.

Answer 2

Per ottenere i commenti doxygen nei file python esiste uno strumento python chiamato doxy2swig.py sul web come descritto here.

Crea documentazione xml dal tuo codice. Quindi utilizzare lo strumento:

doxy2swig.py index.xml documentation.i

e l'importazione documentation.i in voi sorso file di interfaccia tramite

% import "documentation.i"

E il suo fatto.