Sinon: "एपीआई विशिष्टता" शैली प्रलेखन

वैसे, मैं वर्तमान दस्तावेज़ीकरण पर ध्यान नहीं दे रहा हूँ, जो मूल्यवान है। मैं केवल एक अतिरिक्त, व्यापक बात का सुझाव दे रहा हूं।

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

हम कोड एनोटेशन और थोड़ा टूलिंग के बारे में बाइकशेड कर सकते थे। शायद व्यवहार्य विकल्प हैं।

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

@mantoni JSDocs को ऑटो-जेनरेट करने के लिए बहुत सारे टूल हैं। मुझे इसका कोई v1 मुद्दा नहीं दिख रहा है। आपको हर जगह @typedef s बनाने की आवश्यकता नहीं है। बस हो रहा है

/**
  <strong i="8">@param</strong> {String} [foo] optional string
  <strong i="9">@example</strong> Create foo instance
       var foo = dooFoo('somestring') 
*/ 

काफी मदद करेगा।

हाय @ 76784 , यह बहुत अच्छा इनपुट है! 😊

हालाँकि, मुझे कुछ विचार करने हैं।

मुझे JSDoc बहुत पसंद है। यही वह है जो हम Chai.js पर उपयोग करते हैं और यह अब तक बहुत अच्छी तरह से काम करता है क्योंकि चीजों को नामस्थानों में अलग करने में सक्षम होने के कारण कोड को हमेशा डॉक्स के साथ सिंक में रखा जाता है क्योंकि वे एक दूसरे के ठीक बगल में हैं।

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

मुझे लगता है कि निश्चित रूप से JSDocs होना अच्छा होगा, लेकिन यह ध्यान रखना महत्वपूर्ण है कि इसके लिए एक अत्यंत महत्वपूर्ण प्रयास की आवश्यकता होगी।

अगर @ 76784 एक शाखा शुरू करेगा और कुछ अवधारणाओं को पेश करेगा, तो मुझे लगता है कि इस विचार से आकर्षित कुछ लोग जल्दी से इसे

@lucasfcosta

मुझे जावा डॉक्स बहुत शुष्क लगते हैं। यह संदर्भ के लिए अच्छा है, लेकिन इसके बड़े हिस्से को सीखने या टटोलने के लिए बुरा है।

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

मैं JSDoc का विशेषज्ञ नहीं हूं, लेकिन मुझे आश्चर्य है कि JSDoc टिप्पणियों में प्रवेश के लिए ट्यूटोरियल से लिंक करने का एक आसान तरीका होगा।

इस पर कुछ सबूतों के योगदान के लिए, @ fatso83 , मेरे पास इस समय थोड़ा सा समय है (मुझे पता है, कौन नहीं है?), लेकिन मैं बाद में वर्ष में बेहतर स्थिति में हो सकता हूं . सिनॉन को अच्छी तरह से सीखने का यह एक शानदार तरीका होगा।

इस समस्या को स्वचालित रूप से पुराने के रूप में चिह्नित कर दिया गया है क्योंकि इसमें हाल की गतिविधि नहीं है। आगे कोई गतिविधि नहीं होने पर इसे बंद कर दिया जाएगा। आपके योगदानों के लिए धन्यवाद।

मैंने इस मुद्दे को पिन कर दिया है, इसलिए इसे बासी बॉट द्वारा बंद नहीं किया जाता है

अगर हम इस सड़क से नीचे जाने का फैसला करते हैं, तो मुझे लगता है कि हमें https://github.com/gajus/eslint-plugin-jsdoc जैसे कुछ का उपयोग करना चाहिए ... नियमों को शायद eslint-config-sinon में जाना चाहिए।

इसमें और बाहर गोता लगाने के लिए खेद है - यह वास्तव में कुछ कार्य प्राथमिकताओं से प्रेरित है। और मुझे नहीं पता कि यह सही धागा है, लेकिन मौजूदा दस्तावेज पर कुछ और प्रतिक्रिया देने के लिए ...

जैसा कि मैं जासूसों की तरह कुछ देखता हूं: https://sinonjs.org/releases/v7.4.1/spies/

मैं मोचा के साथ काम कर रहा हूं, जिसका पहले खंड में दिखाया गया एक अलग वाक्यविन्यास है।

"test should call subscribers on publish": function () {
    var callback = sinon.spy();
    PubSub.subscribe("message", callback);

    PubSub.publishSync("message");

    assertTrue(callback.called);
}

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

ऐसा कुछ है जो मुझे लगता है कि यदि आप उदाहरण प्रदान करने जा रहे हैं तो ऐसा किया जाना चाहिए। परीक्षण की जा रही किसी भी चीज़ की न्यूनतम कार्यशील कार्यक्षमता दिखाएं। myLib साथ यहाँ भी यही समस्या है: https://sinonjs.org/releases/v7.4.1/fake-xhr-and-server/

मैं समझ गया - myLib कुछ ऐसा है जिसे मैं लिखूंगा। लेकिन आप बहुत से नौसिखिया से इस सामान को सीखने के लिए कह रहे हैं कि वे किसी भी चीज के खिलाफ परीक्षण कर रहे हैं।

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

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

असल में वह परीक्षण मोचा के वाक्यविन्यास का उपयोग कर रहा है

क्या?? अब मुझे मोचा दस्तावेज के बारे में शेखी बघारना होगा। :-)

मैंने इस प्रयास को https://github.com/sinonjs/samsam/pull/82 में शुरू करने का प्रयास किया है