While building a Project in Ruby I am required to document every important piece of code with RDoc, using YARD, the bulk of the work is done via Command Patterns Classes (from GOF).
The main structure of a Command Pattern is similar to this one:
class Command
def initialize(specific, params, for, command); end
def execute
# The specific code goes here
end
end
So the definition of the Command is basically the Class name, and instead of calling their execute methods with the specific parameters, you prepare them beforehand and then you just call execute.
So, does it make sense to document the initialize method or should the Class should be documented, here are my alternatives:
The "classic" YARD way (I'm in no way an expert in documentation)
# 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
I think that a most "proper" way should be something like this, but kind of breaks YARD because I don't get the full support from its labels.
# 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
