Rails API Documentation Conventions

Wording

Write simple, declarative sentences. Brevity is a plus: Get to the point.

Write in present tense: “Returns a hash that…”, rather than “Return a hash that…” or “Will return a hash that…”.

Start comments in upper case, follow regular punctuation rules:

  # Declares an attribute reader backed by an internally-named instance variable.
  def attr_internal_reader(*attrs)
    ...
  end

Communicate to the reader what’s the current way of doing things. Both explicit and implicitly. Use the recommended idioms in edge (which is the version we are documenting), reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil?

The proper name of Rails components has spaces in between: “Active Record”. Please write them like that. There’s lack of unanimity in books, but we checked it with David.

Fonts

Fixed-width font for method names when they are alone, literals like nil, false, true, self, symbols, and method parameters.

  # Copies the instance variables of +object+ into +self+.
  #
  # Instance variable names in the +exclude+ array are ignored. If +object+
  # responds to <tt>protected_instance_variables</tt> the ones returned are
  # also ignored. For example, Rails controllers implement that method.
  # ...
  def copy_instance_variables_from(object, exclude = [])
    ...
  end

When “true” and “false” are English words rather than Ruby keywords use regular font for them:

  # If <tt>reload_plugins?</tt> is false, add this to your plugin's <tt>init.rb</tt>
  # to make it reloadable:
  #
  #   Dependencies.load_once_paths.delete lib_path

Regular font as well for constants and for method names qualified by the class or module they belong to.

  # Returns the classes in the current ObjectSpace where this module has been
  # mixed in according to Module#included_modules.

Normally constants would be written using a fixed-width font, but regular font is already used all over the
docs, so we just follow this convention.

Fixed-width font for filenames:

  # This can also be set as a configuration option in <tt>config/environment.rb</tt>:
  #
  #   config.action_mailer.default_url_options = { :host => "example.com" }

Description Lists

In lists of options, parameters, etc. use a hyphen between the item and its description (reads better than a colon because normally options are symbols):

  # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+.

The description starts in upper case and ends with a full stop, it’s regular English.

Example Code

Choose meaningful examples that depict and cover the basics and also interesting points or gotchas.

Use two spaces to indent chunks of code. That is two spaces with respect to the left margin, the examples
themselves should use Rails code conventions.

Short docs do not need an explicit “Examples” label to introduce snippets, they just follow paragraphs as in

  # Converts a collection of elements into a formatted string by calling
  # <tt>to_s</tt> on all elements and joining them.
  #
  #   Blog.find(:all).to_formatted_s # => "First PostSecond PostThird Post"

On the other hand big chunks of structured documentation may have distinguished “Examples” sections:

  # ==== Examples
  #
  #   Person.exists?(5)
  #   Person.exists?('5')
  #   Person.exists?(:name => "David")
  #   Person.exists?(['name LIKE ?', "%#{query}%"])

The result of expressions follow them and are introduced by "# => ", vertically aligned.

  # For checking if a fixnum is even or odd.
  #
  #   1.even? # => false
  #   1.odd?  # => true
  #   2.even? # => true
  #   2.odd?  # => false

If the line gets too long the comment may be placed on the next line.

  #   label(:post, :title)
  #   # => <label for="post_title">Title</label>
  #
  #   label(:post, :title, "A short title")
  #   # => <label for="post_title">A short title</label>
  #
  #   label(:post, :title, "A short title", :class => "title_label")
  #   # => <label for="post_title" class="title_label">A short title</label>

In general we avoid using any printing method like puts or p for that purpose.

On the other hand, regular comments do not use an arrow:

	
polymorphic_url(record)  # same as comment_url(record)

RDoc

As of July 2008 the official documentation is generated with RDoc 2.1.

For help in RDoc you may consult its online documentation and Chapter 16 of the Pickaxe.

Gotchas

Using a pair of + for fixed-width fonts only works with words, that is anything matching \A\w+\z:

  # Use +has_many+ in the base, and +belongs_to+ in the associated model.

But <tt> is needed for anything else, notably symbols, setters, inline snippets, etc:

  # * <tt>:host</tt> - Overrides the default (current) host if provided.