Ruby RDoc

Key RDoc Features

# Method description

rdoc --format=html

# :call-seq:

ri ClassName

🔹 Basic RDoc Comments

Add comments above classes, modules, and methods to document your code. RDoc extracts these comments and formats them into readable documentation with proper structure and formatting.

# This class manages user accounts
# It provides methods for creating and updating users
class User
  # Creates a new user with email and password
  # 
  # @param email [String] the user's email address
  # @param password [String] the user's password
  def initialize(email, password)
    @email = email
    @password = password
  end
  
  # Returns the user's email address
  def email
    @email
  end
end

🔹 Generating Documentation

Use the rdoc command to generate HTML documentation from your Ruby files. RDoc scans your code, extracts documentation comments, and creates a browsable website with all your code documentation.

# Generate docs for a single file
rdoc person.rb

# Generate docs for all Ruby files
rdoc *.rb

# Generate docs for a directory
rdoc lib/

# Specify output directory
rdoc --op doc lib/

# Generate with title
rdoc --title "My Project" lib/

🔹 RDoc Markup

RDoc supports special markup syntax to format your documentation. Use these markup elements to create lists, code blocks, links, and emphasized text in your generated documentation.

# = Main Heading
# == Sub Heading
# === Smaller Heading
#
# This is a paragraph with *bold* and _italic_ text.
#
# * Item 1
# * Item 2
# * Item 3
#
# 1. First
# 2. Second
# 3. Third
#
# Code example:
#   result = calculate(10, 20)
#   puts result
#
# Link: https://ruby-doc.org
class Calculator
end

🔹 RDoc Tags

Special tags provide additional information about methods and parameters. These tags help create more detailed and structured documentation that's easier for other developers to understand and use.

# :call-seq:
#   add(a, b) -> Integer
#   add(a, b, c) -> Integer
#
# Adds numbers together
def add(*numbers)
  numbers.sum
end

# :category: Utility Methods
def helper_method
  # ...
end

# :nodoc:
def internal_method
  # This won't appear in docs
end

🔹 Using ri Command

The ri command provides quick access to Ruby documentation from the terminal. Search for classes, methods, and modules without opening a browser, making it perfect for quick reference while coding.

# View class documentation
ri String

# View method documentation
ri String#upcase

# View module documentation
ri Enumerable

# Search for methods
ri -i upcase

# List all classes
ri -l

🔹 Complete Documentation Example

Here's a fully documented class showing best practices for RDoc comments. This example demonstrates proper documentation structure with descriptions, parameters, return values, and usage examples.

# = Calculator
#
# A simple calculator class for basic arithmetic operations.
#
# == Usage
#
#   calc = Calculator.new
#   result = calc.add(5, 3)
#   puts result  # => 8
#
# Author:: John Doe
# License:: MIT
class Calculator
  # Creates a new Calculator instance
  def initialize
    @history = []
  end
  
  # Adds two numbers together
  #
  # @param a [Numeric] first number
  # @param b [Numeric] second number
  # @return [Numeric] sum of a and b
  #
  # Example:
  #   calc.add(5, 3)  # => 8
  def add(a, b)
    result = a + b
    @history << result
    result
  end
  
  # Returns calculation history
  #
  # @return [Array] array of previous results
  def history
    @history
  end
end