Как документировать код Ruby?

существуют ли определенные соглашения кода при документировании кода 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

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

7 ответов


вы должны нацелить свою документацию на процессор 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, как указано. Но не игнорируйте очень популярные двор рубиновый документ инструмент, а также. Много документации вы увидите в интернете для Ruby использует двор. RVM знает двор и использует его для генерации вашей документации на вашем компьютере, если она доступна.

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


Rails имеет некоторые руководство по документации API. Это, вероятно, хорошая отправная точка.


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

http://tomdoc.org/


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

см. раздел образца на ссылке, которую я послал вам