Ruby 编程/RubyDoc

← 单元测试 | RubyGems →

标准 Ruby 库提供了一个从自文档代码生成文档的工具，称为RubyDoc，简称 RDoc。尽管它是标准库的一部分，但 RDoc 不是你需要需要使用的文件。相反，它包含一个名为rdoc的命令行程序和一个用于从 Ruby 和 C 代码中解析特殊格式的注释的库。

一个简单的例子

以下是文件simpleNumber.rb的内容，它包含一个类SimpleNumber

# This file is called simpleNumber.rb
# It contains the class SimpleNumber

class SimpleNumber

  def initialize( num )
    raise if !num.is_a?(Numeric)
    @x = num
  end

  def add( y )
    @x + y
  end

  def multiply( y )
    @x * y
  end

end

为了开始，运行rdoc在这个文件上

>> rdoc simpleNumber.rb

                    simpleNumber.rb: c...
Generating HTML...

Files:   1
Classes: 1
Modules: 0
Methods: 3
Elapsed: 0.426s

快速浏览一下就会发现rdoc创建了一个名为doc/的新目录。它包含相当多的文件（鉴于如此简单的类！）

>> ls doc/
classes      files                fr_file_index.html    index.html
created.rid  fr_class_index.html  fr_method_index.html  rdoc-style.css

打开文件doc/index.html在网络浏览器中，找到

RDoc 做了什么？首先，它扫描了给定的文件（显示在左上角窗格中）。中间窗格列出了simpleNumber.rb中的所有类，而右侧窗格则提供了 SimpleNumber 中的所有方法。在这种情况下，底部的窗格显示了文件simpleNumber.rb的摘要信息，这些信息是从文件中顶层的注释中提取的。一旦我们选择一个类或函数，它将显示更多具体的信息。

处理多个文件

命令行中包含的任何目录都将被搜索 Ruby 文件（带有.rb或.rbw扩展名）和 C 文件（带有.c扩展名）。rdoc 将递归地进行搜索，这使得它方便地为代码的大型树结构进行文档化。如果没有指定源文件，RubyDoc 将从当前目录开始搜索。输出始终生成在当前位置下的目录doc/中。

默认情况下，任何未被识别为 Ruby 或 C 的文件都不会被解析，但可以作为 rdoc 的命令行参数包含。在这种情况下，它们被视为 SimpleMarkup（见下文）——一般来说，它们将只作为 HTML 文档中的纯文本文件进行浏览。

RDoc 格式

RDoc 使用一个名为 SimpleMarkup 的格式系统来进行其标记目的。SimpleMarkup 是一个简化的基于文本的标记系统，类似于许多维基标记语言。以下是一个简要概述

在左边缘对齐的连续行（在文本文件中为第 0 列，或在源文件中为注释字符和空格之后）被视为一个段落。空行开始一个新段落。
如果一行以 "*", "-" 或 "<a digit>" 开头，则以下信息是一个列表项，可以是不带编号的或带编号的。所有后续行应缩进以匹配列表项第一行的文本。以下是一个例子（来自 RDoc 文档）

* this is a list with three paragraphs in
   the first item. This is the first paragraph.

   And this is the second paragraph.

   1. This is an indented, numbered list.
   2. This is the second item in that list

   This is the third conventional paragraph in the
   first list item.

* This is the second item in the original list

列表可以被标记。每个标签必须在方括号内或后面跟着两个冒号

    [cat]  a small furry mammal
           that seems to sleep a lot

    [ant]  a little insect that is known
           to enjoy picnics

    cat::  a small furry mammal
           that seems to sleep a lot

    ant::  a little insect that is known
           to enjoy picnics

任何超出当前左边缘开始的行都被视为逐字文本（例如，程序代码）
任何以一个或多个等号开头的行都是一个标题。一个等号是顶级标题，两个等号是二级标题，等等。
三条或更多条短线在一行中构成水平线。
基本文本标记
- 可以使用标签，包括用于*粗体文本*的星号，用于_强调_文本的下划线，以及用于+代码+文本的加号。
- 或者，可以使用 HTML 标签。

链接到其他方法

要链接到其他方法，请像 ri 一样格式化它们，例如

# same as the #read method of the

你可以避免创建像

\#method_name

（不会链接）和

\Win32

这样的链接，用于不应该链接到已知类名的驼峰式命名法。

链接到 URL

以下是一个例子

# For detail, see the msdn[http://msdn.microsoft.com].

使用 RDoc 与 RI

包含图表

如果程序dot来自Graphviz可用，RDoc 将生成类层次结构图作为 HTML 文档的一部分。可以通过命令行选项--diagram或-d.

启用此行为

[编辑 | 编辑源代码]

警告 : 此功能仅在 Ruby 1.8.X 中可用；从 Rdoc for Ruby 1.9.X 开始，对该功能的支持已取消。RDoc 可用于从文件的注释中生成命令行使用字符串（段落）。这是通过类方法RDoc::usage

# TestRDocUsage: A useless file
#
#  Usage:  ruby testRDocUsage.rb  [options]
#

require 'rdoc/usage'

RDoc::usage

完成的。以下是一个例子

>> ruby testRdocUsage.rb 
TestRDocUsage: A useless file

 Usage:  ruby testRDocUsage.rb  [options]

当运行时RDoc 可用于从文件的注释中生成命令行使用字符串（段落）。这是通过类方法并不特别有趣。RDoc 可用于从文件的注释中生成命令行使用字符串（段落）。这是通过类方法可以接受两种类型的命令行选项。如果第一个参数是整数，则该值将用作应用程序的退出代码（是的，

#= Overview
# TestRDocUsage: A useless file
#
#= Usage
#
#  Usage:  ruby testRDocUsage.rb  [options]
#

require 'rdoc/usage'

RDoc::usage('Usage')

终止应用程序）。任何进一步的（字符串）参数都调用出应使用的介绍性注释的部分。以下是一个稍复杂一点的上述例子的版本

>> ruby testRdocUsage.rb 

USAGE
=====
  Usage:  ruby testRDocUsage.rb  [options]

这次有节标题。运行脚本给出RDoc 可用于从文件的注释中生成命令行使用字符串（段落）。这是通过类方法其中只包含“使用”部分（作为

的参数调用）。

[编辑 | 编辑源代码]

-a, --all: 解析所有类方法，而不仅仅是公共方法。
-x, --exclude pattern: 从搜索中排除与pattern匹配的文件/目录。在命令行中明确包含的文件永远不会被排除。

外部链接

RDoc 文档（使用 RDoc 生成！）位于Ruby-Doc

问题

如何在 Gem 中发布 RDoc 时包含外部图像文件？RDoc 会将图像转换为 html！