YardRuby 文檔工具
YARD 是一個 Ruby 文檔生成工具。它使用戶能夠生成一致的、可用的文檔，這些文檔可以非常容易地導出為多種格式，并且還支持擴展自定義Ruby結(jié)構，如自定義類級定義。
特點：
1. RDoc / SimpleMarkup格式兼容性：使YARD與RDoc格式兼容。實際上，YARD不會對RDoc文檔字符串進行任何處理，并將其留給輸出生成工具來決定如何呈現(xiàn)文檔。
2. Yardoc元標記格式像Python，Java，Objective-C和其他語言一樣：YARD在常規(guī)代碼文檔旁邊為元標記使用'@tag'樣式定義語法。這些標簽應該能夠愉快地并排放置RDoc格式的文檔，但是提供了一種更一致和可用的方式來描述有關對象的重要信息，例如它們采用什么參數(shù)以及它們期望是什么類型，什么方法應該返回，它會引發(fā)什么異常，如果過時了，等等。它還允許在輸出生成階段更好地（更一致地）組織信息。您可以在Tags.md文件中找到標簽列表。
YARD還支持某些標簽的可選“類型”聲明。這使開發(fā)人員能夠以非侵入性但有用且一致的方式來記錄紅寶石方法和參數(shù)的類型簽名。代替在說明書正文中描述此數(shù)據(jù)，開發(fā)人員可以在一行中正式聲明參數(shù)或返回類型?？紤]以下以YARD格式記錄的方法：
# Reverses the contents of a String or IO object.
#
# @param contents [String, #read] the contents to reverse
# @return [String] the contents reversed lexically
def reverse(contents)
contents = contents.read if contents.respond_to? :read
contents.reverse
end
通過上面的@param標記，我們了解到content參數(shù)可以是String或響應“ read”方法的任何對象，這比文本描述（其應為IO對象）更強大。這也通知開發(fā)人員，他們應該期望收到該方法返回的String對象，盡管這對于“反向”方法可能是顯而易見的，但是當方法名稱可能不具有描述性時，它將變得非常有用。
3. YARD的自定義構造和可擴展性：YARD旨在通過插件進行擴展和定制。以需要記錄以下代碼的場景為例：
class List
# Sets the publisher name for the list.
cattr_accessor :publisher
end
此自定義聲明提供了動態(tài)生成的代碼，文檔工具很難在沒有開發(fā)人員幫助的情況下正確地編寫代碼。為了減輕手動記錄過程的麻煩，開發(fā)人員可以擴展YARD來處理cattr_accessor構造，并使用相關的文檔自動在類上創(chuàng)建屬性。這使得記錄外部API（尤其是動態(tài)API）對于用戶的使用而言更加一致。
YARD還為其他任何地方的可擴展性而設計，使您可以添加對新編程語言，新數(shù)據(jù)結(jié)構甚至數(shù)據(jù)存儲位置/方式的支持。
4.原始數(shù)據(jù)輸出：YARD還可以將記錄的對象作為原始數(shù)據(jù)（轉(zhuǎn)儲的命名空間）輸出，可以在以后重新加載以進行生成，甚至審計代碼。這意味著任何開發(fā)人員都可以使用原始數(shù)據(jù)為任何自定義格式（例如YAML）執(zhí)行輸出生成。盡管YARD計劃支持XHTML樣式的文檔輸出以及命令行（基于文本）和可能的XML，但對于希望從其他形式獲得YARD處理優(yōu)勢的人（例如將所有文檔都扔進去），這可能仍然有用。數(shù)據(jù)庫。利用這種原始數(shù)據(jù)格式的另一種有用方法是編寫可以自動生成測試用例的工具，或者在代碼中顯示可能未處理的異常。
5.本地文檔服務器：YARD可以為項目或已安裝的gem（類似于gem server）提供文檔，并具有動態(tài)搜索和實時重新加載的附加優(yōu)勢。使用實時重新加載功能，您可以記錄代碼并通過刷新頁面立即預覽結(jié)果；YARD將完成重新生成HTML的所有工作。這使編寫文檔變得更快。