YARD का उपयोग करके रेल परियोजनाओं पर रूबी के लिए प्रलेखन लिखना

शुभ दोपहर, ह्रज़ितली! मैंने पाया कि रेल परियोजनाओं पर रूबी के लिए दस्तावेज बनाने की प्रक्रिया को व्यवस्थित करने के तरीके पर कोई लेख नहीं है। इस समस्या को ठीक करें।

लेख में वर्णन किया जाएगा कि रेल परियोजनाओं के लिए सक्षम दस्तावेज लिखने के लिए यार्ड रत्न का उपयोग कैसे करें और स्वचालित रूप से एक दस्तावेज उत्पन्न करें जहां यह प्रलेखन एक प्रस्तुतिकरण रूप में प्रस्तुत किया जाएगा। प्रलेखन का एक उदाहरण ValiIzRashki साइट कोड में पाया जा सकता है।

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

सिद्धांत: दस्तावेज क्यों लिखें?

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

लेकिन सबसे अच्छी टिप्पणी वह है जिसे लिखने की आवश्यकता नहीं है?

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

लेकिन प्रलेखन लिखना बहुत लंबा समय है!

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

यदि आप प्रलेखन के अतिरिक्त अधिक तर्क चाहते हैं, तो आप इस विषय पर स्मार्ट लोगों द्वारा अन्य लेख पढ़ सकते हैं, उदाहरण के लिए, इस प्रस्तुति को देखें। और हम अभ्यास के लिए आगे बढ़ेंगे।

अभ्यास: यार्ड संरचित टिप्पणियां

पहली बार रूबी प्रोजेक्ट्स पर अपनी रूबी में मैंने एक विशिष्ट संरचना के बिना टिप्पणियां लिखीं। प्रत्येक विधि से पहले, मैंने संक्षेप में लिखा कि वहाँ क्या चल रहा था। तब मुझे एहसास हुआ कि यह वर्णन करना सुविधाजनक होगा, उदाहरण के लिए, यह विधि जो पैरामीटर लेती है; साथ ही साथ यह क्या लौटाता है। सवाल यह था कि हर जगह एक ही कमेंट का टोटा क्यों नहीं?


रत्न यार्ड मिला। इसका सार यह है कि आप अपने कोड पर कुछ सरल सिंटैक्स का उपयोग करते हुए टिप्पणी लिखते हैं, कुछ दूर xml / html जैसा दिखता है। जिसके बाद आप एक कमांड चलाते हैं जो html फाइलें बनाएगी जहां आपके कोड और इसके लिए प्रलेखन एक सुविधाजनक प्रारूप में चित्रित किया जाएगा। RDOC रत्न एक एनालॉग है , लेकिन इसका सिंटैक्स मुझे अधिक जटिल लगा।

मणि सेट करें

$ gem install yard 

या तो मणिभ में जोड़ें

  gem 'yard' 

और बंडल इंस्टॉल चलाएं।

Valiizrashki.ru से एक उदाहरण विधि लें

 def try_to_evacuate(country_id) country = Country.find(country_id) if country.allows_immigrants? evacuate! true else false end end 

यह विधि निर्धारित करती है कि क्या किसी दूसरे देश में प्रवास करना संभव है या नहीं। इसलिए हम एक टिप्पणी के रूप में विधि की घोषणा से पहले लिखते हैं।

 # ,         def try_to_evacuate(country_id) country = Country.find(country_id) ... 

जब आप नॉक बटन पर क्लिक करते हैं तो विधि को कहा जाता है। हम इसे YARD टैग @note साथ @note , जो विभिन्न अतिरिक्त डेटा के लिए जिम्मेदार है। वाक्य विन्यास इस तरह दिखता है:

 @_ ()   

यदि हम एक टैग में कई लाइनों को फिट करना चाहते हैं, तो हम टैब का उपयोग करते हैं

 @_       

हम विधि घोषणा से पहले उसी स्थान पर @note टैग के साथ कॉल के स्थान के बारे में जानकारी लिखते हैं:

 # ,         # @note      "" def try_to_evacuate(country_id) ... 

