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

Question

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

यहां मेरे पास है मेरी प्रारंभिक पास से बटोरने के लिए सक्षम किया गया:

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

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

AppleDoc पेशेवरों नहीं है: सेब के मौजूदा डॉक्स के साथ संगत लगता है, सेब docsets,
AppleDoc विपक्ष बनाने के साथ अनुकूलता:, typedefs, enums, और कार्यों का प्रलेखन के साथ अंक सक्रिय रूप से विकसित किया जा रहा

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

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

उपर्युक्त सभी जानकारियां के आधार पर की

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

Answer 1

निर्माता और Doxygen का नेतृत्व डेवलपर के रूप में, मुझे भी मेरी परिप्रेक्ष्य
(स्पष्ट रूप से और साथ ही ;-)

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

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

संस्करण 1.8.0 के रूप में, डॉक्सिजन Markdown markup का समर्थन करता है, साथ ही बड़ी संख्या में अतिरिक्त markup आदेशों का समर्थन करता है।

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

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

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

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

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

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

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

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

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

Answer 2

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

अपने अंक अनुसार (मैं केवल appledoc और Doxygen का उल्लेख है, मैं headerdoc याद नहीं है कि अच्छी तरह से):

1. लगातार नज़र ।

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

3. वर्ग: appledoc जाना जाता वर्गों के लिए merge categories करने की अनुमति देता है या छोड़ उन्हें अलग, नींव & अन्य सेब वर्ग श्रेणियों index file में अलग-अलग सूचीबद्ध कर रहे हैं। डॉक्सिजन: जब मैंने कोशिश की तो यह सबसे अच्छा काम नहीं कर रहा था।

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

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

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

कुछ समय के बाद से मैं, अन्य उपकरणों का उपयोग करने की कोशिश की तो उल्लेख किया मुद्दों से ऊपर के साथ Doxygen/headerdoc संबोधित किया गया है हो सकता है है! एप्लाडोक के पास भी नुकसान हैं: जैसा कि आप उल्लेख करते हैं कि enums, structs, functions आदि के लिए कोई समर्थन नहीं है (इस दिशा में कुछ काम किया गया था, check this fork), और इसकी अपनी set of issues है जो आपकी आवश्यकताओं के आधार पर इसका उपयोग करने से रोक सकती है।

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

Answer 3

Xcode 5 अब प्रलेखन के लिए खोज और यह प्रदर्शित करने के लिए अपनी टिप्पणी को पार्स होगा:

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