您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

Ruby on Rails 開發從頭來（十八）：使用 RDoc 自動產生專案文件

編輯：Java 相關知識

RDoc 簡介

RDoc 是 Ruby 內建文件產生工具，從原始碼註解提取類別、模組、方法、屬性文件，產生 HTML 格式 API 文件。

產生文件指令

depot> rake appdoc

或直接呼叫：

depot> rdoc --main README --title "Depot API" app lib

文件輸出結構

doc/
├── index.html          # 專案首頁
├── classes/            # 類別/模組文件
│   ├── Product.html
│   ├── StoreController.html
│   └── ...
├── files/              # 原始碼檔案列表
│   ├── app_models_product_rb.html
│   └── ...
├── css/                # 樣式表
└── js/                 # 搜尋腳本

撰寫 RDoc 相容註解

# 類別/模組說明
# 可用多行描述功用、用法範例
class Product < ActiveRecord::Base
  # 方法說明：計算含稅價格
  # @param tax_rate [Float] 稅率 (0.05 表 5%)
  # @return [BigDecimal] 含稅價格
  def price_with_tax(tax_rate = 0.05)
    price * (1 + tax_rate)
  end
  
  # 屬性說明
  # @return [String] 商品標題
  attr_reader :title
end

常用 RDoc 標籤

標籤	用途	範例
`@param`	參數說明	`@param name [Type] description`
`@return`	回傳值說明	`@return [Type] description`
`@raise`	拋出例外說明	`@raise [ActiveRecord::RecordNotFound] if not found`
`@example`	用法範例	`@example product.price_with_tax(0.05)`
`@see`	參考連結	`@see https://api.rubyonrails.org`
`@author`	作者	`@author John Doe`
`@version`	版本	`@version 1.2.3`
`@deprecated`	標記棄用	`@deprecated Use new_method instead`