@Deprecated जैसे प्रयोगात्मक या अधूरे API कैसे दस्तावेज़ित करें?

Question

क्या एक अच्छा शब्द है जो समान है लेकिन "पदावनत" से अलग है इसका मतलब यह है कि एक विधि या एपीआई कोड आधार में है लेकिन इसका उपयोग नहीं किया जाना चाहिए क्योंकि इसका कार्यान्वयन पूर्ण नहीं है या संभावना में बदलाव होगा? (हाँ, मुझे पता है, उन तरीकों को सार्वजनिक नहीं किया जाना चाहिए, यादा यादा यादा। मैंने अपनी स्थिति नहीं बनाई, मैं बस इसे सर्वश्रेष्ठ बनाने की कोशिश कर रहा हूं।)

लोग क्या सुझाव देते हैं? प्रायोगिक, अपूर्ण, कुछ और?

अगर मैं इस API के लिए javadoc प्रलेखन बना रहा हूं जो अभी भी प्रवाह में है, तो क्या मुझे @deprecated टैग का उपयोग करना चाहिए या क्या एक बेहतर सम्मेलन है? मेरे लिए @deprecated का तात्पर्य है कि यह API पुराना है और एक नया पसंदीदा तंत्र उपलब्ध है। मेरी स्थिति में, कोई विकल्प नहीं है, लेकिन एपीआई में कुछ तरीके समाप्त नहीं हुए हैं और इसलिए इसका उपयोग नहीं किया जाना चाहिए। इस बिंदु पर मैं उन्हें निजी नहीं बना सकता, लेकिन मैं डॉक्स में स्पष्ट चेतावनी देना चाहता हूं।

Comments

एक "अस्थिर" टैग भी सहायक होगा। अर्थ कुछ अलग होगा। "यह ठीक काम करने वाला है लेकिन हम भविष्य में कुछ बदलाव कर सकते हैं"।

— बोरबिज

Answer 1

उपयुक्त शब्द सबसे अधिक संभावना इनक्यूबेटर है , यह Google और Apache द्वारा उपयोग किया जाता है:

• गूगल-वेब-टूलकिट-इनक्यूबेटर

  Google वेब टूलकिट के लिए विगेट्स और लाइब्रेरी के आधिकारिक इनक्यूबेटर ...

• अपाचे इनक्यूबेटर

  ... ओपन-सोर्स प्रोजेक्ट्स के लिए प्रवेश द्वार पूरी तरह से अपाचे सॉफ्टवेयर फाउंडेशन प्रोजेक्ट बनने का इरादा है ...

यदि आप ऊपर उल्लिखित परियोजनाओं पर करीब से नज़र डालते हैं, तो आप देख सकते हैं कि "प्रयोगात्मक" API (जैसे GWT में) में "समर्पित" पैकेज नाम हैं, जैसे com.google.gwt.gen2। यह स्थायी सार्वजनिक खपत के लिए भविष्य के "अंतिम रूप से" एपीआई को प्रदूषित करने से बचने के लिए है - क्योंकि, आप जानते हैं,

"सार्वजनिक एपीआई, हीरे की तरह, हमेशा के लिए होते हैं। आपके पास इसे पाने का एक मौका है इसलिए इसे अपना सर्वश्रेष्ठ दें ..." (जोशुआ बलोच, एक अच्छा एपीआई कैसे डिज़ाइन करें और यह क्यों मायने रखता है )

Comments

मैं "प्रायोगिक" की ओर झुकाव था की तरह एपीआई को देखने के बाद developer.chrome.com/extensions/experimental.html

— माइकल लेवी

Answer 2

मैं @deprecatedविशुद्ध रूप से व्यावहारिक कारणों के लिए उपयोग करेगा ।

यद्यपि आप @deprecatedइसका सही अर्थ नहीं बताते हैं, लेकिन इसका एक महत्वपूर्ण लाभ है: जावा कंपाइलर ने इसके लिए अंतर्निहित समर्थन दिया है। -deprecationध्वज के साथ संकलित करने से आपको उन सभी स्थानों का पता लगाने में मदद मिलती है जहाँ आप एक पदावनत पद्धति को ओवरराइड करते हैं, जिससे आपके उपयोगकर्ताओं को बहुत जल्दी संदिग्ध कोड खोजने में मदद मिलती है। आप @deprecatedजावदोक टैग का उपयोग यह समझाने के लिए कर सकते हैं कि वास्तव में जो कोई भी आपके दस्तावेज़ को पढ़ने के लिए आगे बढ़ रहा है। यह वह जगह है जहां आप उपयोगकर्ता को बता सकते हैं कि एपीआई प्रयोगात्मक है, उन्हें अपने जोखिम पर इस्तेमाल किया जाना चाहिए, और इसी तरह।

Comments

+1। बहुत बढ़िया बिंदु। एपीआई के ऐसे हिस्सों के लिए अंतर्निहित समर्थन होना आवश्यक है, और उपयोगकर्ताओं को यह समझने के लिए प्रलेखन देखने के लिए प्रोत्साहित करता है कि उन हिस्सों को मूल्यह्रास के रूप में चिह्नित क्यों किया गया है।

— आर्सेनी मूरज़ेंको

मैं आईडीई और डॉक्स प्राप्त करने के लिए कम से कम विधि को उजागर करने और फिर एक संक्षिप्त विवरण रखने के लिए "* @deprecated यह एक प्रयोगात्मक एपीआई है और बदलने की संभावना है"।

— माइकल लेवी

बस याद रखना कि पदावनत करने से बहुत सारी चेतावनियाँ होंगी। यह उतना बुरा नहीं हो सकता है जितना लगता है। प्रायोगिक सुविधाओं से सावधान रहना ठीक हो सकता है।

— बोरबॉज

Answer 3

मैंने अन्य एपीआई में ऐसा कभी नहीं देखा है, क्योंकि प्रयोगात्मक या अधूरी सुविधाओं का सार्वजनिक एपीआई में कोई लेना-देना नहीं है।

चूंकि आपके पास कोई विकल्प नहीं है, बस स्पष्ट रूप से दिखाई देने वाली चेतावनी डालें कि एपीआई का हिस्सा परिवर्तन के अधीन है।

Comments

कुंआ। उदाहरण के लिए हमारे पास है: junit.org/apidocs/org/junit/experimental/package-summary.html वैसे, पैकेज का उपयोग करना एक विचार था। एक बार एपीआई के अस्थिर होने पर आपको पैकेज को बदलने की आवश्यकता होती है ताकि आप सभी निर्भरता को तोड़ देंगे। एक जावा एनोटेशन बेहतर होता

— बोरबज