YARD for documentation in Ruby - Practice Problems & Coding Challenges

Challenge - 5 Problems

❓ Predict Output

intermediate

What is the output of this YARD documentation comment parsing?

Given the following Ruby method with YARD comments, what will be the description extracted by YARD for the method `greet`?

Ruby

##
# Greets a person with their name.
#
# @param name [String] the name of the person
# @return [String] greeting message
#
def greet(name)
  "Hello, #{name}!"
end

A "Hello, #{name}!"

B "greet method"

C "Greets a person with their name."

D "@param name [String] the name of the person"

💡 Hint

Look at the first comment line after the ## marker.

YARD uses the first comment line after the ## as the method description. The @param and @return tags provide additional metadata but are not the main description.

🧠 Conceptual

intermediate

Which YARD tag documents the return type of a method?

In YARD documentation, which tag is used to specify what a method returns?

A @return

B @param

C @yield

D @example

💡 Hint

It describes the output of the method.

The @return tag documents the return value and its type for a method in YARD.

🔧 Debug

advanced

Why does this YARD comment fail to document the method parameter?

Examine the following YARD comment and method. Why will YARD not recognize the parameter documentation correctly? ## # Calculates the square of a number. # @param num the number to square # @return [Integer] the squared result # def square(number) number * number end

Ruby

##
# Calculates the square of a number.
# @param num the number to square
# @return [Integer] the squared result
#
def square(number)
  number * number
end

A The comment block is missing the initial # marker.

B The @param tag is missing the type specification in brackets.

C The method is missing a return statement.

D The parameter name in @param does not match the method parameter name.

💡 Hint

Check if the parameter names match exactly.

YARD requires the parameter name in the @param tag to exactly match the method's parameter name to link documentation correctly.

📝 Syntax

advanced

Which YARD comment block is syntactically correct for documenting a method?

Choose the correctly formatted YARD comment block for this method: def add(a, b) a + b end

A

## Adds two numbers.
@param a [Integer]
@param b [Integer]
@return [Integer]

B

##
# Adds two numbers.
# @param a [Integer]
# @param b [Integer]
# @return [Integer]

C

# Adds two numbers.
# @param a Integer
# @param b Integer
# @return Integer

D

##
# Adds two numbers.
@param a [Integer]
@param b [Integer]
@return [Integer]

💡 Hint

YARD comment blocks start with ## and each line begins with #.

Option B uses the correct YARD syntax: a comment block starting with ## and each line starting with #, with tags properly formatted.

🚀 Application

expert

How many methods will YARD document in this Ruby class?

Consider this Ruby class with YARD comments. How many methods will YARD generate documentation for? class Calculator ## # Adds two numbers # @param x [Integer] # @param y [Integer] # @return [Integer] def add(x, y) x + y end # Subtracts y from x def subtract(x, y) x - y end ## # Multiplies two numbers # @param x [Integer] # @param y [Integer] # @return [Integer] def multiply(x, y) x * y end end

Ruby

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

  # Subtracts y from x
  def subtract(x, y)
    x - y
  end

  ##
  # Multiplies two numbers
  # @param x [Integer]
  # @param y [Integer]
  # @return [Integer]
  def multiply(x, y)
    x * y
  end
end

A 2

B 3

C 1

D 0

💡 Hint

YARD only documents methods with comment blocks starting with ##.

YARD documents methods with comment blocks starting with ##. The 'add' and 'multiply' methods have such blocks, but 'subtract' only has a single # comment, so it is not documented.

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