Документ YARD - как документировать тип класса, ориентируясь на его родительский класс

Предположим, у меня есть следующее

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

person Cyril Duchon-Doris    schedule 26.04.2019    source источник


Ответы (1)


Достаточно написать

# @return [AbstractClass]

Читатель должен предположить, что может применяться замена Лискова. Префикс Abstract (а также @abstract tag) также будет ясно сообщать об этом, и в результирующей документации будут перечислены ConcreteClass1 и ConcreteClass2 в разделе "Прямые известные подклассы" AbstractClass.

Что касается возврата класса, рекомендация создателя YARD заключается в использовании Class<AbstractClass> .

person dug    schedule 26.04.2019