如何记录Ruby代码？

Question

在记录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

这个猜测没关系,但也许有更好/更优秀的文档实践？

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

Answer 2

我强烈建议使用RDoc.它几乎是标准.它易于阅读代码注释,并允许您轻松地为项目创建基于Web的文档.

Answer 3

我建议按照规定了解RDoc.但是不要忽略非常流行的YARD A Ruby Document工具.你将在网上看到Ruby的很多文档使用Yard.RVM知道Yard并使用它在您的机器上生成文档(如果可用).

当Yard使用它时,仍然需要RDoc.

Answer 4

Rails有一些API文档指南.这可能是一个很好的起点.

Answer 5

您还可以检查TomDoc for Ruby - 版本1.0.0-rc1.

http://tomdoc.org/