doxygen उद्देश्य-सी दस्तावेज़ीकरण जेनरेटर: हेडरडॉक बनाम डॉक्सीजन बनाम ऐप्पलडॉक




documentation-generation headerdoc (3)

एक्सकोड 5 अब दस्तावेजों की खोज करने और इसे प्रदर्शित करने के लिए आपकी टिप्पणियों का विश्लेषण करेगा:

आपको अब सेबडोक या डॉक्सिजन का उपयोग करने की आवश्यकता नहीं है (कम से कम जब आप अपने दस्तावेज़ निर्यात नहीं करना चाहते हैं)। अधिक जानकारी here मिल सकती here

मुझे अपने कार्यस्थल के लिए एक दस्तावेज उत्पादन समाधान लागू करने की आवश्यकता है और इसे शीर्षक में उल्लिखित तीनों तक सीमित कर दिया है। मैं इन समाधानों के बीच औपचारिक तुलना के तरीके में बहुत कम जानकारी प्राप्त करने में सक्षम हूं, और मुझे उम्मीद है कि आप में से एक या अधिक में अनुभव वाले अनुभवों में वजन हो सकता है:

यहां मैं अपने प्रारंभिक पास से प्राप्त करने में सक्षम हूं:

हेडरडॉक प्रोस: सेब के मौजूदा दस्तावेज़ों के साथ संगत, सेब डॉक्ससेट बनाने के साथ संगतता
हेडरडॉक विपक्ष: व्यवहार को संशोधित करने में मुश्किल, परियोजना सक्रिय रूप से काम नहीं कर रही है, कई ने इसे से दूर कर दिया है (जिसका अर्थ है कि कुछ कमी होनी चाहिए, हालांकि मैं इसे प्रमाणित नहीं कर सकता)।

डॉक्सिजन प्रोस: व्यापक उपयोग आधार के सक्रिय समर्थन समुदाय बी / सी, बहुत अनुकूलन, अधिकांश आउटपुट प्रकार (जैसे लेटेक्स आदि)
डॉक्सिजन विपक्ष: सेब डॉक्स के साथ संगत दिखने / व्यवहार करने के लिए काम करता है, सेब डॉक्ससेट के साथ संगतता उतनी सरल नहीं है

ऐप्पलडॉक प्रोस: सेब के मौजूदा दस्तावेज़ों, सेब डॉक्ससेट बनाने के साथ संगतता के साथ संगत दिखता है,
ऐप्पलडोक विपक्ष: सक्रिय रूप से विकसित किए जा रहे टाइपिफ, एनम्स और कार्यों के दस्तावेज़ीकरण के साथ समस्या

