Home

docrails 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…”.

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

Fonts

Fixed-width font for method names when they are alone, literals like nil, false, true, self, 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

Chose 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 in 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

For help about RDoc there’s online documentation, and Chapter 16 of the Pickaxe.

Gotchas

Using a pair of @+@s for fixed-width fonts only works with words, that is anything matching:

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

But use TT elements for anything else, notably symbols, setters, inline snippets, etc:

  # Raised when an error occured while doing a mass assignment to an attribute through the
  # <tt>attributes=</tt> method. The exception has an +attribute+ property that is the name of the
  # offending attribute.