Documentation Guidelines

This page shows the recommended format for writing documentation and provides guidelines for writing documentation for ruby.

Classes

Top-level classes should contain an overview of the library explaining why you would want to use the library and some small examples showing the major features of the library. For an example see the documentation for Net::HTTP or OpenSSL.

Internal classes should contain an overview of the library and examples of its specific use.

If a class is an implementation detail it should be documented to provide a guide for future maintainers. It may be marked with # :nodoc:

Methods

When ruby builds ri data it runs with --all so private and protected methods will be shown to users. Be sure to document all methods.

If a method is an implementation detail it should be documented to provide a guide for future maintainers. It may be marked with # :nodoc:

Method arguments

Where the argument list is complicated call-seq should be used to describe the how to call the method. From Array::new:

call-seq:
  Array.new(size=0, obj=nil)
  Array.new(array)
  Array.new(size) {|index| block }

Method arguments should be surrounded in +, not _, <code>, <tt> or <i>. This allows rdoc -C2 to find undocumented method parameters. From Array::new:

Returns a new array.  In the first form, the new array is empty, or it is
created with +size+ copies of +obj+ (that is, +size+ references to the
same +obj+).  The second form creates a copy of the array passed as a
parameter (the array is generated by calling to_ary on the parameter). In
the last form, an array of the given size is created. Each element in this
array is calculated by passing the element's index to the given block and
storing the return value.

General Guidelines

Documentation should be written RDoc format unless the library maintainer chooses otherwise.

Avoid placing class names and method names in +, <code> or <tt>. This allows rdoc to create cross-references between various pages of documentation.

Documentation should be wrapped at 80 columns.

Submit documentation formatting patches separately from patches that add new content.