Documentation Guide

This guide discusses recommendations for documenting classes, modules, and methods in the Ruby core and in the Ruby standard library.

Generating documentation

Most Ruby documentation lives in the source files and is written in RDoc format.

Some pages live under the doc folder and can be written in either .rdoc or .md format, determined by the file extension.

To generate the output of documentation changes in HTML in the {build folder}/.ext/html directory, run the following inside your build directory:

make html

If you don’t have a build directory, follow the quick start guide up to step 4.

Then you can preview your changes by opening {build folder}/.ext/html/index.html file in your browser.

Goal

The goal of Ruby documentation is to impart the most important and relevant information in the shortest time. The reader should be able to quickly understand the usefulness of the subject code and how to use it.

Providing too little information is bad, but providing unimportant information or unnecessary examples is not good either. Use your judgment about what the user needs to know.

General Guidelines

Characters

Use only US-ASCII-compatible characters in a C source file. (If you use other characters, the Ruby CI will gently let you know.)

If want to put ASCII-incompatible characters into the documentation for a C-coded class, module, or method, there are workarounds involving new files doc/*.rdoc:

RDoc

Ruby is documented using RDoc. For information on RDoc syntax and features, see the RDoc format.

Output from irb

For code examples, consider using interactive Ruby, irb.

For a code example that includes irb output, consider aligning # => ... in successive lines. Alignment may sometimes aid readability:

a = [1, 2, 3] #=> [1, 2, 3]
a.shuffle!    #=> [2, 3, 1]
a             #=> [2, 3, 1]

Headings

Organize a long discussion for a class or module with headings.

Do not use formal headings in the documentation for a method or constant.

In the rare case where heading-like structures are needed within the documentation for a method or constant, use bold text as pseudo-headings.

Blank Lines

A blank line begins a new paragraph.

A code block or list should be preceded by and followed by a blank line. This is unnecessary for the HTML output, but helps in the ri output.

Method Names

For a method name in text:

Embedded Code and Commands

Code or commands embedded in running text (i.e., not in a code block) should marked up as monofont.

Code that is a simple string should include the quote marks.

Auto-Linking

Most often, the name of a class, module, or method is auto-linked:

- Float.
- Enumerable.
- File.new
- File#read.

renders as:

In general, RDoc’s auto-linking should not be suppressed. For example, we should write just plain Float (which is auto-linked):

Returns a Float.

which renders as:

Returns a Float.

However, do suppress auto-linking when the word in question does not refer to a Ruby entity (e.g., some uses of Class or English):

\Class variables can be tricky.

renders as:

Class variables can be tricky.

Also, do suppress auto-linking when the word in question refers to the current document (e.g., Float in the documentation for class Float).

In this case you may consider forcing the name to monofont, which suppresses auto-linking, and also emphasizes that the word is a class name:

A +Float+ object represents ....

renders as:

A Float object represents .…

For a very few, very often-discussed classes, you might consider avoiding the capitalized class name altogether. For example, for some mentions of arrays, you might write simply the lowercase array.

Instead of:

For an empty Array, ....

which renders as:

For an empty Array, ....

you might write:

For an empty array, ....

which renders as:

For an empty array, ....

This more casual usage avoids both auto-linking and distracting font changes, and is unlikely to cause confusion.

This principle may be usefully applied, in particular, for:

However, it should be applied only when referring to an instance of the class, and never when referring to the class itself.

When writing an explicit link, follow these guidelines.

rdoc-ref Scheme

Use the rdoc-ref scheme for:

See section “rdoc-ref Scheme” in Links.

Use a full URL-based link for:

Doing so ensures that the link will valid even when the package documentation is built independently (separately from the core documentation).

The link should lead to a target in docs.ruby-lang.org/en/master/.

Also use a full URL-based link for a link to an off-site document.

Variable Names

The name of a variable (as specified in its call-seq) should be marked up as monofont.

Also, use monofont text for the name of a transient variable (i.e., one defined and used only in the discussion, such as n).

HTML Tags

In general, avoid using HTML tags (even in formats where it’s allowed) because ri (the Ruby Interactive reference tool) may not render them properly.

Tables

In particular, avoid building tables with HTML tags (<table>, etc.).

Alternatives:

Documenting Classes and Modules

The general structure of the class or module documentation should be:

Synopsis

The synopsis is a short description of what the class or module does and why the reader might want to use it. Avoid details in the synopsis.

Common Uses

Show common uses of the class or module. Depending on the class or module, this section may vary greatly in both length and complexity.

What’s Here Summary

The documentation for a class or module may include a “What’s Here” section.

Guidelines:

Documenting Methods

General Structure

The general structure of the method documentation should be:

Calling Sequence (for methods written in C)

For methods written in Ruby, RDoc documents the calling sequence automatically.

For methods written in C, RDoc cannot determine what arguments the method accepts, so those need to be documented using RDoc directive {call-seq:}.

For a singleton method, use the form:

class_name.method_name(method_args) {|block_args| ... } -> return_type

Example:

*  call-seq:
*    Hash.new(default_value = nil) -> new_hash
*    Hash.new {|hash, key| ... } -> new_hash

For an instance method, use the form (omitting any prefix, just as RDoc does for a Ruby-coded method):

method_name(method_args) {|block_args| ... } -> return_type

For example, in Array, use:

*  call-seq:
*    count -> integer
*    count(obj) -> integer
*    count {|element| ... } -> integer
*  call-seq:
*    <=> other -> -1, 0, 1, or nil

For a binary-operator style method (e.g., Array#&), cite self in the call-seq (not, e.g., array or receiver):

*  call-seq:
*    self & other_array -> new_array

Arguments:

Block:

Return types:

Aliases:

Synopsis

The synopsis comes next, and is a short description of what the method does and why you would want to use it. Ideally, this is a single sentence, but for more complex methods it may require an entire paragraph.

For Array#count, the synopsis is:

Returns a count of specified elements.

This is great as it is short and descriptive. Avoid documenting too much in the synopsis, stick to the most important information for the benefit of the reader.

In-Brief Examples

For a method whose documentation is lengthy, consider adding an "in-brief" passage, showing examples that summarize the method's uses.

The passage may answer some users’ questions (without their having to read long documentation); see Array#[] and Array#[]=.

Details and Examples

Most non-trivial methods benefit from examples, as well as details beyond what is given in the synopsis. In the details and examples section, you can document how the method handles different types of arguments, and provides examples on proper usage. In this section, focus on how to use the method properly, not on how the method handles improper arguments or corner cases.

Not every behavior of a method requires an example. If the method is documented to return self, you don’t need to provide an example showing the return value is the same as the receiver. If the method is documented to return nil, you don’t need to provide an example showing that it returns nil. If the details mention that for a certain argument type, an empty array is returned, you don’t need to provide an example for that.

Only add an example if it provides the user additional information, do not add an example if it provides the same information given in the synopsis or details. The purpose of examples is not to prove what the details are stating.

Many methods that can take an optional block call the block if it is given, but return a new Enumerator if the block is not given; in that case, do not provide an example, but do state the fact (with the auto-linking uppercase Enumerator):

*  With no block given, returns a new Enumerator.

Argument Description (if necessary)

For methods that require arguments, if not obvious and not explicitly mentioned in the details or implicitly shown in the examples, you can provide details about the types of arguments supported. When discussing the types of arguments, use simple language even if less-precise, such as "level must be an integer", not "level must be an Integer-convertible object". The vast majority of use will be with the expected type, not an argument that is explicitly convertible to the expected type, and documenting the difference is not important.

For methods that take blocks, it can be useful to document the type of argument passed if it is not obvious, not explicitly mentioned in the details, and not implicitly shown in the examples.

If there is more than one argument or block argument, use a labeled list.

Corner Cases and Exceptions

For corner cases of methods, such as atypical usage, briefly mention the behavior, but do not provide any examples.

Only document exceptions raised if they are not obvious. For example, if you have stated earlier than an argument type must be an integer, you do not need to document that a TypeError is raised if a non-integer is passed. Do not provide examples of exceptions being raised unless that is a common case, such as Hash#fetch raising a KeyError.

Related Methods (optional)

In some cases, it is useful to document which methods are related to the current method. For example, documentation for Hash#[] might mention Hash#fetch as a related method, and Hash#merge might mention Hash#merge! as a related method.

Methods Accepting Multiple Argument Types

For methods that accept multiple argument types, in some cases it can be useful to document the different argument types separately. It's best to use a separate paragraph for each case you are discussing.