क्या जवादोक के लिए कुछ अच्छे और आधुनिक विकल्प हैं? [बन्द है]

Question

आइए इसका सामना करें: आपको यह देखने के लिए एक डिजाइनर होने की आवश्यकता नहीं है कि डिफ़ॉल्ट Javadoc बदसूरत दिखता है ।

वेब पर कुछ संसाधन हैं जो Javadoc को फिर से स्टाइल करते हैं। लेकिन डिफ़ॉल्ट व्यवहार उत्पाद का प्रतिनिधित्व करता है और यथोचित रूप से अच्छा दिखना चाहिए।

एक अन्य समस्या यह है कि अन्य समान संसाधनों की तुलना में जावदोक की उपयोगिता अप-टू-डेट नहीं है।

विशेष रूप से बड़ी परियोजनाओं को फ़ायरफ़ॉक्स की त्वरित खोज का उपयोग करके नेविगेट करना मुश्किल है।

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

सैद्धांतिक प्रश्न:
क्या किसी को पता है, अगर किसी तरह से मानकीकृत तरीके से जावदोक को विकसित करने की योजना है?
EDIT: इस विषय पर सूर्य की विकि के लिए एक उपयोगी कड़ी ।

Comments

मुझे खुशी होगी अगर javadoc वैध HTML 4.01 या XHTML पृष्ठ उत्पन्न करेगा।

— एकरनोकद

आपको क्या समस्या है?

— बेजरोजो

कोई इसे क्यों कम करेगा? मुझे लगता है कि यह एक उचित प्रश्न है: +1

— डैनियल स्लॉफ़

(X) HTML Javadoc के लिए एकमात्र तरीका नहीं होना चाहिए। ब्राउज़र (स्थानीय) ज्ञान के आधार तक पहुँचने के लिए एक बहुत ही सीमित साधन है।

— ivan_ivanovich_ivanoff

मुझे व्यक्तिगत रूप से जावदोक पसंद है। यह स्पष्ट, संक्षिप्त और बिंदु तक है। दूसरी ओर MSDN साइट ...

— samoz

Answer 1

मैंने एक Markdown (java) Doclet बनाया है, जो Markdown के स्वरूपित पाठ में स्रोत टिप्पणियाँ लेगा और उसी HTML Javasocs का निर्माण करेगा।

नया डॉकलेट पाठ पर कुछ संयम भी करता है, लेकिन इस स्तर पर उत्पन्न HTML नहीं बदला जाता है।

यह HTML-in-java-commenting मुद्दों को संबोधित करने के लिए किसी तरह से जाता है जो वर्तमान जावेदोक के साथ शायद सबसे बड़ी प्रयोज्य समस्या है।

Answer 2

मुझे नहीं लगता कि जावदोक की अवधारणाएं पुरानी हैं। जहाँ तक मैं देख सकता हूँ, ये अवधारणा वर्षों पहले डॉक्सिज़न नाम के एक उत्पाद में निहित है, जो अभी भी अन्य भाषाओं के लिए उपलब्ध है (यानी ऑब्जेक्टिव-सी जहाँ इसका भारी उपयोग होता है)। यहां तक ​​कि यह पूर्ववर्ती है - TeX ( साक्षर प्रोग्रामिंग ) बनाने के लिए डोनाल्ड नूथ द्वारा उपयोग किए जाने वाले प्रोग्रामिंग वातावरण पर एक नज़र है ।

फिर भी यह प्रोग्राम कोड और प्रलेखन के लिए एक स्रोत होने के लिए एक पेचीदा विचार है।

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

Comments

कृपया ScalaDoc2 scala-lang.org/api/current पर एक नज़र डालें और फिर कहें कि जवादोक पुराना नहीं है। :-) हालाँकि मैं मानता हूँ कि यह मूल अवधारणाएँ कमोबेश एक बेहतर कार्यान्वयन है। एक शायद javadoc उपकरण के नए कार्यान्वयन के साथ भी ऐसा ही कर सकता है।

