Ruby 中的 Python 文档字符串相当于什么？

Question

在 Python 中，您可以使用 obj.__doc__ 来访问对象的文档字符串。 Ruby 中的等效操作是什么？

Answer 1

Ruby 没有 Python __doc__ 等效项。他们经常使用 Rdoc 格式作为文档，例如：

# For example, a square or circle.
class Shape
  # A horizontal position.
  def x
  end

  # A vertical position.
  def y
  end
end

Answer 2

不幸的是，Ruby 没有任何像 Python 一样的内置文档字符串。

RDoc 看起来很糟糕。 RDoc 被设计为处理成 HTML 格式并在我们的浏览器中读取。它不是纯文本。谁喜欢阅读类似 HTML 的源代码？院子更好。还有 TomDoc 仅使用纯文本。但它们都无法与 Pythonic 文档字符串相比，例如，Pythonic 文档字符串允许从任何 python 控制台进行简单的自动完成，并且不需要使用任何处理工具。

Answer 3

使用 Yard 在 Ruby 中记录代码更容易，Yard 支持不同的标签，例如 :NODOC:

要使用 Yard 记录代码，只需将注释写在代码上方即可。

# MyClass.new(...) some comment here
class MyClass
end

# foo("bar")
def foo(bar = nil)
end

然后在项目的当前工作目录上运行 yard ，这将为您生成 $PWD/doc 目录，其中包含一组不错的文档。

Answer 4

我不相信红宝石支持这一点。

Answer 5

Ruby 命名为 HEREDOCS，支持各种格式选项，例如文字、前导空格等。我发现的两篇有用的文章是：

• 如何在 Ruby 中创建多行字符串？ 和
• Heredocs 以及如何在 Ruby 和 Rails 中使用它们

下面是一些简单示例：

irb(main):001:0" puts <<~TILDE
irb(main):002:0"   This removes leading whitespace to the left
irb(main):003:0"     but preserves indentation underneath it,
irb(main):004:0"     which is quite helpful for formatting.
irb(main):005:0"
irb(main):006:0> TILDE
This removes leading whitespace to the left
  but preserves indentation underneath it,
  which is quite helpful for formatting.

irb(main):007:0" puts <<-LITERAL
irb(main):008:0"     This will do whatevery you
irb(main):009:0"    tell it to do
irb(main):010:0"         which can be nice if you want
irb(main):011:0"      things to be laid out very, very
irb(main):012:0"        p r e c i s e l y
irb(main):013:0"     ... except the problem is you have
irb(main):014:0"       to put this text all the way to the left
irb(main):015:0"     of your code if you want to avoid leading
irb(main):016:0"     whitespace.
irb(main):017:0> LITERAL
    This will do whatevery you
   tell it to do
        which can be nice if you want
     things to be laid out very, very
       p r e c i s e l y
    ... except the problem is you have
      to put this text all the way to the left
    of your code if you want to avoid leading
    whitespace.

HEREDOCS 还支持字符串插值。

irb(main):018:0> name = 'Jeff'
=> "Jeff"
irb(main):019:0" puts <<~INTERPOLATION
irb(main):020:0"   My name is #{name}
irb(main):021:0> INTERPOLATION
My name is Jeff