我的书签
添加书签
移除书签附录 A：使用 RDOC 记录 Ruby
RDoc 是描述源代码文档格式的工具。RDoc 工具是 Ruby 的标准工具，可以处理 Ruby 代码文件和 C 代码 Ruby 类库，以便提取文档并对其进行格式化，以便它可以显示，例如在 Web 浏览器中。可以以源代码注释的形式显式添加 RDoc 文档。RDoc 工具还可以提取源代码本身的元素，以提供类，模块和方法的名称以及方法所需的任何参数的名称。
以 RDoc 处理器可访问的方式记录你自己的代码很容易。你可以在记录代码之前编写一组普通的单行注释（例如类或方法），也可以编写由 =begin rdoc 和 =end 分隔的嵌入式多行注释。请注意，rdoc 必须跟随 =begin 后，否则 RDoc 处理器将忽略注释块。
如果要生成文档，只需从命令提示符运行 RDoc 处理器即可。要为单个文件生成文档，请输入 rdoc，后跟文件名：
rdoc rdoc1.rb
要为多个文件生成文档，请在 rdoc 命令后输入以空格分隔的文件名：
rdoc rdoc1.rb rdoc2.rb rdoc3.rb
Rdoc 工具将创建一个格式良好的 HTML 文件（index.html），顶部有三个窗格，底部有四个较大的窗格。三个顶部窗格显示文件，类和方法的名称，而底部窗格显示文档。
HTML 包含超链接，以便你可以单击类和方法名称以导航到关联的文档。文档放在它自己的子目录 \doc 中，还有许多必需的 HTML 文件和一个样式表来应用格式。
你可以通过在单个单词或多个单词周围的标签周围放置格式字符来为 RDoc 注释添加额外的格式。使用 * 和 * 表示粗体，_ 和 _ 表示斜体，+ 和 + 表示’打字机’字体。较长文本的等效标记为 <b> 和 </b> 表示粗体，<em> 和 </em> 表示斜体，<tt> 和 </tt> 表示打字机字体。
如果要从 RDoc 文档中排除注释或注释的一部分，可以将它放在 #-- 和 #++ 注释标记之间，如下所示：
#--# This comment won‟t appear# in the documentation#++# But this one will
还有各种特殊说明，包含在冒号对之间。例如，如果要添加要在浏览器栏中显示的标题，请使用 :title:，像这样：
#:title: My Fabulous RDoc Document
RDoc 提供了更多选项，使你能够以各种方式格式化文档，并以其它格式输出来替代 HTML 格式。如果你真的想要掌握 RDoc，请务必阅读完整的文档：
