Rubyでドキュメントを書く RDoc vs YARD vs TomDoc

Rubyでドキュメント書くときは標準ライブラリで入ってるRDocを使う人が多いかもしれませんが他にもドキュメントのフォーマットがあるのでいろいろ比較してみた。

下記コードの詳細は https://github.com/natsumesou/ruby-doc こちらを御覧ください。

RDoc

RDocは特にフォーマットというのが無いので良くも悪くも自由にかける(String)は自分で勝手につけただけで生成されたドキュメントでも文章として扱われるだけ。

# 人間を表すクラス
class Person

  # - first_name - 名前
  attr_reader :first_name
  # - last_name - 苗字
  attr_reader :last_name
  # - gender - 性別
  attr_reader :gender
  # - age - 年齢
  attr_reader :age

  # - first_name - 名前
  # - last_name - 苗字
  # - gender - 性別(default: nil)
  # - age - 年齢(default: nil)
  #
  # Example
  #     person = Person.new('ひろゆき', '松本', :man, 17)
  def initialize first_name, last_name, gender = nil, age = nil
    @first_name = first_name
    @last_name = last_name
    @gender = gender
    @age = age
  end
end

生成されたドキュメント

attr_readerを分けて書いたのは生成されたドキュメントがおかしくなるので分けました。
RDocの特徴はフォーマットが自由というのとmarkdown記法が中途半端に使えることだと思った。中途半端というのは使える記法と使えない記法があるのでそこを注意しないといけない。

YARD

YARDは自由すぎるRDocに対してきっちりとしたフォーマットを用意することで誰でも同じようなドキュメントが生成できるように考慮されたもの。アノテーションという形でパラメータや返り値などが指定できる他、型の指定やDeprecated、TODOなど様々な表記がサポートされている。

# 人間を表すクラス
class Person
  # @return [String] 名前
  attr_reader :first_name
  # @return [String] 苗字
  attr_reader :last_name
  # @return [Symbol] 性別
  attr_reader :gender
  # @return [Fixnum] 年齢
  attr_reader :age

  # @param first_name [String] 名前
  # @param last_name [String] 苗字
  # @param gender [Symbol] 性別
  # @param age [Number] 年齢
  #
  # @example
  #  person = Person.new('ひろゆき', '松本', :man, 17)
  #
  # @return [Object] インスタンス
  def initialize first_name, last_name, gender = nil, age = nil
    @first_name = first_name
    @last_name = last_name
    @gender = gender
    @age = age
  end
end

フォーマットがしっかりしていたほうがいいという人にはうってつけ。
生成されたドキュメントにはDeprecatedやTODOなどがわかりやすく表記されており、また型指定ができる（ない場合はObjectになる）ので複雑なコードを管理する場合の補助としても助かる。

TomDoc

TomDocはRDocの自由すぎるフォーマットに対してある程度の制約を設けたもの。あくまでもRDocをベースにしており、それに対してパラメータや返り値、Exampleなどのフォーマットを追加した程度のものである。
あとこちらもattr_readerは一つづつコメントを書かないとうまくドキュメントが生成されなかった。これは仕方がないことなのかな。

# Public: 人間を表すクラス.
class Person

  # Public: Instance Attribute
  #
  # first_name - 名前
  # last_name - 苗字
  # gender - 性別
  # age - 年齢
  attr_reader :first_name, :last_name, :gender, :age

  # Public:
  #
  # first_name - 名前
  # last_name - 苗字
  # gender - 性別
  # age - 年齢
  #
  # Examples
  #   person = Person.new('ひろゆき', '松本', :man, 17)
  #
  # Returns instance
  def initialize first_name, last_name, gender = nil, age = nil
    @first_name = first_name
    @last_name = last_name
    @gender = gender
    @age = age
  end
end

メソッド、パラメータ、返り値の説明の間には改行が必須で、それがないとドキュメントのパースがうまくいかない。さらにinitializeに対しても必ずReturnsが無いといけないため若干不便さがある。生成されるドキュメントは貧弱なためRDocを利用したほうが良さそう。
また現行のtomdoc -v 0.2.5、0.2.4ともにtomdocコマンドでドキュメントを生成しようとするとうまくいかない（Ruby-2.0.0を使っていたからか？）ためgithubのtomdoc.rbブランチをcloneして使ってみたらうまくいった。TomDocはドキュメントにも書いてあるようにRuby 1.8.7での動作確認をしてあるとのことで若干の不安がある（githubでの開発も盛んに思えない）。

SDoc（おまけ）

RDocのフォーマットで生成するドキュメントのフォーマットを変える。RailsのドキュメントがSDocを使って生成されてる。（あくまでドキュメントの見た目が変わるだけでフォーマットはRDoc）

まとめ

RDocはちょっとドキュメントとしては自由すぎて内部でフォーマットを細かく決めないとカオスになりそう。またTomDocはちょっと動作が不安で開発も滞ってそうなため不安だし、フォーマットの強制の仕方が中途半端で好きじゃなかった。YARDは開発もそれなりでフォーマットがしっかりしていてドキュメントを書く上で申し分ないという感じ。
YARD好きはRuby向いてないとか言われそうだけどRubyのドキュメントを書くならYARDをおすすめしたい。

上記のコード、ドキュメントの完全版は
https://github.com/natsumesou/ruby-doc
に置いてあるので見たい人はご自由にどうぞ。