हम लिखते हैं कि पैरामीटर @param टैग का उपयोग करके पैरामीटर को स्वीकार करता है। इस पैरामीटर का डेटा प्रकार वर्ग कोष्ठक में लिखा गया है, उसके बाद पैरामीटर विवरण।

 # @param country_id [Integer] id  

हम लिखते हैं कि यह विधि वास्तव में @return टैग का उपयोग करके कैसे @return । यहां हम चौकोर कोष्ठक में लिखते हैं कि किस प्रकार का डेटा हमारे पास लौटाया जाएगा, उनके बाद - मूल्य का विवरण।

 # @return [Boolean]    

स्पष्टता के लिए, हम इस पद्धति के उपयोग का एक उदाहरण लिखते हैं। हम इस मामले में एक टैब का उपयोग करके @example टैग का उपयोग कर रहे हैं।

 # @example # try_to_evacuate(2) 

हम @see मॉडल का उपयोग करके देश मॉडल प्रलेखन के लिए एक लिंक भी छोड़ देंगे ताकि आप जल्दी से वहां कूद सकें।

 # @see Country 

परिणाम इस प्रकार है:

 # ,         # @param country_id [Integer] id  # @note      "" # @example # try_to_evacuate(2) # @return [Boolean]    # @see Country def try_to_evacuate(country_id) country = Country.find(country_id) if country.allows_immigrants? evacuate! true else false end end 

YARD प्रलेखन में अन्य टैग हैं जो आप इस लिंक पर सीख सकते हैं।

प्रलेखन समय!

इसे अविश्वसनीय रूप से गणितीय बनाने के लिए, एक परियोजना में एक विन्यास फाइल बनाएं, जिसे निम्न सामग्री के साथ .yardopts :

 --private --protected -o doc/ruby 

उसके बाद, टर्मिनल में अपने प्रोजेक्ट फ़ोल्डर में टर्मिनल पर जाएं और वहां कमांड चलाएं

 $ yard 

डॉक्टर / माणिक फ़ोल्डर बनाया गया था। इसे एक्सप्लोरर में खोलें और वहां _index.html खोलें। ब्राउज़र में, हम अपनी विधि पर स्विच करेंगे और इसे देखेंगे:

यह अच्छा लग रहा है। और मॉडल विधि का संदर्भ काम करता है।

हमने एक सेटिंग फ़ाइल क्यों बनाई? ताकि हर बार आप एक साधारण yard कमांड के साथ प्रलेखन की पीढ़ी शुरू कर सकें। फ़ाइल में पहली दो पंक्तियाँ प्रलेखन के लिए निजी तरीकों को जोड़ने के लिए जिम्मेदार हैं, और तीसरा - उस फ़ोल्डर को सेट करता है जिसमें प्रलेखन दिखाई देता है।

बोनस: दस्तावेज़ का दस्तावेजीकरण

कॉफ़ीस्क्रिप्ट के लिए, उन्होंने समान सिंटैक्स और कार्यक्षमता के साथ एक उपकरण बनाया, जिसे कोडो कहा जाता है। मुझे हैक कोड के दस्तावेज़ीकरण के लिए खुद को सीमित करने का कोई कारण नहीं दिखता है और इसे स्क्रिप्ट के लिए नहीं लिखना है।

एक प्रलेखित फ़ंक्शन का एक उदाहरण जो संख्याओं को रेडियंस में अनुवाद करता है:

  #    # @param x [Integer]  # @return [Integer]  rad:(x) -> x * Math.PI / 180 

प्रोजेक्ट रूट में .codoopts फ़ाइल बनाएँ और वहाँ लिखें:

 -o doc/coffee 

उसके बाद, जब आप प्रोजेक्ट के रूट में कमांड चलाते हैं

 $ codo 

हम डॉक / कॉफी फ़ोल्डर में कॉफ़ीस्क्रिप्ट के लिए दस्तावेज़ बनाएंगे।

हो गया, आप अद्भुत हैं!

निष्कर्ष

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