संस्करणिंग के पेशेवरों और विपक्ष javadoc

Question

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

मैंने एसवीएन के अच्छे प्रथाओं के बारे में पढ़ा है, जिसमें SO पर कई रोचक प्रश्न शामिल हैं, लेकिन विशेष रूप से किसी भी को विशेष रूप से जावाडोक हैंडलिंग पर नहीं पूछा गया है।

पहले तो मुझे तर्क है कि केवल स्रोत कोड संस्करणीकृत किया जाना चाहिए के साथ सहमत हो गया था, और मैंने सोचा कि जावाडोक था वास्तव में ग्रहण के साथ है फिर से निर्माण, या उदाहरण के लिए एक javadoc.xml चींटी फ़ाइल से आसान है, लेकिन मैं यह भी सोचा इन बिंदुओं में से:

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

इस बारे में आपके विचार क्या हैं? कृपया रचनात्मक, गैर-व्यक्तिपरक तर्कों के साथ उत्तर दें। मुझे यह समझने में दिलचस्पी है कि कौन सा केस परिदृश्य जवाडोक के संस्करण को प्रोत्साहित करता है, और जो इसे खराब विकल्प लगता है।

Answer 1

विरोध के खिलाफ एक तर्क विवादों को मर्ज करेगा, और एक पूर्व एसवीएन उपयोगकर्ता के रूप में मुझे एसवीएन के साथ विलय करने से नफरत है। गिट के साथ भी यह समस्या तब होती है जब वे समस्याएं होती हैं। और यदि आपकी बड़ी टीम नियमित रूप से विलीन हो जाती है तो दैनिक काम होता है।

कुछ अन्य लोगों के खिलाफ एक और तर्क होगा, अगर कुछ लोग पूरे स्रोत पेड़ नहीं चाहते हैं, तो पूरे प्रोजेक्ट को हडसन जैसे कुछ सीआई सिस्टम के तहत रखें और नियमित आधार पर जावाडॉक्स के निर्माण को ट्रिगर करें, जैसे उन्हें काम करना और प्रकाशित करना कहीं।

मेरे लिए निष्कर्ष है: संस्करण javadocs नहीं है।

Answer 2

संक्षिप्त उत्तर: नहीं, अपने जावाडॉक्स को संस्करण न बनाएं।

Javadocs आपके कोड से उत्पन्न होते हैं, जो आपके .class फ़ाइलों के समान होते हैं। यदि आपका एपीआई बदलता है और आपको दस्तावेज़ों का एक नया संस्करण जारी करने की आवश्यकता है, तो आप हमेशा उस संशोधन (या एक नया चेक आउट) पर वापस जा सकते हैं और वहां से जावाडॉक्स उत्पन्न कर सकते हैं।

Answer 3

मेरे दो सेंट ...

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

यह पुस्तकालयों आप अपने खुद के आंतरिक कोड के साथ की तुलना में वितरित की एक समस्या की शायद और अधिक है, लेकिन यह कुछ मैं में अब चलाने है और फिर से

Answer 4

मैं हाल ही में एक संस्करण नियंत्रण प्रणाली के लिए कुछ जावाडोक उत्पादन जोड़ा (है चूंकि जिथब एक वेबसाइट के रूप में शाखा gh_pages की सामग्री दिखाता है, यह put them on the web का सबसे आसान तरीका था)।

एक समस्या यह है कि यहाँ जावाडोक हर जावाडोक रन की तारीख/समय फ़ाइल में डालता है, ताकि आप हमेशा अपने सभी फाइलों को एक commit से अगलेमें परिवर्तन है। इसलिए एक उपयोगी अंतर प्राप्त करने में सक्षम होने की अपेक्षा न करें जो आपको दिखाता है कि आपके संस्करणों के बीच वास्तव में कौन सा दस्तावेज़ बदल गया है, जब तक कि आप अलग-अलग होने पर इन टिप्पणी पंक्तियों को किसी भी तरह से अनदेखा न करें। (असल में, एक और प्रश्न I found out how to omit टाइमस्टैम्प के कारण।)

और निश्चित रूप से, आपको हमेशा पुराने स्रोतों के चेकआउट से अपने जावडोक को पुन: उत्पन्न करने में सक्षम होना चाहिए। और जारी पुस्तकालयों के लिए, इसके साथ जारी संस्करण के जावाडोक को प्रचारित करें।

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