रूबी कोड कैसे दस्तावेज़ करें?

201

क्या रूबी कोड का दस्तावेजीकरण करते समय कुछ कोड कन्वेंशन हैं? उदाहरण के लिए मेरे पास निम्नलिखित कोड स्निपेट हैं:

require 'open3'

module ProcessUtils

  # Runs a subprocess and applies handlers for stdout and stderr
  # Params:
  # - command: command line string to be executed by the system
  # - outhandler: proc object that takes a pipe object as first and only param (may be nil)
  # - errhandler: proc object that takes a pipe object as first and only param (may be nil)
  def execute_and_handle(command, outhandler, errhandler)
    Open3.popen3(command) do |_, stdout, stderr|
      if (outhandler)
        outhandler.call(stdout)
      end
      if (errhandler)
        errhandler.call(stderr)
      end
    end
  end
end

यह अनुमान है कि यह ठीक है, लेकिन शायद बेहतर / बेहतर प्रलेखन प्रथाएं हैं?

ruby

— StackedCrooked
स्रोत

shop.oreilly.com/product/9780596516178.do स्रोत कोड में एक अच्छा सा उदाहरण है। अध्याय 2 सूची में देखें। यह यहाँ के जवाब की तरह है। मैंने स्रोत कोड दिखाने के लिए rdoc के साथ खेला है। आप अपने फ़ाइल एक्सटेंशन को my_code.rb से my_code.rb.txt की तरह बना सकते हैं और फिर उस पर rdoc चला सकते हैं। > rdoc my_code.rb.txt तो यह वर्गों और मॉड्यूल के बारे में कोई बात नहीं करेगा क्योंकि rdoc वैसे भी इसके लिए HTML रेंडर करेगा। इसके साथ मजे करो।

— डगलस जी। एलन

198

आपको अपने दस्तावेज़ को RDoc प्रोसेसर के लिए लक्षित करना चाहिए, जो आपके दस्तावेज़ को ढूँढ सकता है और उससे HTML उत्पन्न कर सकता है। आपने अपनी टिप्पणी इसके लिए सही जगह पर रखी है, लेकिन आपको RDoc प्रलेखन पर एक नज़र डालनी चाहिए कि RDoc को उन प्रारूपों के प्रकारों के बारे में सीखना है जो प्रारूपित करना जानते हैं। उस अंत तक, मैं आपकी टिप्पणी को निम्नानुसार सुधारूंगा:

  # Runs a subprocess and applies handlers for stdout and stderr
  # Params:
  # +command+:: command line string to be executed by the system
  # +outhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil)
  # +errhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil)

— केन ब्लूम
स्रोत

मुझे यह कैसे दस्तावेज़ करना चाहिए कि आउटहैंडलर और इरहैंडलर पैरामीटर शून्य हो सकते हैं?

— स्टैक्डक्रोकड

10

यार्ड के एनोटेशन अधिक शक्तिशाली हो सकते हैं, लेकिन जब तक यह आरडीओसी के बजाय मानक रूबी वितरण में शामिल नहीं है, तब तक इसके एनोटेशन मानक नहीं हैं।

— केन ब्लूम

: RDoc लिंक इस कोशिश टूट गया है github.com/ruby/rdoc । यदि कोई व्यक्ति उस लिंक से खुश है तो मैं उत्तर को संपादित करने का अनुरोध करूंगा।

— जॉर्डन स्टीवर्ट

27

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

— टोपेर फंगियो
स्रोत

24

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

आरडीओसी की अभी भी आवश्यकता होगी, क्योंकि यार्ड इसका उपयोग करता है।

— vgoff
स्रोत

1

ज्यादातर C ++, Java, Scala और PHP का उपयोग करने के बाद, मुझे @tagनोटेशन बहुत ही परिचित लगता है ।

— डबल 1जैक

1

चार साल हो गए हैं और यार्ड बहुत विकसित हो गया है। यह अफ़सोस की बात है कि यार्ड अभी भी रूबी में शामिल नहीं है। (वैसे YARD होमपेज HTTPS को स्वीकार करता है।)

— फ्रैंकलिन यू

1

आरडीओसी की तुलना में यार्ड हल्का प्रतीत होता है! धन्यवाद :)

— कांस्टेंटिन डी ला रोशे

16

रेल में कुछ एपीआई प्रलेखन दिशानिर्देश हैं । यह शायद एक अच्छा शुरुआती बिंदु है।

— हांक गे
स्रोत

9

आप रूबी के लिए टॉमडॉक - संस्करण 1.0.0-आरसी 1 भी देख सकते हैं।

http://tomdoc.org/

— onurozgurozkan
स्रोत

FWIW, यह एक GitHub शैली गाइड में निर्दिष्ट है - github.com/styleguide/ruby

— माइकल ईस्टर

धन्यवाद, टोमडॉक सर्वोत्तम वर्तमान प्रथाओं के लिए एक अच्छा स्रोत प्रतीत होता है जब यह रूबी कोडिंग का दस्तावेजीकरण करता है। "कैसे" और "क्यों" का उत्तर स्पष्ट रूप से rdoc प्रलेखन से गायब है।

— माइकल रेनर

टॉमडॉक को आज तक नहीं रखा गया है। अंतिम प्रतिबद्ध मई 2012 था।

— माशा

1

@माशा 2017 तक मेरा मानना है कि सादे आरडीओसी के अलावा सबसे अच्छा दांव यार्ड होगा, अब यह सामग्री को पार्स करता है और कुछ फैंसी हाइपरलिंक्स को कक्षाओं और तरीकों के लिए बनाता है।

— फ्रैंकलिन यू

2

विहित आरडीओसी है यह आपके द्वारा पोस्ट किए गए समान है।

आपके द्वारा भेजे गए लिंक पर नमूना अनुभाग देखें

— OscarRyz
स्रोत

2

यहाँ रूबी प्रलेखन प्रणाली (RDOC) के लिए प्रलेखन है

— jrhicks
स्रोत