RDoc - Ruby 文档系统

概述

RDoc 为 Ruby 项目生成超文本文档和命令行文档。RDoc 包括基于命令行的工具 rdoc 和 ri 。

生成文档

一旦安装成功，你就可以利用 rdoc 命令生成文档

$ rdoc [options] [names...]

获取最新选项参数，键入

$ rdoc --help

最典型的应用就是为一个 Ruby 项目生成文档（例如 RDoc 自己）。

$ rdoc

这个命令为所有的当前文件夹及子文件夹内的所有 Ruby 和 C 文件生成文档。生成的文档 存储在 rdoc 文件夹内。

你可以给你的读者推送一个能够包含主要信息的页面作为主页。例如，我们使用了

rdoc --main README.rdoc

此时你会发现你在注释中使用的各种格式技巧都会展示出来。

RDoc 通过文件扩展名来判断如何处理文件。凡是以 .rb 和 .rbw 结尾的被认定 为 Ruby 源文件，凡是以 .c 结尾的被认定为 C 文件，其他文件被认定为标识文件 （不管是不是以 ‘#’ 开始）files. 如果目录被传递给 RDoc，那么将直解析 C 和 Ruby 文件。

生成文档使用 rake 查看 RDoc::Task。

通过程序生成文档：

gem 'rdoc'
require 'rdoc/rdoc'

options = RDoc::Options.new
rdoc.document options
# see RDoc::RDoc

编写文档

编写 RDoc 文档就是在每个类、模块、方法、常量或者属性上面添加你认为需要说明的注释 就可以了：

  ##
  # 这个类通过一系列的点了表示任意多边形。

  class Shape

    ##
    # 新多边形通过一系列 +polyline+ 描述。
    #
    # 如果 +polyline+ 终点与起始点非同一点，默认使用起始点作为终点。
    #
    # 如果线产生交叉将发生 ArgumentError 错误，形状可能异形。

    def initialize polyline
      # ...
    end

  end

文档默认使用 RDoc::Markup 格式，另外 TomDoc 格式，Markdown 格式和 RD 格式也支持。你可以通过设置 .rdoc_options 文件里的默认格式选项而为整个项目设置格式。关于创建文件说明可以查看 RDoc::Options 的保存参数。你也可以通过 markup: 命令为当个文件设置注释格式，但这仅限于你想要尝试使用一下不同风格注释格式时使用。 参见 RDoc::Markup 的其他命令。

注释可以通过命令告诉 RDoc 不解析某些信息从而隐藏。查看 RDoc::Markup 命令 来控制文档解析、定义方法参数或者在类中安主题分类方法。查看 RDoc::Parser::Ruby 了解常用元编程方法。

关于使用 RDoc 生成 C 文件的文档参考 RDoc::Parser::C。

检测你的项目是否准备好了文档可以运行 rdoc -C lib 来生成报告。 rdoc -C1 lib 会包含文档参数名字。