如何记录 Ruby 代码？答案

【问题标题】：How to document Ruby code?如何记录 Ruby 代码？
【发布时间】：2010-12-13 11:31:30
【问题描述】：

在记录 ruby 代码时是否有某些代码约定？例如我有以下代码sn-p：

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

这个猜测是可以的，但也许有更好/更好的文档实践？

【问题讨论】：

shop.oreilly.com/product/9780596516178.do 在源代码中有一个很好的小例子。参见第 2 章列表。这就像这里的答案。我玩过 rdoc 只是为了显示源代码。您可以将文件扩展名设置为 my_code.rb 到 my_code.rb.txt，然后在其上运行 rdoc。 > rdoc my_code.rb.txt 那么类和模块就无关紧要了，因为 rdoc 无论如何都会为它渲染 html。玩得开心。

标签： ruby

【解决方案1】：

我会高度建议使用RDoc。这几乎是标准。代码 cmets 易于阅读，它使您可以轻松地为您的项目创建基于 Web 的文档。

【讨论】：

【解决方案2】：

您应该将您的文档定位为 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)

【讨论】：

我应该如何记录 outhandler 和 errhandler 参数可能为零？
YARD 的注解可能更强大，但在它被包含在标准 Ruby 发行版而不是 RDoc 中之前，它的注解不是标准的。
RDoc 链接已损坏试试这个：github.com/ruby/rdoc。如果每个人都对该链接感到满意，我会要求编辑答案。

【解决方案3】：

我建议按照所述了解 RDoc。但也不要忽视非常流行的YARD A Ruby Document 工具。您将在网上看到的很多关于 Ruby 的文档都使用 Yard。 RVM 知道 Yard 并使用它在您的机器上生成文档（如果可用）。

仍然需要 RDoc，因为 Yard 使用它。

【讨论】：

主要使用 C++、Java、Scala 和 PHP，我发现 @tag 表示法非常熟悉。
四年过去了，YARD有了很大的发展。可惜 YARD 仍然没有包含在 Ruby 中。（顺便提一下，YARD 主页接受 HTTPS。）
YARD 似乎比 RDoc 轻！谢谢:)

【解决方案4】：

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

【讨论】：

【解决方案5】：

您还可以查看 TomDoc for Ruby - 版本 1.0.0-rc1。

http://tomdoc.org/

【讨论】：

FWIW，这个在 GitHub 风格指南中指定 - github.com/styleguide/ruby
谢谢，在记录 ruby 代码时，tomdoc 似乎是当前最佳实践的良好来源。回答 rdoc 文档中显然缺少的“如何”和“为什么”。
TomDoc 尚未更新。最后一次提交是 2012 年 5 月。
@maasha 到 2017 年，我相信除了普通的 RDoc 之外最好的选择是 YARD，因为它可以解析内容并为类和方法创建一些精美的超链接。

【解决方案6】：

这是ruby documentation system (RDOC)的文档

【讨论】：

【解决方案7】：

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

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

【讨论】：