ruby - 为什么需要 ":nodoc:" 语法？

Question

似乎很多库/插件都使用这种语法：

  def self.included(base) # :nodoc:
    base.extend ClassMethods
  end

为什么这:nodoc:部分是必要的？

Answer 1

这不是必要的。如果应用于一个类，它只是禁止类扩展中所有方法的文档（rdoc）。在 Ruby 编程中描述为：

:nodoc: - 不要在文档中包含这个元素。对于类和模块，直接在受影响的类或模块中的方法、别名、常量和属性也将从文档中省略。但是，默认情况下，将记录该类或模块中的模块和类。

Answer 2

我认为没有必要。实际上，在我看来，它是 RDoc 最没用的特性之一。

很多次我在阅读图书馆的代码时看到它，我不得不问自己“为什么？”。我认为没有任何理由使用此功能。如果您不希望人们使用您的方法，只需将其设为私有即可。阅读文档并查看对文档中遗漏的方法的方法调用时，这是一个很大的麻烦。