YARD 文档 - 如何记录一个 class 类型，重点关注其父 class

Question

假设我有以下

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

如何记录一个 return 值，该值 return 是 class 继承 AbstractClass（ConcreteClass1 或 ConcreteClass2）的 class 实例？我想强调 return 值可以是 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

现在假设我的方法 return 是 class 本身，而不是 class 实例，这是好的方法吗？

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

Answer 1

写就够了

# @return [AbstractClass]

reader 应该假定 Liskov 替换可能适用。 Abstract 前缀（以及 @abstract 标签）也将清楚地传达这一点，生成的文档将在 "Direct Known Subclasses" 下列出 ConcreteClass1 和 ConcreteClass2 AbstractClass.

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

YARD 文档 - 如何记录一个 class 类型，重点关注其父 class

YARD doc - how to document a class type focusing on its parent class

code-documentation

yard