RDOC

RDOC是通过从源代码来生成文档的工具，可以生成HTML格式或者ri格式，前提就是我们要在源代码中添加足够的注释 。

注释可以以#开头，也可以放在=being...=end之间，如果你用=being...=end,那么=being后面必须要加一个rdoc标志，以便能区别文档的格式 。
比如:

= begin rdoc
Calculate the minimal - cost path though the graph
using Debrinkski ' s algorithm, with optimized
inverse pruning of isolated leaf nodes.
=end
def calculate_path
  
end

这些注释可以被标记起来，为了使单词呈现出italic,bold,typewriter，你可以使用_word_,*word*,+word+来表示。如果你要将一长段语句呈现上述效果，可以这样:<em>words</em>,<b>words</b>,<tt>words</tt>
当遇到#--时RDoc停止处理注释，当遇到#++时RDOC又开始处理注释。
比如:

#  Extract the age and calculate the
#  date of birth.
# --
#  FIXME: fails if the birthday falls on
#  February 29th, or if the person
#  was born before epoch and the installed
#  Ruby doesn't support negative time_t
# ++
#  The DOB is returned as a Time object.
# --
#  But should probably change to use Date.
def get_dob(person)
           
end

则生成的HTML文档中的主注释为

Extract  the age and calculate the  date  of birth . The DOB is returned  as  a  Time   object .

列表
当要在声称的HTML中显示列表时，可以这样：
1. 以 *或者-开头(当要列表以•  开头时)
2.  以一个数字加上一个句号开头（当要列表一数字排开时）
3.  以一个大写（小写）字母加上一个句号开头
比如

#  Lists are typed as indented paragraphs with:
#  * a '*' or '-' (for bullet lists)
#  * a digit followed by a period for
#    numbered lists
#  * an upper or lower case letter followed
#    by a period for alpha lists.

则生成的效果为

Lists are typed  as  indented paragraphs with :

• a ’*’ or ’-’ (for bullet lists)
• a digit followed by a period for numbered lists
• an upper or lower case letter followed by a period for alpha lists.

带标签的列表（也称描述列表）是这样产生的：用[]把标签括起来
比如

#  [cat]   small domestic animal
#  [+cat+] command to copy standard input
#          to standard output

也可以在标签后面加2个冒号来达到同样的效果

#  cat::   small domestic animal
#  +cat+:: command to copy standard input
#          to standard output

看下面这段注释 :

#  <tt>--output</tt> <i>name [, name]</i>::
#      specify the name of one or more output files. If multiple
#      files are present, the first is used as the index.
#
#  <tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
#                      index areas, or bit ratios of units as
#                      they are processed.

它所产生的效果为:

—output name [, name]:	specify the name of one or more output files. If multiple files arepresent, the first is used as the index.
—quiet::	do not output the names, sizes, byte counts, index areas, or bit ratios ofunits as they are processed.

Headings
要产生<h1><h2><h3>等等的效果，可以以连续的=开头，比如<h1>就是# =,<h2>就是# ==,<h3>就是# ===,等等

水平线可以用三个或者3个以上的-表示，比如# -----

改变文档行为
方法的参数列表按照方法的申明来展开和显示。如果方法里面出现了yield,那么传递给yield的参数也会在最终文档中显示出来。例如
def fred
  ...
  yield line, address
得到的文档就会是这个样子：
fred() {|line, address| ... }

你能够改写这种行为，方法是在方法名称的同一行加上注释:yields: ...  比如：
def fred      # :yields: index, position
  ...
  yield line, address
则得到的文档就会是这个样子：
fred() {|index, position| ... }

:yields:只是改变文档行为的一种，其他的还包括：
:nodoc: [all]
    不再文档中包含这一部分
:doc:
    强迫一个方法或者属性编译进文档。对于想把一个private方法编进文档很有用
:notnew:

其他的命令：
:call-seq: lines...
:include: filename
:title: text
:main: name
:stopdoc:  /  :startdoc:
:endoc: