Project

General

Profile

DocumenterHowTo » History » Version 2

Version 1 (Eric Hodel, 10/07/2011 06:36 AM) → Version 2/3 (Zachary Scott, 12/02/2013 12:26 AM)

=begin
((<This = DocumenterHowTo

This
page has moved 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 documenting-ruby.org|URL:http://documenting-ruby.org/documentation-guidelines.html>))
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.

=end