YARD for documentation in Ruby - Mini Project: Build & Apply

Documenting Ruby Code with YARD

📖 Scenario: You are working on a small Ruby project that calculates areas of different shapes. To help your team understand your code better, you want to add clear documentation using YARD, a popular Ruby documentation tool.

🎯 Goal: Learn how to write YARD documentation comments for Ruby methods and classes, so your code is easy to understand and maintain.

📋 What You'll Learn

Create a Ruby class with methods

Add YARD documentation comments to the class and methods

Use tags like @param and @return in the comments

Print the result of method calls to verify functionality

💡 Why This Matters

🌍 Real World

Clear documentation helps teams understand code quickly and reduces bugs when working on projects together.

💼 Career

Many Ruby jobs require writing and maintaining well-documented code using tools like YARD to improve code quality and collaboration.

1

Create a Ruby class with methods

Create a Ruby class called ShapeCalculator with two methods: area_of_square that takes side as a parameter and returns the area of the square, and area_of_circle that takes radius as a parameter and returns the area of the circle (use 3.14 for π).

Ruby

# Create the ShapeCalculator class with two methods
class ShapeCalculator
  # Your code here
end

Need a hint?

Define a class with class ShapeCalculator and add two methods with def. Use simple math to calculate areas.

2

Add YARD documentation comments to the class

Add a YARD documentation comment above the ShapeCalculator class that briefly describes the class purpose using # comments.

Ruby

# Add a YARD comment describing the ShapeCalculator class
# Your code here
class ShapeCalculator
  def area_of_square(side)
    side * side
  end

  def area_of_circle(radius)
    3.14 * radius * radius
  end
end

Need a hint?

Use # to write a short description above the class definition.

3

Add YARD documentation comments to methods

Add YARD documentation comments above both methods. For area_of_square, add @param side [Numeric] and @return [Numeric] tags. For area_of_circle, add @param radius [Numeric] and @return [Numeric] tags. Also add a short description for each method.

Ruby

# Add YARD comments for both methods
# Your code here
# Calculates areas of different shapes
class ShapeCalculator
  def area_of_square(side)
    side * side
  end

  def area_of_circle(radius)
    3.14 * radius * radius
  end
end

Need a hint?

Use # comments with @param and @return tags above each method.

4

Print results of method calls

Create an instance of ShapeCalculator called calculator. Then print the result of calculator.area_of_square(4) and calculator.area_of_circle(3).

Ruby

# Create an instance and print the results
# Your code here
# Calculates areas of different shapes
class ShapeCalculator
  # Calculates the area of a square
  # @param side [Numeric] the length of one side of the square
  # @return [Numeric] the area of the square
  def area_of_square(side)
    side * side
  end

  # Calculates the area of a circle
  # @param radius [Numeric] the radius of the circle
  # @return [Numeric] the area of the circle
  def area_of_circle(radius)
    3.14 * radius * radius
  end
end

Need a hint?

Create an object with ShapeCalculator.new and use puts to print method results.