Як документувати Ruby-код?

Чи існують певні правила коду під час документування рубінового коду? Наприклад, у мене є такий фрагмент коду:

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

Здогадується, що це нормально, але, можливо, є кращі / покращені методи документації?

Вам слід націлити свою документацію на процесор 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)

Я б дуже рекомендував використовувати RDoc . Це майже стандарт. Прочитати коментарі до коду легко, і це дозволяє легко створювати веб-документацію для вашого проекту.

Я б запропонував ознайомитися з RDoc, як зазначено. Але не ігноруйте також дуже популярний інструмент YARD A Ruby Document . Багато документації, яку ви побачите в Інтернеті для Ruby використовує Ярд. RVM знає Ярд і використовує його для генерації вашої документації на вашій машині, якщо вона є в наявності.

RDoc все одно буде потрібен, оскільки Yard використовує його.

Rails має деякі рекомендації щодо документації щодо API . Це, мабуть, хороша відправна точка.

Ви також можете перевірити TomDoc на Ruby - Версія 1.0.0-rc1.

http://tomdoc.org/

Канонічний - RDoc, він дуже схожий на той, який ви розмістили.

Дивіться зразок розділу за посиланням, яке я вам надіслав

Ось документація для системи документації на рубіні (RDOC)