— हंस-पीटर स्टॉपर

Answer 3

Javadoc सबसे अच्छा स्रोत कोड ऑटो-प्रलेखन पीढ़ी प्रणाली है जिसे मैंने कभी देखा है। इसका बड़ा हिस्सा यह है कि यह बहुत सरल है - मैं अपने 5 साल पुराने सेल फोन के साथ भी javadocs ब्राउज़ कर सकता हूं यदि मैं चाहता हूं! हालांकि मैं मानता हूं कि थोड़ा सा फेसलिफ्ट क्रम में हो सकता है और विशेष रूप से JDK के माध्यम से ब्राउज़ करने के लिए एक दर्द है, मैं पहिया को पूरी तरह से मजबूत करने की हिम्मत नहीं करूंगा क्योंकि हमारे पास वर्तमान में एक RESTful है, इसके उद्देश्य के लिए समाधान का उपयोग करना आसान है जो काम करता है बस के बारे में कहीं भी।

Comments

खैर, इस समस्या के साथ कि अंतर-पृष्ठ लिंक (जैसे http://download.oracle.com/javase/6/docs/api/java/lang/String.html#String(byte[])) अमान्य हैं क्योंकि वे कोष्ठक, कोष्ठक और अन्य वर्णों का उपयोग करते हैं जिनकी अनुमति नहीं है। यह उन्हें कुछ ब्राउज़रों में तोड़ने का कारण बनता है।

— जॉय

BTW, इस टिप्पणी के लिए एक अद्यतन, मैं वास्तव में आजकल लगता है कि scaladoc2 (देखें scala-lang.org/api/current/index.html ) वास्तव में javadoc से बेहतर है, हालांकि ज्यादातर क्योंकि यह javadocs के अच्छे हिस्सों को उधार लेती है और फिर जोड़ता है वहाँ कुछ अन्य निफ्टी चीजें।

— एस्को

फिर भी एक और अद्यतन, जावाडोक प्रणाली JDK7 में पूरी तरह मरम्मत की गई और संदर्भ के लिए आजकल बल्कि spiffy लग रहा है, पर सरकारी एपीआई जावाडोक जाँच download.oracle.com/javase/7/docs/api

— Esko

हाँ, लेकिन यह इतना ही है!

— जिग्गी

@Ziggy तब अपना खुद का CSS बनाये या एक बिलकुल अनोखा doc पेज बनाने के लिए aforementioned API का उपयोग करे? : P

— Esko

Answer 4

मुझे हाल ही में एक मेल मिला जिसमें लिखा था कि सन जावदोक एचटीएमएल आउटपुट को आधुनिक बनाने पर काम कर रहा है। उक्त मेल से:

हम JDK7 के लिए javadoc / doclet में सुधार का प्रस्ताव कर रहे हैं। प्रोजेक्ट विकी पेज http://wikis.sun.com/display/Javadoc/Home पर स्थित है । प्रस्तावित सुधारों के एक हिस्से के रूप में, javadoc आउटपुट के UI को नया रूप दिया जाएगा। नए डिजाइन के स्क्रीनशॉट प्रोजेक्ट विकी पर अपलोड किए गए हैं। Javadoc आउटपुट मार्कअप को मान्य HTML और WCAG 2.0 अनुरूप होने के लिए संशोधित किया जाएगा।

तो वहाँ निश्चित रूप से काम चल रहा है, भले ही कुछ देर हो। हालांकि, मेरी नज़र में, Javadoc की सबसे बड़ी कमियों में से एक HTML के साथ इसकी बहुत करीबी युग्मन है। कई वर्गों में जावदोक है जिसमें शाब्दिक एचटीएमएल शामिल है और आउटपुट एचटीएमएल पर भी निर्भर करता है। दुर्भाग्यपूर्ण है, लेकिन यह कभी भी नहीं बदलेगा, मुझे लगता है। फिर भी, इसका मतलब यह है कि डेवलपर्स को HTML में जो कुछ भी चाहिए उसे शामिल करने के लिए स्वतंत्र हैं जो कि अमान्य, गैर-अच्छी तरह से गठित आदि हो सकते हैं, इसलिए javadoc टूल से आउटपुट को अपनाना इस का केवल एक हिस्सा है, दूसरा जीता ' टी और बदल नहीं सकता है और इस प्रकार रहता है।

ब्राउज़िंग प्रलेखन के लिए के रूप में मैं भी HTML प्रलेखन एक छोटे से खोजा। मैं आमतौर पर ग्रहण में जावदोक दृश्य का उपयोग करता हूं। इसमें कमियां भी हैं (धीमी गति से और आप वास्तव में खोज नहीं कर सकते हैं) लेकिन यह ज्यादातर चीजों के लिए गुड एनफ ™ है।

Comments

बढ़िया खबर !!! धन्यवाद !!! मैं अब इस उपयोगी लिंक को प्रदान करने के लिए अपने प्रश्न को संपादित करूंगा।

— ivan_ivanovich_ivanoff

@ivan_ivanovich_ivanoff, शायद आप सूर्य टीम के साथ भी अपनी चिंताओं को आवाज़ दे सकते हैं। लगता है कि अगर वे आपको खुश कर सकते हैं, तो इससे हम सभी को फायदा होगा।

— थोरबजोरन रेव एंडरसन

Answer 5

व्यक्तिगत रूप से मुझे अभी भी जावदोक बहुत उपयोगी लगता है। खासकर जब से यह मानकीकृत है। मैं किसी भी प्रमुख प्रलेखन शैली के बारे में नहीं जानता, जो मुझे नेविगेट करने में आसान लगता है (जो कि बहुत अच्छी तरह से व्यक्तिपरक हो सकती है, लेकिन मैं व्यक्तिगत रूप से एमएसडीएन को उपयोग करने के लिए भयानक पाता हूं, उदाहरण के लिए)।

खोज के लिए: Javadoc सर्च फ़्रेम का उपयोग करें , यह सभी प्रकार के Javadoc का उपयोग करना बहुत आसान बनाता है। यह फ़ायरफ़ॉक्स के लिए एक यूजरस्क्रिप्ट और Google क्रोम एक्सटेंशन के रूप में उपलब्ध है ।

Comments

यह मुझे ऐसा लगता है कि जावदोक सर्च फ्रेम केवल बाएं हाथ के फ्रेम में पैकेज और क्लास के नामों पर खोज करता है, जो उपयोगी है, लेकिन एक पूर्ण पाठ खोज जितना उपयोगी नहीं होगा।

— ग्लेन लॉरेंस

Answer 6

आपके प्रैक्टिकल सवाल का जवाब देने के लिए, मैंने दोस्तों से गुहार लगाई और उनसे पूछा। फॉरेस्टडॉक, डॉकलेट और डॉक्सीजेन।

दूसरा सवाल, मैं यह कहूंगा कि हां, इसका बहुत "वेब-ओह-टूय" नहीं है, लेकिन कम से कम एक ऑफ़लाइन वातावरण में काम करने की आपकी गारंटी है, और यह आपके एपीआई के साथ जहाज करने के लिए पर्याप्त छोटा है। मैं तख्ते के उपयोग को विवादित करता हूं, लेकिन फिर यह javadoc के लिए अच्छी तरह से काम करता है। मैंने इसे बदलने की कोई योजना नहीं देखी है। ग्रहण को पढ़ने, व्याख्या करने और उसे उत्पन्न करने के लिए जहाँ तक जावदोक का कुछ समर्थन है।

Answer 7

आप यह कहना चाहते हैं कि कम आक्रामक और जबर्दस्त तरीके से बात कर सकते हैं। ज्यादातर लोगों को परवाह नहीं है कि तकनीकी संसाधन कैसा दिखता है, और "यह वेब 2.0 पर्याप्त नहीं है!" वैपिड मार्केट्रायस्पेक की तरह लगता है।

और क्या वास्तव में आप "अधिक उपयोगी" पर विचार करेंगे? व्यक्तिगत रूप से, मैं निश्चित रूप से एक पूर्ण पाठ खोज और बेहतर उपयोग करने वाला ब्राउज़र चाहूंगा, और AJAX उन लोगों के साथ संभावित मदद कर सकता है।

खैर, JavaDoc के बारे में अच्छी बात यह है कि यह पुरानी के विपरीत है - यह मनमाने ढंग से एक्स्टेंसिबल है। आप आगे क्यों नहीं जाते हैं और एक डॉकलेट लिखते हैं जो एपीआई डॉक्स की तरह का उत्पादन करता है जो आप चाहते हैं?

किसी और ने ऐसा क्यों नहीं किया जो अब तक (जो कि जाहिर तौर पर मामला है) किसी का अनुमान है - शायद कोई और आपके बारे में उतना दृढ़ता से महसूस नहीं करता।

Comments

1) यह एक तथ्य है कि प्रयोज्य के प्रति लोगों की धारणा अच्छे डिजाइन पर निर्भर करती है। 2) AJAX - एक स्थानीय फ़ाइल के लिए: // संसाधन? 3) मुझे यकीन है, सी / सी ++ पारिस्थितिकी तंत्र में कोई भी लगातार नामकरण के बारे में दृढ़ता से महसूस नहीं करता है जैसा कि मैं करता हूं, लेकिन यह लगातार नामकरण की जरूरतों को अमान्य नहीं करता है।

