All notes
Rdoc

Command line

rdoc reference.



# Quickly test the RDoc output with the following command:
echo "+:to_param+" | rdoc --pipe
# => <p><code>:to_param</code></p>

Use in Rails

rubyOnRails: API doc guidelines.


bundle exec rake rdoc
# Resulting HTML files can be found in the ./doc/rdoc directory.

Some guidelines

Use gender neutral pronouns (they/their/them) instead of he/she/him/her/his/hers.

Use American English (color, center, modularize, etc).

Use the Oxford comma ("red, white, and blue", instead of "red, white and blue").

General

Paragraphs, verbatim

Paragraphs are lines that share the left margin.

Text indented past this margin are formatted verbatim.

Links

Any names containing an underscore or preceded by a hash character are automatically hyperlinked from comment text to their description.

Lists


# Unordered lists
* item 1
- item 2

# Ordered lists
1. item 1
1. item 2

# Labeled lists (or description lists) are typed using square brackets for the label.
[cat]   small domestic animal
[+cat+] command to copy standard input

# Result in tabular form, so the descriptions all line up.
# This was used to create the 'author' block at the bottom of this description.
cat::   small domestic animal
+cat+:: command to copy standard input

Headings, Rules


= Level One Heading
== Level Two Heading

# Horizontal lines
---

nodoc, doc

Mark it as ":nodoc:" and it's removed from public documentation.


module ActiveRecord::Core::ClassMethods
  def arel_table #:nodoc:
    # do some magic..
  end
end

# In the following code, only class SM::Input will be documented.
module SM  #:nodoc:
  class Input
  end
end
module Markup #:nodoc: all
  class Output
  end
end

":doc:" force a method to be documented even if it wouldn't otherwise be.

Hidden comment

Stops processing comments if it finds a comment line containing '#--'. Commenting can be turned back on with a line that starts '#++'.


# Extract the age and calculate the
# date-of-birth.
#--
# FIXME: fails if the birthday falls on
# February 29th
#++
# The DOB is returned as a Time object.

def get_dob(person)
   ...

yield

If a method calls yield, then the parameters passed to yield will also be displayed:


def fred
  ...
  yield line, address

# This will get documented as
fred() { |line, address| ... }

Fonts

Fixed-width font



class Array
  # Calls +to_param+ on all its elements and joins the result with
  # slashes. This is used by +url_for+ in Action Pack.
  def to_param
    collect { |e| e.to_param }.join '/'
  end
end

# Please use <tt>...</tt> for everything else, notably class or module names with a namespace as in <tt>ActiveRecord::Base</tt>.

Example codes



##### Short

# Converts a collection of elements into a formatted string by
# calling +to_s+ on all elements and joining them.
#
#   Blog.all.to_formatted_s # => "First PostSecond PostThird Post"

##### Long example with a separate "Examples" section

# ==== Examples
#
#   1.even? # => false
#   1.odd?  # => true
#   2.even? # => true
#   2.odd?  # => false