What Is RDoc In Ruby? The Official Ruby Documentation System

RDoc is a very powerful built-in system in Ruby that allows documentation to be generated directly from source code. This method ensures that documentation remains near to the implementation while streamlining the development process for developers.

What is (Documentation) RDoc in Ruby?

The official documentation system for Ruby is called RDoc. Like Python’s PyDoc or Java’s JavaDoc, it is a program that collects and formats documentation included in Ruby source code files.

RDoc has two primary jobs:

• It searches source files for information to document by analyzing Ruby (and C language extension) files.
• It takes this data and turns it into output that can be read.

The two primary formats in which RDoc’s documentation can be seen are ri, a local command-line viewer, and HTML, a browsable website.

How RDoc Works

RDoc documentation is produced by explicitly including specially structured comments before the methods, classes, or modules they describe in your Ruby source files.

Comment Formatting

The declaration of the element (method, class, or module) that the documentation comments are describing must appear right before it. They are usually written as multiline comments with the hash (#) character at the start of each line.

To use the RDoc tool, they must begin with =begin rdoc. Alternatively, they can be written using embedded documents, which are multiline comments that begin with =begin and conclude with =end.

RDoc Markup

Similar to wikis, RDoc employs a straightforward markup grammar that enables developers to organise the documentation in a clear and readable manner while maintaining the readability of the source comments.

RDoc Directives and Modifiers

You can control how RDoc handles the element by adding special directives in the comments or on the same line as the definition:

:nodoc:: This modifier hides an element (class, module, or method) from the documentation output.

:doc:: This compels a technique to be documented, even if it is a secret one.

:yields: arguments: This takes precedence over RDoc’s yield-based automatic detection of parameters supplied to a block.

:call-seq: lines...: This enables you to manually define the method signature (calling sequence) for documentation purposes.

Code Example: Documenting a Method

This is an illustration of how to use RDoc comments to document a basic file and its procedure:

# simple_sum.rb

# Takes any number of numeric terms and returns the sum.
# It can handle integers and floats.
#
# === Examples
#
#   sum(1, 2, 3)                             # => 6
#   sum(1, -1, 10)                           # => 10
#   sum(1.5, 0.2, 0.3, 1)                    # => 3.0

def sum(*terms)
  terms.inject(0) { |sum, term| sum + term }
end

# --- Example Outputs ---
puts "sum(1, 2, 3) = #{sum(1, 2, 3)}"
puts "sum(1, -1, 10) = #{sum(1, -1, 10)}"
puts "sum(1.5, 0.2, 0.3, 1) = #{sum(1.5, 0.2, 0.3, 1)}"

Output

sum(1, 2, 3) = 6
sum(1, -1, 10) = 10
sum(1.5, 0.2, 0.3, 1) = 3.0

When the rdoc sum.rb command is used to process this code (saved as sum.rb), RDoc creates HTML pages in the doc/ subdirectory. After parsing the comments, the indented lines are shown as samples of Ruby code.

Running RDoc

You use the rdoc command-line program to create documentation:

$ rdoc sum.rb
. Generating HTML...
Files:   1 Classes: 0 Modules: 0 Methods: 1 Elapsed: 0.101s

Rails Applications: Rake is used for Rails to automate the documentation process. RDoc is launched and the documentation website is created under doc/app/ when developers use the rake appdoc command from the application’s root directory.

Gems: Installing a Ruby gem makes the RDoc documentation available locally since it is automatically generated and installed with the program. The local documentation directory or the gem_server command are the usual ways to access this documentation.

Viewing RDoc Locally (ri)

Viewing RDoc documentation straight from the command line is possible with the ri (Ruby Interactive) command, which comes with the Ruby interpreter. This documentation is taken from the Ruby source’s specially structured comments.

You invoke ri by passing the name of a class, module, or method:

RDoc guarantees that the required API documentation is produced and kept up to date as an essential component of the programming process by acting as a vital link between your well-commented source code and an expert, easily navigable reference resource.

You can also read Ruby Domain Specific Language With Practical Code Examples