— ivan_ivanovich_ivanoff

1) वास्तव में आप "अच्छे डिजाइन" पर क्या विचार करेंगे? मैं, एक के लिए, नियमित जावाडॉक को अच्छी तरह से डिज़ाइन किया गया है। 2) वास्तविक AJAX नहीं होगा, मुझे लगता है, लेकिन समान कार्यक्षमता वास्तव में संभव होनी चाहिए। 3) फिर भी, ऐसा लगता है कि वर्तमान JavaDoc अधिकांश लोगों के लिए काफी अच्छा है कि किसी ने भी अब तक एक बेहतर बनाने की जहमत नहीं उठाई है - जो कि मुश्किल नहीं होगा।

— माइकल बोर्गवर्ड

1) मानक हिस्सा: दृढ़ता से संरचित डेटा, HTML नहीं। कार्यान्वयन हिस्सा: जावा में लिखा गया एक डेस्कटॉप ऐप;) 3) मुझे लगता है कि कई स्वयंसेवकों को जावदोक में सुधार करने के लिए पाया जा सकता है, लेकिन इसे गंभीर बनाने के लिए एक जेएसआर की आवश्यकता होगी। इस विषय को प्राप्त करने के लिए यथार्थवादी नहीं।

— ivan_ivanovich_ivanoff

