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

Question

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

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 

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

Answer 1

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

# 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) 

Answer 2

कैनोनिकल RDoc यह आपके द्वारा पोस्ट किए गए एक जैसा ही है।

लिंक पर नमूना अनुभाग मैं तुम्हें

Answer 3

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

Answer 4

रेल कुछ API Documentation Guidelines है। यह शायद एक अच्छा प्रारंभिक बिंदु है।

Answer 5

यहाँ ruby documentation system (RDOC)

Answer 6

तुम भी रूबी के लिए TomDoc जांच कर सकते हैं के लिए दस्तावेज़ है - संस्करण 1.0.0-RC1।

http://tomdoc.org/

Answer 7

मैं RDoc पता करने के लिए के रूप में कहा गया है हो रही सुझाव है। लेकिन साथ ही बहुत लोकप्रिय YARD A Ruby Document उपकरण को अनदेखा न करें। रुबी के लिए आप ऑनलाइन देखे जाने वाले बहुत सारे दस्तावेज यार्ड का उपयोग करते हैं। आरवीएम यार्ड जानता है और यह उपलब्ध होने पर आपकी मशीन पर आपके दस्तावेज़ को उत्पन्न करने के लिए इसका उपयोग करता है।

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