2025-02-20 07:00:03

如何记录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

这个猜想是可以的,但是也许有更好/更好的文档实践?


当前回答

下面是ruby文档系统(RDOC)的文档

其他回答

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

规范是RDoc,它和你发布的那个很相似。

请参阅我发给您的链接中的示例部分

我建议大家去了解一下RDoc。但是也不要忽略非常流行的YARD A Ruby文档工具。您将在网上看到许多Ruby使用Yard的文档。RVM知道Yard,并使用它在您的机器上生成文档(如果可用的话)。

RDoc仍然是必需的,因为Yard使用它。

您应该针对RDoc处理器编写文档,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)

下面是ruby文档系统(RDOC)的文档