Как следует задокументировать класс, основанный на командном шаблоне, в YARD - PullRequest
Новая
       47

Как следует задокументировать класс, основанный на командном шаблоне, в YARD

0 голосов
/ 09 июля 2020

При создании проекта в Ruby я должен документировать каждый важный фрагмент кода с помощью RDo c, используя YARD, основная часть работы выполняется с помощью классов шаблонов команд (из GOF).

Основная структура шаблона команды похожа на эту: 

class Command
  def initialize(specific, params, for, command); end
  def execute
    # The specific code goes here
  end
end

Таким образом, определение команды - это в основном имя класса, и вместо вызова их методов выполнения с указанными параметрами c , вы готовите их заранее, а затем просто вызываете execute.

Итак, имеет ли смысл документировать метод initialize или Class следует документировать, вот мои альтернативы:

Метод "classi c" YARD (я никоим образом не разбираюсь в документации) 

# Generates a reservation for a user in an hotel room in certain date
class ReserveHotelRoom < Command
  # Initializes the Use Case
  # @param user [User] user which is making the reservation
  # @param hotel [Hotel] hotel which is being booked
  # @param room [String] room number/name
  # @param date [Datetime] date for the reservation
  def initialize(user:, hotel:, room:, date:); end
end

Я думаю, что наиболее «правильным» способом должно быть что-то вроде этого, но как бы ломает YARD, потому что я не получаю полной поддержки от его лейблов. 

# Generates a Reservation for a user in an hotel room in a certain date
# @!attribute user [User]
# @!attribute hotel [Hotel] hotel which is being booked
# @!attribute room [String] room number/name
# @!attribute date [Datetime] date for the reservation
class ReserveHotelRoom < Command
  # No documentation should be necessary inside because everything is 'standard'
end
...