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！