Как документировать код 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

Это предположение, что все в порядке, но, возможно, существуют лучшие/превосходные методы документации?

Ответы

Ответ 1

Вы должны настроить таргетинг своей документации на процессор 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)

Ответ 2

Я бы предложил высоко использовать RDoc. Это в значительной степени стандарт. Легко прочитать комментарии к коду, и это позволяет вам легко создавать веб-документацию для вашего проекта.

Ответ 4

Я бы посоветовал узнать RDoc, как сказано. Но не игнорируйте очень популярный инструмент YARD A Ruby Document. Большая часть документации, которую вы увидите в Интернете для Ruby, использует Yard. RVM знает Yard и использует его для генерации вашей документации на вашем компьютере, если она доступна.

RDoc все равно потребуется, поскольку его использует Ярд.

Ответ 5

Вы также можете проверить TomDoc для Ruby - Версия 1.0.0-rc1.

http://tomdoc.org/

Ответ 6

Канонический RDoc он очень похож на тот, который вы разместили.

См. раздел примера ссылки, которую я отправил вам.