क्या यह सही लगता है? हमारे वांछित समाधान होगा:

  • सेब के उद्देश्य से सी वर्ग संदर्भ के साथ लगातार देखो और महसूस करें
  • एक्सकोड के भीतर से दस्तावेज़ीकरण संदर्भ खींचने के लिए विकल्प-क्लिक करने की क्षमता, और उसके बाद दस्तावेज़ से लिंक करें (बस सेब की कक्षाओं की तरह)
  • श्रेणियों, एक्सटेंशन, और जैसे (सेब की कक्षाओं की कस्टम श्रेणियां) की स्मार्ट हैंडलिंग
  • अपने स्वयं के संदर्भ पृष्ठों को बनाने की क्षमता (इस पृष्ठ की तरह: लोड हो रहा है ... जिसमें छवियां शामिल हो सकती हैं, और जेनरेट क्लास संदर्भों से सहजता से लिंक करने योग्य हो सकती हैं, जैसे कि सेब के UIViewController क्लास संदर्भ पृष्ठ से लिंक कैसे लिंक करता है।
  • कमांड लाइन कमांड चलाने के लिए आसान है जिसे बिल्ड स्क्रिप्ट में एकीकृत किया जा सकता है
  • बहुत बड़े कोडबेस की गहन हैंडलिंग

उपर्युक्त सभी सूचनाओं के आधार पर, उपर्युक्त समाधानों में से कोई भी दूसरों की तुलना में स्पष्ट रूप से बेहतर है? जोड़ने के लिए कोई सुझाव या जानकारी अत्यधिक सराहना की जाएगी।


डॉक्सिजन के निर्माता और लीड डेवलपर के रूप में, मुझे अपना परिप्रेक्ष्य भी प्रदान करने दें
(स्पष्ट रूप से पक्षपातपूर्ण भी ;-)

यदि आप ऐप्पल की अपनी प्रलेखन शैली की 100% वफादार प्रतिकृति की तलाश में हैं, तो उस संबंध में ऐप्पलडॉक बेहतर विकल्प है। डॉक्सिजन के साथ आपको वही दिखने के लिए कठिन समय लगेगा, इसलिए मैं कोशिश करने की अनुशंसा नहीं करता।

एक्सकोड डॉक्ससेट के संबंध में; ऐप्पल instructions प्रदान करता है कि इसे डॉक्सिजन के साथ कैसे सेट करें (उस समय लिखा गया था जब एक्सकोड 3 जारी किया गया था)। एक्सकोड 4 के लिए डॉक्सिजन को एकीकृत करने के लिए एक अच्छी मार्गदर्शिका भी है।

संस्करण 1.8.0 के अनुसार, डॉक्सिजन मार्कडाउन मार्कअप का समर्थन करता है, साथ ही अतिरिक्त markup कमांड की एक बड़ी संख्या भी।

डॉक्सिजन के साथ आप मुख्य पृष्ठ (@mainpage) के साथ-साथ उपपृष्ठों (@subpage या @page का उपयोग करके) पर दस्तावेज़ शामिल कर सकते हैं। एक पृष्ठ के अंदर आप अनुभाग और उपखंड बना सकते हैं। वास्तव में, डॉक्सिजन का उपयोगकर्ता मैनुअल पूरी तरह से डॉक्सिजन का उपयोग करके लिखा गया था। इसके अलावा, आप कक्षाओं या कार्यों को एक साथ समूहित कर सकते हैं (@defgroup और @ingroup का उपयोग करके) और कक्षा के अंदर कस्टम अनुभाग (@name का उपयोग करके) बनाते हैं।

Doxygen एक विन्यास फाइल इनपुट के रूप में उपयोग करता है। आप doxygen -g का उपयोग कर डिफ़ॉल्ट मानों के साथ एक टेम्पलेट जेनरेट कर सकते हैं या एक बनाने और संपादित करने के लिए आलेखीय संपादक का उपयोग कर सकते हैं। आप डॉक्सिजन का उपयोग कर स्क्रिप्ट के माध्यम से डॉक्सिजन के माध्यम से पाइप विकल्प भी पा सकते हैं doxygen - (उदाहरण के लिए FAQ प्रश्नों के प्रश्न 17 देखें)

Doxygen उद्देश्य-सी तक सीमित नहीं है, यह सी, सी ++, और जावा सहित भाषाओं की एक बड़ी श्रृंखला का समर्थन करता है। डॉक्सिजन मैक प्लेटफॉर्म तक ही सीमित नहीं है, उदाहरण के लिए यह विंडोज और लिनक्स पर भी चलता है। डॉक्सिजन का आउटपुट सिर्फ HTML से अधिक का समर्थन करता है; आप पीडीएफ आउटपुट (लाटेक्स के माध्यम से) या आरटीएफ और मैन पेज उत्पन्न कर सकते हैं।

डॉक्सिजन भी शुद्ध दस्तावेज से परे चला जाता है; डॉक्सिजन स्रोत कोड से विभिन्न ग्राफ और आरेख बना सकते हैं ( dot से संबंधित विकल्प देखें)। डॉक्सिजन आपके कोड का एक ब्राउज़ करने योग्य और वाक्यविन्यास हाइलाइट संस्करण भी बना सकता है, और क्रॉस-रेफरेंस जो दस्तावेज़ीकरण के साथ ( स्रोत ब्राउज़र से संबंधित विकल्प देखें)।

छोटे से मध्यम आकार की परियोजनाओं के लिए डॉक्सिजन बहुत तेज़ है (आरेख पीढ़ी हालांकि धीमी हो सकती है, लेकिन आजकल कई सीपीयू कोर पर समानांतर में चलता है और अगले भाग में एक रन से ग्राफ का उपयोग किया जाता है)। बहुत बड़ी परियोजनाओं के लिए (उदाहरण के लिए कोड की लाखों लाइनें) डॉक्सिजन परियोजनाओं को कई हिस्सों में विभाजित करने की अनुमति देती है और फिर मैंने समझाया कि भागों को एक साथ जोड़ सकते here

उद्देश्य-सी के लिए डॉक्सिजन का उपयोग करने का एक अच्छा वास्तविक जीवन उदाहरण here पाया जा सकता here

डॉक्सिजन का विकास अत्यधिक उपयोगकर्ता प्रतिक्रिया पर निर्भर करता है। हमारे पास प्रश्नों और चर्चाओं और बग और फीचर अनुरोधों के लिए एक बग ट्रैकर के लिए एक सक्रिय मेलिंग सूची है

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

ध्यान दें कि मैं लगभग सभी डॉक्सिजन विकास और मैक पर सबसे अधिक परीक्षण करता हूं।


मैं एप्लाडोक का लेखक हूं, इसलिए यह जवाब पक्षपातपूर्ण हो सकता है :) मैंने सभी उल्लिखित जनरेटर को (और अधिक) कोशिश की लेकिन निराश हो गया क्योंकि कोई भी उत्पादित परिणाम नहीं था (जैसा कि आप के समान लक्ष्य थे)।

