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 &quot;+&quot;, not &quot;_&quot;, &quot;&lt;code&gt;&quot;, &quot;&lt;tt&gt;&quot; or &quot;&lt;i&gt;&quot;. 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&#x27;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 &quot;+&quot;, &quot;&lt;code&gt;&quot; or &quot;&lt;tt&gt;&quot;. 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