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

我想这样做也可以，但是可能有更好/更优秀的文档编写实践吗？

- StackedCrooked

---

http://shop.oreilly.com/product/9780596516178.do 的源代码中有一个不错的小例子。请查看第2章列表。它与这里的答案类似。我已经尝试使用rdoc来显示源代码。您可以将文件扩展名更改为类似于my_code.rb到my_code.rb.txt，然后在其上运行rdoc。> rdoc my_code.rb.txt，因此无论类和模块如何，rdoc都会呈现html。玩得开心。 - Douglas G. Allen

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)

- Ken Bloom

---

我应该如何记录outhandler和errhandler参数可能为nil？ - StackedCrooked

YARD的注释可能更加强大，但在其被包含在标准的Ruby发行版中而不是RDoc之前，它的注释不是标准。 - Ken Bloom

RDoc链接已经失效，请尝试使用此链接：https://github.com/ruby/rdoc。如果大家都满意，我会请求编辑答案。 - Jordan Stewart

Answer 2

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

- Topher Fangio

Answer 3

建议先了解 RDoc。但也不要忽略非常流行的YARD Ruby 文档工具。在线上你将看到很多用 YARD 生成的 Ruby 文档。如果可用，RVM 知道并使用 Yard 在你的计算机上生成文档。

需要注意的是，Yard 使用了 RDoc ，因此仍需要安装 RDoc。

- vgoff

---

在使用过大部分C++、Java、Scala和PHP之后，我发现@tag标记非常熟悉。 - doub1ejack

已经过去了四年，YARD 已经有了很大的发展。遗憾的是，YARD 仍然没有被包含在 Ruby 中。（顺便说一下，YARD 主页支持 HTTPS。） - Franklin Yu

YARD似乎比RDoc更轻巧！谢谢 :) - Constantin De La Roche

Answer 4

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

- Hank Gay

Answer 5

您可以查看Ruby的TomDoc - 截至2022年9月19日仍为1.0.0-rc1版本。

- onurozgurozkan

---

这个是在 GitHub 的风格指南中指定的 - https://github.com/styleguide/ruby。 - Michael Easter

谢谢，tomdoc 似乎是记录 Ruby 代码最佳实践的良好来源。它回答了 RDoc 文档中缺失的“如何”和“为什么”。 - Michael Renner

TomDoc已经没有更新了。最后一次提交是在2012年5月。 - maasha

@maasha 我认为除了普通的RDoc之外，到2017年为止最好的选择应该是YARD，因为它可以解析内容并创建一些漂亮的超链接到类和方法。 - Franklin Yu

Answer 6

规范文档是RDoc，它与您发布的文档非常相似。

请查看我发送给您的链接上的示例部分。

- OscarRyz

Answer 7

这里是Ruby文档系统（RDOC）的文档。

- jrhicks