YARD for documentation in Ruby - Step-by-Step Execution

Concept Flow - YARD for documentation

Write Ruby code

↓

Add YARD comments

↓

Run YARD tool

↓

YARD parses comments

↓

Generate HTML docs

↓

Open docs in browser

YARD reads special comments in Ruby code and creates easy-to-read HTML documentation.

Execution Sample

Ruby

class Calculator
  # Adds two numbers
  # @param a [Integer]
  # @param b [Integer]
  # @return [Integer]
  def add(a, b)
    a + b
  end
end

This Ruby class has a method with YARD comments describing parameters and return type.

Execution Table

Step	Action	Input/Code	YARD Processing	Output/Result
1	Read Ruby code	class Calculator ... end	Identify classes and methods	Found class Calculator and method add
2	Read comments	# Adds two numbers\n# @param a [Integer]\n# @param b [Integer]\n# @return [Integer]	Parse YARD tags	Extract method description and param info
3	Build documentation model	Parsed code and comments	Create structured doc objects	Method add documented with params and return
4	Generate HTML	Documentation model	Convert to HTML pages	HTML files created for Calculator and add
5	Open docs	HTML files	Render in browser	User sees formatted docs with descriptions and types

💡 All code and comments processed, documentation generated successfully

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
code	Ruby source code	Same	Same	Same	Same
comments	Raw comments	Parsed YARD tags	Same	Same	Same
doc_model	Empty	Empty	Filled with method info	Same	Same
html_docs	null	null	null	Created	Same

Key Moments - 3 Insights

Why do we write special comments starting with @param and @return?

These tags tell YARD what each method parameter is and what the method returns, so it can create clear documentation. See execution_table step 2 where YARD parses these tags.

Does YARD run inside Ruby code or separately?

YARD is a separate tool that reads your Ruby files and comments, then generates docs. It does not run inside the Ruby program itself. This is shown in execution_table step 3 and 4.

What happens if I forget to add YARD comments?

YARD will still generate docs but without detailed descriptions or parameter info, so docs are less helpful. This is implied by the parsing step 2 in execution_table.

Visual Quiz - 3 Questions

Look at the execution_table, at which step does YARD parse the special @param tags?

A Step 1

B Step 3

C Step 2

D Step 4

💡 Hint

Check the 'YARD Processing' column in execution_table row for step 2.

According to variable_tracker, when are HTML docs created?

A After Step 4

B After Step 3

C After Step 2

D After Step 5

💡 Hint

Look at the 'html_docs' row and see when it changes from null to Created.

If you remove all YARD comments, what changes in the execution_table?

A Step 3 will fail to build doc model

B Step 2 parsing will find no tags

C Step 4 will not generate HTML

D Step 5 will not open docs

💡 Hint

Refer to step 2 where YARD parses comments; no tags means no param info extracted.

Concept Snapshot

YARD documents Ruby code by reading special comments.
Use @param and @return tags to describe methods.
Run YARD tool to generate HTML docs.
Docs show method details and types clearly.
Helps others understand your code easily.

Full Transcript

YARD is a tool for documenting Ruby code. You write special comments above methods using tags like @param and @return to describe parameters and return values. When you run YARD, it reads your Ruby files and these comments, parses the tags, and builds a documentation model. Then it generates HTML pages that show your code's structure and explanations. Finally, you open these HTML files in a browser to see nice formatted docs. If you forget comments, YARD still works but docs lack detail. This process helps programmers share clear information about their code.