YARD doc - 如何记录专注于其父类的类类型答案

【问题标题】：YARD doc - how to document a class type focusing on its parent classYARD doc - 如何记录专注于其父类的类类型
【发布时间】：2019-04-26 09:33:01
【问题描述】：

假设我有以下内容

class AbstractClass; end
class ConcreteClass1 < AbstractClass; end
class ConcreteClass2 < AbstractClass; end

如何记录一个返回值，该返回值返回一个继承 AbstractClass 的类（ConcreteClass1 或 ConcreteClass2）的类实例？我想重点说明返回值可以是ConcreteClass1 或ConcreteClass2，但重要的是它们都是kind_of(AbstractClass)

我在想这样的事情，这是好方法吗？

# Class MyClassFactory implements the factory pattern for selecting the appropriate class for xxx
def MyClassFactory
  # @return [? < AbstractClass] an instance of a class inheriting AbstractClass
  def create_instance(*args)
     if cond?
       ConcreteClass1
     else
       ConcreteClass2
     end.new(*args)
  end
end

现在假设我的方法返回的是类本身，而不是类实例，这会是好方法吗？

def MyClassFactory
  # @return [? <= AbstractClass] the class to be used
  def select_class
     if cond?
       ConcreteClass1
     else
       ConcreteClass2
     end
  end
end

【问题讨论】：

标签： code-documentation yard

【解决方案1】：

写就够了

# @return [AbstractClass]

读者应该假设 Liskov 替换可能适用。 Abstract 前缀（以及 @abstract 标记）也将清楚地传达这一点，生成的文档将在 AbstractClass 的“直接已知子类”下列出 ConcreteClass1 和 ConcreteClass2。

至于返回一个类，YARD创建者的recommendation是使用Class<AbstractClass>。

【讨论】：