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.

Practice

1. What is the main purpose of using YARD in Ruby code?

easy

A. To automatically fix syntax errors in Ruby code

B. To speed up the execution of Ruby programs

C. To write clear documentation inside the code using special comments

D. To convert Ruby code into other programming languages

Solution

1. Step 1: Understand YARD's role

   YARD is a tool to add documentation inside Ruby code using comments.

2. Step 2: Identify the correct purpose

   It helps explain code clearly, not speed execution or fix errors.

3. Final Answer:

   To write clear documentation inside the code using special comments -> Option C

4. Quick Check:

   YARD -> documentation [OK]

Hint: YARD is for documentation, not code execution [OK]

Common Mistakes:

• Thinking YARD runs or speeds up code
• Confusing YARD with debugging tools
• Assuming YARD converts code to other languages

2. Which of the following is the correct way to document a method parameter using YARD?

easy

A. # @param name [String] the user's name

B. // @param name String the user's name

C. /* @param name String the user's name */

D.

Solution

1. Step 1: Recognize Ruby comment style

   Ruby uses # for single-line comments, so YARD tags must start with #.

2. Step 2: Identify correct YARD tag syntax

   The correct format is "# @param name [Type] description".

3. Final Answer:

   # @param name [String] the user's name -> Option A

4. Quick Check:

   # -> Ruby comments [OK]

Hint: YARD tags start with # in Ruby code comments [OK]

Common Mistakes:

• Using comment styles from other languages
• Omitting square brackets around type
• Writing tags inside HTML or block comments

3. What will be the output of the following YARD comment when generating documentation?

# Adds two numbers
# @param a [Integer] first number
# @param b [Integer] second number
# @return [Integer] sum of a and b
# @example
#   add(2, 3) #=> 5
def add(a, b)
  a + b
end

medium

A. Only the method name will appear without any details

B. Syntax error because @example is not allowed

C. The code will run and print 5

D. Documentation showing method description, parameters with types, return type, and example usage

Solution

1. Step 1: Understand YARD comment tags

   The tags @param, @return, and @example describe method details for documentation.

2. Step 2: Recognize YARD output

   YARD generates HTML docs showing description, parameters, return type, and examples.

3. Final Answer:

   Documentation showing method description, parameters with types, return type, and example usage -> Option D

4. Quick Check:

   YARD tags -> detailed docs [OK]

Hint: YARD tags create detailed docs, not runtime output [OK]

Common Mistakes:

• Confusing documentation comments with code execution
• Thinking @example causes errors
• Expecting code output instead of docs

4. Identify the error in this YARD comment block:

# @param name String the user's name
# @return String greeting message
def greet(name)
  "Hello, #{name}!"
end

medium

A. Missing square brackets around the type in @param and @return tags

B. The method name should be capitalized

C. YARD comments must be placed after the method definition

D. The string interpolation syntax is incorrect

Solution

1. Step 1: Check YARD tag syntax

   YARD requires types in square brackets, e.g., [String], not just String.

2. Step 2: Verify other parts

   Method name capitalization and comment placement are correct; string interpolation is valid Ruby.

3. Final Answer:

   Missing square brackets around the type in @param and @return tags -> Option A

4. Quick Check:

   [Type] -> YARD requirement [OK]

Hint: Always put types in square brackets in YARD tags [OK]

Common Mistakes:

• Omitting square brackets around types
• Placing comments after method instead of before
• Confusing Ruby syntax errors with documentation errors

5. You want to document a Ruby class with YARD that has a method returning a hash with keys as symbols and values as arrays of strings. Which is the best way to write the @return tag for this method?

hard

A. # @return [Hash] a hash with keys and values

B. # @return [Hash{Symbol => Array<String>}] a hash mapping symbols to arrays of strings

C. # @return [Array<Hash>] an array of hashes

D. # @return [Hash(Symbol, Array)] a hash with symbol keys and array values

Solution

1. Step 1: Understand complex type syntax in YARD

   YARD supports detailed type annotations like Hash{KeyType => ValueType}.

2. Step 2: Match the method return type

   The method returns a hash with Symbol keys and Array of String values, so use Hash{Symbol => Array<String>}.

3. Final Answer:

   # @return [Hash{Symbol => Array<String>}] a hash mapping symbols to arrays of strings -> Option B

4. Quick Check:

   Hash{Key => Value} -> correct syntax [OK]

Hint: Use Hash{KeyType => ValueType} for detailed return types [OK]

Common Mistakes:

• Using vague types like just Hash
• Incorrect syntax like Hash(Symbol, Array)
• Confusing array of hashes with hash of arrays