@ivan_ivanovich_ivanoff: आपको क्या लगता है कि किस स्ट्रक्चर्ड स्ट्रक्चर्ड डेटा की ज़रूरत है? और क्यों नहीं एक javadoc-doclet लिख रहा है, जो इस प्रारूप का उत्पादन करता है? और मैं एक डेस्कटॉप-ऐप के विचार का विरोध करता हूं, क्योंकि यह दस्तावेज़ देखने के लिए आपको विशिष्ट ऐप पर लॉक कर देता है।

— स्नेही

Answer 8

एक डॉकबुक डॉलेट है। DocBook HTML (X) HTML से अधिक समृद्ध दस्तावेज़ प्रकार है और तकनीकी सामग्री का वर्णन करने के लिए बेहतर है। DocBook स्रोत से आप विभिन्न प्रकार के आउटपुट स्वरूप तैयार कर सकते हैं।

Answer 9

मैं व्यक्तिगत रूप से HTML (और इसलिए टैग-फ़ील्ड) JavaDoc की तुलना में अधिक पठनीय "टिप्पणी प्रलेखन" मानक चाहूंगा।

उदाहरण के लिए, मार्कडाउन, जैसा कि यहां इस्तेमाल किया गया है, स्रोत में उत्कृष्ट, मानव पठनीय होगा, स्रोत के लिए अच्छी तरह से स्वरूपित बाहरी।

