Ruby kodu nasıl belgelenir?

Ruby kodunu belgelendirirken belirli kod kuralları var mı? Örneğin, aşağıdaki kod parçacığı var:

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

Bu tahmin bu iyi, ama belki de daha iyi / üstün dokümantasyon uygulamaları var?

Belgelerinizi bulabilen ve ondan HTML oluşturabilen RDoc işlemci için belgelerinizi hedeflemelisiniz. Yorumunuzu bunun için doğru yere koydunuz, ancak RDoc'un nasıl biçimlendireceğini bildiği etiket türleri hakkında bilgi edinmek için RDoc belgelerine bakmalısınız . Bu amaçla, yorumunuzu aşağıdaki gibi yeniden biçimlendiririm:

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

RDoc kullanmanızı şiddetle tavsiye ederim . Bu hemen hemen standart. Kod yorumlarını okumak kolaydır ve projeniz için kolayca web tabanlı belgeler oluşturmanıza olanak tanır.

Belirtildiği gibi RDoc'u tanımanızı öneririm. Ama çok popüler olan YARD A Ruby Belgesini görmezden gelmeyin aracını . Ruby için çevrimiçi göreceğiniz belgelerin çoğu Yard'ı kullanır. RVM, Yard'ı bilir ve varsa, makinenizde belgelerinizi oluşturmak için kullanır.

Yard kullandığı için RDoc yine de gerekli olacaktı.

Rails bazı API Dokümantasyon Kılavuzlarına sahiptir . Bu muhtemelen iyi bir başlangıç ​​noktasıdır.

TomDoc for Ruby - Sürüm 1.0.0-rc1'i de kontrol edebilirsiniz.

http://tomdoc.org/

Kurallı RDoc , yayınladığınıza çok benzer.

Size gönderdiğim bağlantıdaki örnek bölüme bakın

İşte yakut dokümantasyon sistemi (RDOC) dokümantasyonu