Documenting Ruby on Rails models with YARD

Question

I'm using YARD for my Ruby on Rails application documentation. I have simple model that looks like this:

# frozen_string_literal: true

# {Patient} is model responsible for storing patient personal informations.
#
# @!attribute id
#   @return [UUID] ID of the {Patient} in UUID format.
#
# @!attribute name
#   @return [String] Name of the {Patient}.
#
# @!attribute gender
#   @return [String] Gender of the {Patient}.
#
# @!attribute date_of_birth
#   @return [Date] Date of birth of the {Patient}.
#
# @!attribute created_at
#   @return [DateTime] Time when {Patient} was created.
#
# @!attribute updated_at
#   @return [DateTime] Time when {Patient} was updated.

class Patient < ApplicationRecord
  # == Relationships ========================================================
  belongs_to :organization

  # == Validations ==========================================================
  validates :name,          presence: true
  validates :date_of_birth, presence: true
  validates :gender,        inclusion: { in: Constants::GENDERS }
end

How can I document with YARD my Relationships and Validations? I saw that there is gem https://github.com/theodorton/yard-activerecord but it was not updated for 6 years.

Answer 1

ruby gem annotate is a way to auto-document your functions based on your database

Answer 2

I know, this is an old post, but I see some logic behind it. When you are working with developers who are not so experienced so they might not know by heart what methods a belongs_to generates, it makes sense to document it. But does not make sense to do it by hand! Please don't look at the question from your 10-15-20 years of experience. Also, having that kind of documentation would make the learning curves of the developers much lower.