API 文件指南

1 檔案

Rails API 文件是用生成的 RDoc。要生成它，請確保您是在 rails 根目錄下，執行 bundle install 並執行：

$ bundle exec rake rdoc

生成的 HTML 檔案可以在 ./doc/rdoc 目錄中找到。

請查閱 RDoc 文件以獲取有關標記，並考慮到這些額外的指令。

2 連結

Rails API 文件並不打算在 GitHub 上使用 viewed，因此連結應該使用相對於當前 API 的 RDoc link 標記。

這是由於 GitHub Markdown 與在 api.rubyonrails.org 和 edgeapi.rubyonrails.org 上釋出的生成的 RDoc 之間存在差異。

例如，我們使用 [link:classes/ActiveRecord/Base.html] 建立到 RDoc 生成的 ActiveRecord::Base 類的連結。

這優於絕對 URL，例如 [https://api.rubyonrails.org/classes/ActiveRecord/Base.html]，後者會將讀者帶到當前文件版本之外（例如 edgeapi.rubyonrails.org）。

3 措辭

寫簡單的陳述句。簡潔是一個優點：切入正題。

用現在時寫：“返回一個......的雜湊”，而不是“返回一個......的雜湊”或“將返回一個......的雜湊”。

以大寫開始註釋。遵循正常標點規則：

# 宣告一個由內部命名的屬性讀取器
# 實例變數。
def attr_internal_reader(*attrs)
  # ...
end

明確和隱含地向讀者傳達當前的做事方式。使用edge中推薦的習語。如果需要，重新排序部分以強調偏好的方法等。文件應該是 model 以獲得最佳實踐和規範的現代 Rails 用法。

文件必須簡潔但全面。探索和記錄邊緣情況。如果 module 是匿名的，會發生什麼？如果集合為空怎麼辦？如果引數為零怎麼辦？

Rails 元件的專有名稱在單詞之間有一個空格，例如“Active Support”。 ActiveRecord 是一個 Ruby module，而 Active Record 是一個 ORM。所有的 Rails 文件都應該始終以它們的專有名稱來引用 Rails 元件，如果在您的下一篇博文或簡報中您記得這個花絮並考慮到它，那將是非凡的。

正確拼寫名稱：Arel、minitest、RSpec、HTML、MySQL、JavaScript、ERB。如有疑問，請檢視一些權威來源，例如他們的官方文件。

將冠詞“an”用於“SQL”，就像在“SQL 語句”中一樣。也是“SQLite 資料庫”。

更喜歡避免“你”和“你的”的措辭。例如，代替

If you need to use `return` statements in your callbacks, it is recommended that you explicitly define them as methods.

使用這種風格：

If `return` is needed it is recommended to explicitly define a method.

也就是說，當使用代詞來指代一個假設的人時，例如“a 具有 session cookie”的使用者，性別中性代詞（他們/他們/他們）應該是用過的。代替：

他或她……使用它們。
他或她……使用它們。
他或她...使用他們的。
他或她的……使用他們的。 *他或她自己......使用自己。

4 英語

請使用美式英語（color、center、modularize 等）。請參閱此處列出美式英語和英式英語拼寫差異。

6 示例程式碼

選擇描述和包含基礎知識以及有趣的觀點或問題的有意義的例子。

使用兩個空格來縮排程式碼塊——也就是說，為了標記目的，相對於左邊距的兩個空格。示例本身應該使用 Rails 編碼約定。

簡短的文件不需要明確的“示例”標籤來引入片段；他們只是按照段落：

# 將元素集合轉換為格式化的字串
# 在所有元素上呼叫 +to_s+ 並加入它們。
#
# Blog.all.to_formatted_s # => "First PostSecond PostThird Post"

另一方面，大塊的結構化文件可能有一個單獨的“示例”部分：

# ==== 例子
#
# Person.exists?(5)
# Person.exists?('5')
# Person.exists?（姓名：“大衛”）
# Person.exists?(['name LIKE ?', "%#{query}%"])

表示式的結果跟在它們後面，並由“# =>”引入，垂直對齊：

# 用於檢查整數是偶數還是奇數。
#
# 1.偶數？ # => 假
# 1.奇數？ # => 真
# 2.偶數？ # => 真
# 2.奇數？ # => 假

如果一行太長，註釋可能會放在下一行：

# 標籤（：文章，：標題）
# # => <label for="article_title">標題</label>
#
# label(:article, :title, "一個簡短的標題")
# # => <label for="article_title">一個簡短的標題</label>
#
# label(:article, :title, "短標題", class: "title_label")
# # => <label for="article_title" class="title_label">短標題</label>

避免為此目的使用任何列印方法，如 puts 或 p。

另一方面，正常註釋不使用箭頭：

# polymorphic_url(record) # 同comment_url(record)

8 檔名

根據經驗，使用相對於應用程式根目錄的檔名：

config/routes.rb            # YES
routes.rb                   # NO
RAILS_ROOT/config/routes.rb # NO

9 字型

9.1 等寬字型

使用固定寬度字型：

常量，特別是類和 module 名稱。
方法名稱。
字面值，如 nil、false、true、self。
Symbols。
方法引數。
檔名。

class Array
  # Calls +to_param+ on all its elements and joins the result with
  # slashes. This is used by +url_for+ in Action Pack.
  def to_param
    collect { |e| e.to_param }.join '/'
  end
end

將 +...+ 用於固定寬度字型僅適用於簡單的內容，例如普通方法名、symbols、路徑（帶正斜槓）等請使用 <tt>...</tt> 用於其他所有內容，特別是類或 module 名稱帶有名稱空間如 <tt>ActiveRecord::Base</tt>。

您可以使用以下命令快速測試 RDoc 輸出：

$ echo "+:to_param+" | rdoc --pipe
# => <p><code>:to_param</code></p>

9.2 普通字型

當 "true" 和 "false" 是英文單詞而不是 Ruby keywords 使用正常字型時：

# 在指定的上下文中執行所有驗證。
# 如果沒有發現錯誤則返回真，否則返回假。
#
# 如果引數為假（預設為 +nil+），則上下文為
# 設定為 <tt>:create</tt> 如果 <tt>new_record?</tt> 為真，
# 和 <tt>:update</tt> 如果不是。
#
# 沒有 <tt>:on</tt> 選項的驗證將執行 no
# 重要的上下文。使用 # some <tt>:on</tt> 進行驗證
# 選項只會在指定的上下文中執行。
def valid?(context = nil)
  # ...
end

11 動態生成的方法

使用 (module|class)_eval(STRING) 建立的方法旁邊有一個註釋和一個生成程式碼的實例。該註釋與模板相距 2 個空格：

for severity in Severity.constants
  class_eval <<-EOT, __FILE__, __LINE__ + 1
    def #{severity.downcase}(message = nil, progname = nil, &block)  # def debug(message = nil, progname = nil, &block)
      add(#{severity}, message, progname, &block)                    #   add(DEBUG, message, progname, &block)
    end                                                              # end
                                                                     #
    def #{severity.downcase}?                                        # def debug?
      #{severity} >= @level                                          #   DEBUG >= @level
    end                                                              # end
  EOT
end

如果生成的行太寬，比如 200 列或更多，請將註釋放在呼叫上方：

# def self.find_by_login_and_activated(*args)
# options = args.extract_options!
# ...
＃ 結尾
self.class_eval %{
  def self.#{method_id}(*args)
    options = args.extract_options!
    ...
  end
}

12 方法可見性

在為 Rails 編寫文件時，瞭解面向使用者的公共 API 與內部 API 之間的差別很重要。

Rails 和大多數庫一樣，使用來自 Ruby 的私有 keyword 來定義內部 API。但是，公共 API 遵循略有不同的約定。 Rails 沒有假設所有公共方法都是為使用者使用而設計的，而是使用 :nodoc: 指令將這些型別的方法註釋為內部 API。

這意味著 Rails 中有一些不供使用者使用的具有 public 可見性的方法。

一個例子是 ActiveRecord::Core::ClassMethods#arel_table：

module ActiveRecord::Core::ClassMethods
  def arel_table # :nodoc:
    # do some magic..
  end
end

如果您認為“此方法看起來像 ActiveRecord::Core 的公共類方法”，那麼您是對的。但實際上 Rails 團隊不希望使用者依賴這種方法。因此他們將其標記為 :nodoc: 並將其從公共文件中刪除。這背後的原因是允許團隊根據他們認為合適的跨版本的內部需求更改這些方法。這個方法的名字可能會改變，或者返回value，或者整個類可能會消失；沒有任何保證，因此您不應在外掛或應用程式中依賴此 API。否則，當您升級到較新版本的 Rails 時，您的應用程式或 gem 可能會損壞。

作為貢獻者，重要的是要考慮此 API 是否的目標在於供終端使用者使用。 Rails 團隊致力於在不經過完整的棄用週期的情況下，不對跨版本的公共 API 進行任何重大更改。建議您使用 :nodoc: 任何內部方法/類，除非它們已經是私有的（意味著可見性），在這種情況下，預設情況下它是內部的。 API 穩定後，可見性可以更改，但由於向後相容性，更改公共 API 會困難得多。

一個類或 module 被標記為 :nodoc: 以表明所有方法都是內部 API，不應直接使用。

總結一下，Rails 團隊使用 :nodoc: 來標記公開可見的方法和類供內部使用；應仔細考慮 API 可見性的更改，並首先透過拉取請求進行討論。

13 關於 Rails 堆疊

在記錄部分 Rails API 時，重要的是要記住所有進入 Rails 堆疊的部分。

這意味著行為可能會根據範圍或上下文而改變您嘗試記錄的方法或類。

當你拿走整個堆疊時，在不同的地方會有不同的行為考慮到，一個這樣的例子是 ActionView::Helpers::AssetTagHelper#image_tag：

# image_tag("icon.png")
# # => <img src="/assets/icon.png" />

儘管 #image_tag 的預設行為是始終返回 /images/icon.png，我們考慮了完整的 Rails 堆疊（包括 Asset Pipeline）我們可能會看到上面看到的結果。

我們只關心使用完全預設時的行為導軌堆疊。

在這種情況下，我們想要記錄 framework 的行為，而不僅僅是這個具體方法。

如果您對 Rails 團隊如何處理某些 API 有疑問，請隨時開啟工單或向問題跟蹤器傳送補丁。

回饋

我們鼓勵您幫助提高本指南的品質。

如果您發現任何拼寫錯誤或資訊錯誤，請提供回饋。要開始回饋，您可以閱讀我們的回饋部分。

您還可能會發現不完整的內容或不是最新的內容。請務必為 main 新增任何遺漏的文件。假設是非穩定版指南(edge guides) 請先驗證問題是否已經在主分支上解決。請前往 Ruby on Rails 指南寫作準則查看寫作風格和慣例。

如果由於某種原因您發現要修復的內容但無法自行修補，請您提出 issue。

關於 Ruby on Rails 的任何類型的討論歡迎提供任何文件至 rubyonrails-docs 討論區。

Guides.rubyonrails.org

Chapters