वर्तमान JavaDoc के साथ, मुझे लगता है कि बहुत से लोग JavaDoc टिप्पणियों का उपयोग करते हैं, लेकिन वास्तव में उस हद तक दस्तावेज़ नहीं करते हैं जो वे कर सकते थे। मुझे यकीन है कि हर किसी ने एपीआई के ऑनलाइन जावाडॉक को ब्राउज किया है जो गैर-दस्तावेज या मुश्किल से प्रलेखित किया गया है, और इस तरह इसका उपयोग करने की तुलना में कहीं अधिक कठिन है।

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

Answer 10

क्या कोई जानता है, अगर किसी तरह से मानकीकृत तरीके से जावदोक को विकसित करने की कुछ योजनाएं हैं?

इसी JSR (JSR 260), जो कि Javadoc को एन्हांसमेंट निर्दिष्ट करता है, को JDK 7 (अभी के लिए) से बाहर वोट दिया गया है। क्या योजना बनाई गई थी ( इस साइट से ) का अवलोकन :

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

जेडीके 7 के लिए समग्र दृष्टिकोण बहुत गंभीर है ।

Answer 11

JavaDoc अपने आप में बेहद लचीली है क्योंकि आप मानक डॉकलेट को कस्टम डॉकलेट के साथ बदल सकते हैं ताकि कुछ ऐसा प्रदान किया जा सके जो आपकी परियोजनाओं को विशिष्ट आवश्यकताओं को पूरा करता हो।

जिस परियोजना पर मैं काम कर रहा हूं, हमने जावाडोक के साथ हमारे उत्पाद के लिए एक HTML / XML- आधारित प्रलेखन प्रणाली (क्लाइंट-साइड XSLT 2.0 का उपयोग करके) पूरी तरह से एकीकृत किया है। इसके लिए, XML में JavaDoc डेटा का उत्पादन करने के लिए एक कस्टम डॉकलेट का उपयोग किया गया था, कोड टिप्पणियों के भीतर भी HTML मार्कअप सुनिश्चित करने के लिए टैग्सअप का उपयोग किया गया था।

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

यहीं नहीं विशाल प्रलेखन में एक नमूना प्रविष्टि बिंदु के लिए एक लिंक है: जावाडॉक दर्शक नमूना

यहाँ एक छवि भी है:

Answer 12

एक स्मार्ट सीलेबल जेवाडॉक दर्शक:

कई बार, मुझे JavaDoc ब्राउज़ करने की समस्या का सामना करना पड़ता है। मैं Adnroid डॉक्टर खोज विकल्प की तरह कुछ के लिए देख रहा था। अंत में मुझे ऐसा कुछ मिलता है। यदि आप फ़ायरफ़ॉक्स का उपयोग करते हैं तो समाधान यहाँ है।

1. प्लगइन GreaseMonkey स्थापित करें, इसके थोड़े से कस्टमाइज़िंग वेब पेज को जिस तरह से हम देखते हैं। (हमें किसी java doc पृष्ठ को अनुकूलित करने की आवश्यकता है, इसलिए हम कक्षा के नाम पर खोज कर सकते हैं) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

2. काम करने के लिए चिकनाई के लिए, हमें अनुकूलन के लिए कुछ उपयोगकर्ता स्क्रिप्ट की आवश्यकता है। इसे greasemonkey द्वारा स्वचालित रूप से डाउनलोड किया जा सकता है। JavaDoc खोज फ्रेम या JavaDoc वृद्धिशील खोज से उपयोगकर्ता नाम स्थापित करें ।

यह मेरे लिए बहुत अच्छा काम करता है।