[Idea] "Getting Started" quick start

[baweaver]

Referring to the "Getting Started" guide:

https://github.com/lsegal/yard/blob/main/docs/GettingStarted.md#documenting-code-with-yard

The initial example presented is old-format RDoc. While this is compatible with YARDoc it may be more effective for new readers to present a quick-start example of what YARDoc looks like in how YARDoc recommends you use it.

Such a quick-start would be a fast rundown of all the basic tag types one might encounter in an example class:

# A person object that does person things
#
# @author [baweaver]
# @since 0.0.1
#
class Person
  # Version of the Person gem
  VERSION = '0.0.1'.freeze

  # Name of the person
  attr_reader :name

  # Age of the person
  attr_reader :age

  # Age a person is considered an adult
  ADULT_AGE = 18

  # Creates a new person
  #
  # @param name: [String]
  #   Name of the person
  #
  # @param age: [Integer]
  #   Person's current age
  #
  # @return [Person]
  def initialize(name:, age:)
    @name = name
    @age = age
  end

  # Whether or not a person is an adult
  #
  # @return [Boolean]
  def adult?
    @age >= ADULT_AGE
  end

  # Updates a person's age
  #
  # @param years [Integer]
  #   Number of years to update, should be positive
  #
  # @return [Integer]
  #   Current age
  #
  # @raise [ArgumentError]
  #   If age is negative
  def happy_birthday!(years)
    raise ArgumentError, 'Nice try Mr. Flamel' if years < 1

    @age += years
  end
end

More than willing to write this, but wanted to run it by folks first to make sure that's something that'd be of interest.

[benoittgt]

Maybe with a preview of the result?

Or something hosted on a github.io page.