YARD for documentation in Ruby

Introduction

YARD helps you write clear notes inside your Ruby code. These notes explain what your code does, so others (and you) can understand it easily later.

When you want to explain what a method or class does in your Ruby program.

When you want to create easy-to-read documentation for your Ruby project.

When you want to help teammates understand your code without reading every line.

When you want to generate HTML pages that show your code's documentation.

When you want to keep your code and its explanation together in one place.

Syntax

Ruby

# Use special comments starting with @ to describe code elements
# @param name [Type] description
# @return [Type] description
# @example
#   example code here

YARD comments start with a # and use @tags like @param and @return to explain code parts.

You write these comments just before the method, class, or module you want to document.

Examples

This example shows how to document a simple method with parameters and return type.

Ruby

# Adds two numbers
# @param a [Integer] the first number
# @param b [Integer] the second number
# @return [Integer] the sum of a and b
def add(a, b)
  a + b
end

This example documents a class and its attribute.

Ruby

# Represents a person
# @!attribute [r] name
#   @return [String] the person's name
class Person
  attr_reader :name
  
  # Initialize with a name
  # @param name [String] the person's name
  def initialize(name)
    @name = name
  end
end

This example includes an example usage inside the documentation.

Ruby

# Calculates factorial
# @param n [Integer] number to calculate factorial for
# @return [Integer] factorial of n
# @example
#   factorial(5) #=> 120
def factorial(n)
  return 1 if n <= 1
  n * factorial(n - 1)
end

Sample Program

This program defines a Calculator class with documented methods. It then creates an object and prints results of add and multiply.

Ruby

# Calculator class
# Performs basic math operations
class Calculator
  
  # Adds two numbers
  # @param x [Integer] first number
  # @param y [Integer] second number
  # @return [Integer] sum of x and y
  def add(x, y)
    x + y
  end

  # Multiplies two numbers
  # @param x [Integer] first number
  # @param y [Integer] second number
  # @return [Integer] product of x and y
  def multiply(x, y)
    x * y
  end
end

calc = Calculator.new
puts calc.add(3, 4)
puts calc.multiply(3, 4)

Important Notes

You can generate HTML documentation by running yard doc in your project folder.

YARD supports many tags like @param, @return, @example, @see to make docs clear.

Keep your comments simple and focused on what the code does, not how it works internally.

Summary

YARD lets you write easy-to-read notes inside Ruby code to explain it.

Use special @tags in comments before methods or classes to describe parameters, returns, and examples.

You can generate nice HTML pages from these comments to share documentation.