如何记录Ruby代码？

c90pui9n 于 2022-09-21 发布在 Ruby

关注(0)|答案(7)|浏览(132)

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

来源：https://stackoverflow.com/questions/1681467/how-to-document-ruby-code

7条答案

按热度按时间

lnvxswe21#

您应该将您的文档定位于RDoC处理器，它可以找到您的文档并从中生成HTML。您已经将您的注解放在了正确的位置，但是您应该查看RDoc documentation以了解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)

赞(0）回复(0）举报 2022-09-21

8tntrjer2#

我强烈建议使用RDoc。这几乎就是标准。它很容易阅读代码注解，并允许您轻松地为您的项目创建基于Web的文档。

赞(0）回复(0）举报 2022-09-21

zzwlnbp83#

我建议了解RDoC，就像我所说的那样。但也不要忽视非常流行的YARD A Ruby Document工具。你会在网上看到很多Ruby Use Yard的文档。RVM了解Yard，并使用它在您的机器上生成文档(如果它可用)。

RDoC仍然是必需的，因为Yard正在使用它。

赞(0）回复(0）举报 2022-09-21

bmvo0sr54#

Rails有一些API Documentation Guidelines。这可能是一个很好的起点。

赞(0）回复(0）举报 2022-09-21

yftpprvb5#