आपके अंक के अनुसार (मैं केवल एप्लाडोक और डॉक्सिजन का उल्लेख करता हूं, मैं हेडरडोक को अच्छी तरह से याद नहीं करता):

  1. लगातार देखो: बॉक्स से सेबडोक, सीएसएस को ट्विक करने की अन्य आवश्यकता, लेकिन संभवतः करने योग्य।

  2. प्रलेखन सेट का निर्माण (एक्सकोड संदर्भों के लिए): बॉक्स के बाहर खोजने योग्य और विकल्प-क्लिक करने योग्य दस्तावेज़ीकरण के लिए एप्लाइडोक पूर्ण समर्थन, डॉक्सिजन xml और मेकफ़ाइल उत्पन्न करता है जिसे आपको स्वयं को आमंत्रित करने की आवश्यकता होती है। इसके अतिरिक्त एप्लाडोक बॉक्स के बाहर प्रकाशित डॉक्ससेट का समर्थन करता है।

  3. श्रेणियाँ: एप्लाडोक आपको ज्ञात कक्षाओं में श्रेणियों को मर्ज करने या उन्हें अलग करने की अनुमति देता है, नींव और अन्य सेब वर्ग श्रेणियां इंडेक्स फ़ाइल में अलग-अलग सूचीबद्ध हैं। डॉक्सिजन: जब मैंने कोशिश की तो यह सबसे अच्छा काम नहीं कर रहा था।

  4. कस्टम संदर्भ पृष्ठ: एप्पलडॉक या तो मार्कडाउन या कस्टम एचटीएमएल, डॉक्सिजन supports उपयोग कर बॉक्स से बाहर का supports है: आप मुख्य पृष्ठ पर कस्टम दस्तावेज़ शामिल कर सकते हैं, यह नहीं पता कि आप और पेज शामिल कर सकते हैं या नहीं।

  5. आसान कमांड लाइन: इस पर निर्भर करता है कि आप इसे कैसे देखते हैं: सेबडोक कमांड लाइन स्विच के माध्यम से सभी तर्क ले सकता है (लेकिन वैकल्पिक वैश्विक और प्रोजेक्ट सेटिंग्स प्लिस्ट फाइलों का भी समर्थन करता है) ताकि बिल्ड स्क्रिप्ट के साथ एकीकृत करना बहुत आसान हो। डॉक्सिजन को सभी पैरामीटर सेट अप करने के लिए कॉन्फ़िगरेशन फ़ाइल का उपयोग करने की आवश्यकता होती है।

  6. बड़े कोडबेस: सभी औजारों का समर्थन करना चाहिए, हालांकि इसी तरह तुलना नहीं की गई थी। यह भी सुनिश्चित नहीं है कि कोई उपकरण कैश किए गए मानों का समर्थन करता है (कुछ समय बचाने के लिए पहले एकत्रित डेटा पर चल रहा है) - मैं इसे अगली बड़ी रिलीज के लिए जोड़ने में देख रहा हूं।

यह कुछ समय है जब मैंने अन्य टूल्स का उपयोग करने की कोशिश की, इसलिए डॉक्सिजन / हेडरडोक के साथ ऊपर उल्लिखित मुद्दों को संबोधित किया जा सकता है! सेबडोक के पास भी नुकसान होते हैं: जैसा कि आप उल्लेख करते हैं कि enums, structs, फ़ंक्शंस इत्यादि के लिए कोई समर्थन नहीं है (इस दिशा में कुछ काम किया गया था, इस कांटा की जांच करें ), और इसमें स्वयं के मुद्दों का एक सेट है जो आपको इसका उपयोग करने से रोक सकता है आपकी जरुरतें।

मैं वर्तमान में बड़े अपडेट पर काम कर रहा हूं जिसमें सबसे अधिक चमकदार मुद्दों को शामिल किया जाएगा, जिसमें enums, structs इत्यादि के लिए समर्थन शामिल है। जैसे ही मैं बड़े हिस्से को पूरा करता हूं और इसे पर्याप्त स्थिर करता हूं, मैं नियमित रूप से प्रयोगात्मक शाखा में नई सामग्री को दबा रहा हूं, ताकि आप इसका अनुसरण कर सकें प्रगति। लेकिन यह अभी भी बहुत जल्दी है और प्रगति मेरे समय पर निर्भर करती है, इसलिए कामकाजी समाधान तक इसमें कुछ समय लग सकता है।