क्या स्विग इंटरफेस के लिए प्रलेखन तैयार करने का कोई अच्छा तरीका है?

Question

मैं जानना चाहता हूं कि इंटरफ़ेस पर दस्तावेज़ बनाने/बनाए रखने के लिए कोई अच्छी तकनीक है या नहीं।

मैं स्विंग का उपयोग कर सी ++ कोड से पायथन तक एक इंटरफ़ेस बना रहा हूं; ज्यादातर मैं सी ++ हेडर फाइलों सहित % हूं। मैं कम से कम दर्जनों कक्षाओं और 100 कार्यों के साथ काम कर रहा हूं, इसलिए स्वचालित उपकरण को प्राथमिकता दी जाती है।

आदर्श रूप में, मैं C++ शीर्षकों में डॉक्सिजन स्वरूपित टिप्पणियों का उपयोग पर पाइथन कक्षाओं/विधियों में डॉकस्ट्रिंग को पॉप्युलेट करना चाहता हूं।

वैकल्पिक रूप से, अलग-अलग दस्तावेज उत्पन्न करना (एसीआईआई, एचटीएमएल ...) भी उपयोगी होगा। ऐसा लगता है कि इस तरह की कार्यक्षमता को स्विग के पहले संस्करणों (1.3 और इससे पहले) में समर्थित थी, लेकिन मुझे 2.0 के साथ करने का कोई तरीका नहीं दिख रहा है।

क्या इंटरफ़ेस को दस्तावेज करने के लिए कोई उपयोगी (स्वचालित) तकनीकें हैं?

Answer 1

SWIG 2.0 के साथ %feature("autodoc") में कुछ लाभ है, जो मुझे लगता है कि यह वर्तमान में है।

उदाहरण के लिए:

%module test 

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

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

कुछ अस्पष्ट समझदार प्रलेखन का कारण बनता है सम्मिलित करने के लिए।

अगर वह पर्याप्त नहीं है मुझे लगता है कि अगले सबसे आसान कदम %pythonprepend उपयोग करने के लिए एक मार्कर में अनूठा है कि बनाने के लिए किया जाएगा पर्याप्त sed या इसी तरह के बाद बड़ा घूँट स्वचालित रूप से समाप्त हो गया है इंटरफ़ेस में प्रलेखन डालने के लिए इस्तेमाल किया जा सकता:

%pythonprepend foo "MARKER" 

और उसके बाद:

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

कहाँ आप स्क्रिप्ट एक (अजगर?) का उपयोग कर मार्करों पैदा करते हैं और आर के बाद उन्हें स्थानापन्न करने Doxygen उत्पादन से अधिक देखकर %pythonprepend के कार्यों मिल सकता है एसएनआईजी unning।

Answer 2

पायथन फाइलों में अपनी डॉक्सिजन टिप्पणियां प्राप्त करने के लिए वेब पर doxy2swig.py नामक एक अजगर टूल मौजूद है जैसा कि here वर्णित है।

अपने कोड से एक्सएमएल दस्तावेज बनाएं। तब उपकरण का उपयोग:

doxy2swig.py index.xml

और आयात documentation.i documentation.i आप

% आयात के माध्यम से इंटरफेस फ़ाइल बड़ा घूँट में "documentation.i"

और यह किया गया।