Làm thế nào để tài liệu mã Ruby?

Question

Có quy ước mã nào đó khi viết mã ruby ​​không? Ví dụ: tôi có đoạn mã sau:

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 

Điều này có thể đoán được, nhưng có lẽ có thực tiễn tốt hơn/cao hơn?

Answer 1

Bạn nên nhắm mục tiêu tài liệu của mình cho bộ xử lý RDoc, có thể tìm tài liệu của bạn và tạo HTML từ đó. Bạn đã đưa nhận xét của mình vào đúng vị trí cho điều đó, nhưng bạn nên xem qua số RDoc documentation để tìm hiểu về các loại thẻ mà RDoc biết cách định dạng. Cuối cùng, tôi muốn định dạng lại nhận xét của bạn như sau:

# 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

Kinh điển là RDoc nó rất giống với trang bạn đã đăng.

Xem phần mẫu vào liên kết tôi đã gửi cho bạn

Answer 3

tôi sẽ cao đề nghị sử dụng RDoc. Nó là khá nhiều tiêu chuẩn. Thật dễ dàng để đọc các bình luận mã, và nó cho phép bạn dễ dàng tạo tài liệu dựa trên web cho dự án của bạn.

Answer 4

Đường ray có một số API Documentation Guidelines. Đó có thể là một điểm khởi đầu tốt.

Answer 5

Đây là tài liệu cho các ruby documentation system (RDOC)

Answer 6

Bạn cũng có thể kiểm tra TomDoc cho Ruby - Phiên bản 1.0.0-rc1.

http://tomdoc.org/

Answer 7

Tôi khuyên bạn nên biết RDoc như được nêu. Nhưng đừng bỏ qua công cụ YARD A Ruby Document rất phổ biến. Rất nhiều tài liệu bạn sẽ thấy trực tuyến cho Ruby sử dụng Yard. RVM biết Yard và sử dụng nó để tạo tài liệu của bạn trên máy của bạn nếu nó có sẵn.

RDoc vẫn sẽ được yêu cầu, vì Yard sử dụng nó.