Làm thế nào để ghi lại mã Ruby?


201

Có quy ước mã nhất định khi ghi lại 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 đoán điều này là ổn, nhưng có lẽ có những thực hành tài liệu tốt hơn / tốt hơn?


shop.oreilly.com/product/9780596516178.do có một ví dụ nhỏ đẹp trong mã nguồn. Xem trong danh sách chương 2. Nó giống như câu trả lời ở đây. Tôi đã chơi với ndoc chỉ để hiển thị mã nguồn. Bạn có thể làm cho phần mở rộng tệp của mình giống như my_code.rb thành my_code.rb.txt và sau đó chạy tệp trên đó. > rdoc my_code.rb.txt thì điều đó không thành vấn đề về các lớp và mô-đun bởi vì ndoc sẽ hiển thị html cho nó. Hãy vui vẻ với nó.
Douglas G. Allen

Câu trả lời:


198

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ừ nó. Bạn đã đặt bình luận của mình vào đúng chỗ cho điều đó, nhưng bạn nên xem tài liệu RDoc để 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 sẽ đị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)

Làm thế nào tôi nên tài liệu rằng các tham số outhandler và errhandler có thể không?
StackedCrooking

10
Các chú thích của YARD có thể mạnh hơn, nhưng cho đến khi nó được bao gồm trong bản phân phối Ruby tiêu chuẩn thay vì RDoc, các chú thích của nó không phải là tiêu chuẩn.
Ken Bloom

Liên kết RDoc bị hỏng hãy thử điều này: github.com/ruby/rdoc . Tôi sẽ yêu cầu chỉnh sửa câu trả lời nếu mọi người hài lòng với liên kết đó.
Jordan Stewart

27

Tôi rất muốn đề xuất 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.


24

Tôi muốn đề nghị làm quen với RDoc như đã 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 nếu có.

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


1
Đã sử dụng chủ yếu C ++, Java, Scala và PHP, tôi thấy @tagký hiệu này rất quen thuộc.
ngờ1ejack

1
Đã bốn năm và YARD đã phát triển vượt bậc. Thật đáng tiếc khi YARD vẫn chưa được đưa vào Ruby. (Nhân tiện, trang chủ của YARD chấp nhận HTTPS.)
Franklin Yu

1
YARD dường như nhẹ hơn RDoc! Cảm ơn :)
Constantin De La Roche


9

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

http://tomdoc.org/


FWIW, cái này được chỉ định trong hướng dẫn kiểu GitHub - github.com/styleguide/ruby
Michael Easter

Cảm ơn, tomdoc dường như là một nguồn tốt cho các thực tiễn tốt nhất hiện nay khi nói đến tài liệu mã ruby. Trả lời "làm thế nào" và "tại sao" dường như bị thiếu trong tài liệu của ndoc.
Michael Renner

TomDoc đã không được cập nhật.
Cam

1
@maasha Vào năm 2017, tôi tin rằng đặt cược tốt nhất ngoài RDoc đơn giản sẽ là YARD, bây giờ nó phân tích nội dung và tạo một số siêu liên kết ưa thích cho các lớp và phương thức.
Franklin Yu

2

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

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


Khi sử dụng trang web của chúng tôi, bạn xác nhận rằng bạn đã đọc và hiểu Chính sách cookieChính sách bảo mật của chúng tôi.
Licensed under cc by-sa 3.0 with attribution required.