DocumenterHowTo » History » Version 1

Eric Hodel, 10/07/2011 06:36 AM
Add page for documentation guidelines

1 1 Eric Hodel
=begin
2 1 Eric Hodel
= DocumenterHowTo
3 1 Eric Hodel
4 1 Eric Hodel
This page shows the recommended format for writing documentation and provides guidelines for writing documentation for ruby.
5 1 Eric Hodel
6 1 Eric Hodel
== Classes
7 1 Eric Hodel
8 1 Eric Hodel
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.
9 1 Eric Hodel
10 1 Eric Hodel
Internal classes should contain an overview of the library and examples of its specific use.
11 1 Eric Hodel
12 1 Eric Hodel
If a class is an implementation detail it should be documented to provide a guide for future maintainers.  It may be marked with # :nodoc:
13 1 Eric Hodel
14 1 Eric Hodel
== Methods
15 1 Eric Hodel
16 1 Eric Hodel
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.
17 1 Eric Hodel
18 1 Eric Hodel
If a method is an implementation detail it should be documented to provide a guide for future maintainers.  It may be marked with # :nodoc:
19 1 Eric Hodel
20 1 Eric Hodel
=== Method arguments
21 1 Eric Hodel
22 1 Eric Hodel
Where the argument list is complicated ((|call-seq|)) should be used to describe the how to call the method.  From Array::new:
23 1 Eric Hodel
24 1 Eric Hodel
  call-seq:
25 1 Eric Hodel
    Array.new(size=0, obj=nil)
26 1 Eric Hodel
    Array.new(array)
27 1 Eric Hodel
    Array.new(size) {|index| block }
28 1 Eric Hodel
29 1 Eric Hodel
Method arguments should be surrounded in "+", not "_", "<code>", "<tt>" or "<i>".  This allows ((|rdoc -C2|)) to find undocumented method parameters.  From Array::new:
30 1 Eric Hodel
31 1 Eric Hodel
  Returns a new array.  In the first form, the new array is empty, or it is
32 1 Eric Hodel
  created with +size+ copies of +obj+ (that is, +size+ references to the
33 1 Eric Hodel
  same +obj+).  The second form creates a copy of the array passed as a
34 1 Eric Hodel
  parameter (the array is generated by calling to_ary on the parameter). In
35 1 Eric Hodel
  the last form, an array of the given size is created. Each element in this
36 1 Eric Hodel
  array is calculated by passing the element's index to the given block and
37 1 Eric Hodel
  storing the return value.
38 1 Eric Hodel
39 1 Eric Hodel
== General Guidelines
40 1 Eric Hodel
41 1 Eric Hodel
Documentation should be written RDoc format unless the library maintainer chooses otherwise.
42 1 Eric Hodel
43 1 Eric Hodel
Avoid placing class names and method names in "+", "<code>" or "<tt>".  This allows rdoc to create cross-references between various pages of documentation.
44 1 Eric Hodel
45 1 Eric Hodel
Documentation should be wrapped at 80 columns.
46 1 Eric Hodel
47 1 Eric Hodel
Submit documentation formatting patches separately from patches that add new content.
48 1 Eric Hodel
49 1 Eric Hodel
=end