如何用YARD记录子类方法？

Question

如何文档化子类覆盖而不冗余的方法？例如..。

class Parent
  # Is this the parent?
  # @return [Boolean]
  def parent?
    true
  end
end

class Child < Parent
  def parent?
    false
  end
end

院子会产生这样的东西。

班级:家长 实例方法摘要 #父？⇒布尔值 这是家长吗？班级:儿童 实例方法摘要 #父？⇒布尔值

生成的院子文档将不包括“这是父的吗？”在Child#parent的文档中？，也不会指示它是一个覆盖。

我想看到这样的情况：

班级:家长 实例方法摘要 #父？⇒布尔值 这是家长吗？班级:儿童 实例方法摘要 #父？⇒布尔值 这是家长吗？ 从父级继承的方法 #家长？

我不希望将文档复制到每个子类中。

Answer 1

简单答案

记录这一点的正确方法是在返回类型之后放置一个自由形式的描述，并可能记录方法本身。例如：

class Parent
  # True when a passed argument has Parent
  # as an ancestor.
  #
  # @return [Boolean] ancestor of subclass
  def parent?
    true
  end
end

一个更全面的例子

您还可以通过利用标记语法的自由形式部分和标记语言(默认情况下为RDoc)提供使用示例和更详细的文档。

class Parent
  # True when passed argument includes
  # +Parent+ as an ancestor.
  #
  # @example Cousin isn't subclass of Parent
  #   parent? Cousin.new #=> false
  # @example Child is a subclass of Parent
  #   parent? Child.new #=> true
  # @param obj [Class, #ancestors] Class,
  #   instance, or other object that can
  #   #respond_to?(:ancestors)
  # @return [Boolean] ancestors of _obj_
  #   includes +Parent+ class
  def parent? obj
    obj.class.ancestors.include? self.class
  end
end

可能有更优雅的方法来实现这一点，而且我正在电话上输入，所以请注意代码的清空器，因为我还没有实际测试代码，也没有验证码输出的格式。不过，一般的方法是合理的，我经常使用这种格式。

核心思想

基本上，核心的想法是人们应该：

1. 如果您想要将每个标记项的描述与该项目关联，请将其放在行中。大多数标签支持自由格式的描述或标题，这些描述或标题将以视觉上与标记元素相关联的方式格式化。
2. 对类、方法、参数、示例等使用标记和格式设置。您不需要将其全部插入到单个标记中，尽管在您的特定示例中，您可能希望这样做以使事物在视觉上保持关联。
3. 在大多数情况下，您可以使用用缩进将自由形式的长文本包装起来。
4. 包装有几个例外(例如，示例标题与缩进代码块是说明性的)，但是您通常可以使用RDoc或Markdown语法来解决这个问题。
5. 如果您无法得到您想要的东西，请参考第四项获取其他方法，或者找到一个不同的标记或标记来表示您的意图。
6. 如果你不能从盒子里得到你想要的东西，宏、自定义标签和指令会让你做一些奇怪而美妙的事情。注:我几乎从来不需要这样做，但是如果你需要的话，功能就在那里。

在大多数情况下，更简单更好。当然，理解YARD不能简洁地表示您的创作意图是一种艺术形式，但是很难按预期标记或呈现的代码可能表明需要重构代码，而不仅仅是修改码标记。

记住院子的主要目的

请记住，院子主要用于文档的**元素，并向呈现引擎或文档阅读器提供提示，它本身不是一种成熟的标记语言，不能用陡峭的RBS验证签名，也不强制执行任何类型的调用者/被叫者契约。

都是些评论。使您的代码尽可能自我解释，然后将码看作是通过标记文档元素来改进必要注释的一种方法，这样标记语言就可以生成更好的输出。

Answer 2

您可以在每个方法上使用一个参考标签来引用父方法。

class Child < Parent
  # (see Parent#parent?)
  def parent?
    false
  end
end

Child#parent?将拥有与Parent::parent?相同的文档