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

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

1 голос
/ 26 апреля 2019

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

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

1 Ответ

1 голос
/ 26 апреля 2019

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

# @return [AbstractClass]

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

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

...