主要是在「型態」的標示上。
以前用RDoc的方式來寫，我可以知道某個方法有什麼參數（名稱），卻
不見得可以望文生義（有的名字取得好的話是可以「猜」出來的），多
少要再去查範例才知道怎麼用。
現在用Yard來寫，基本上RDoc的用法都可以沿用（沒試過，文件上說的）
最主要我喜歡的地方在於
# @param [String] name 這是一個名字
# @return [MyModule::MyClass] 傳回一個這個類別
def my_method(name)
...
end
產生文件後，可以清楚地知道這個方法收一個字串，傳回一個類別變數。
甚至還有包括傳進去一個Hash的話裡面該有哪些鍵，代表什麼意義，是什
麼型別（類別），以及其他的種種好用的用法。
如果對產生文件有興趣的朋友，可以試試。
http://yardoc.org/guides/index.html