2013-05-18

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

生成されたドキュメント
f:id:natsumesouxx:20130518232546p:plain

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

f:id:natsumesouxx:20130518232559p:plain

フォーマットがしっかりしていたほうがいいという人にはうってつけ。
生成されたドキュメントには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

f:id:natsumesouxx:20130518232610p:plain

メソッド、パラメータ、返り値の説明の間には改行が必須で、それがないとドキュメントのパースがうまくいかない。さらに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）

f:id:natsumesouxx:20130518232652p:plain

まとめ

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

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

2013-04-30

インターネットは自由という名の悪魔だった。

最近インターネットは殆どのユーザにとって害悪でしかないのではと思うようになってきた。

インターネットはほしいものにアクセスでき、自由で双方向性のあるコミュニケーションが可能となった。

しかしそれらを上手に利用できるのはごく僅かな人間で、ほとんどの人間には副作用として悪いものしか生み出していない。

インターネット世代と言われている多くの若者はテレビ・新聞を観ないでインターネットばかりと言われているが、それらの多くはインターネットの自由性がより視野を狭くし、TVや新聞などある程度まとまった質の高い（それらのユーザは情報操作されたとや揶揄している）情報を取得することをせず自然と自らの殻にこもった情報しか選択しなくなる。

さらに最近は芸能人や有名人などが双方向コミュニケーションの場としてのTwitterやニコニコ生放送を利用するようになり、炎上案件が多発している。

例えば田村淳や岡村隆史などがユーザからの批判コメントを取り上げ話題になっているが、これらは今までは事務所というフィルタに通されたものが直接（しかも手軽に）届くようになり、未然に防がれていた火種をダイレクトに受け取れるようになってしまったことが原因である。後はhitode909さんみたいにインターネットおじさんみたいな人が嵐のように批判して去っていく案件が多発する。

これらに共通することは大抵のユーザは自分で正しい情報を選択することが出来ず、自分の都合の良い情報のみを受け取り、その場の勢いで対象の人物に間違った意見を述べてしまうということだ。

これらのユーザはたちが悪いことに、そういった間違った情報や偏った情報を鵜呑みにするだけでなく、自信で消化するだけでなく、拡散・炎上させようとすることだ（しかも大抵の場合はそれを無意識に行なっている）。

このような点からインターネットは未熟・発展途上等と言われているが、個人的にはもう十分に発達しているし、一般ユーザにリーチしていると思う。

問題は、大抵の人がその自由過ぎるインターネットを利用しきれていないからだ。酒を飲んでも飲まれるなというようにインターネットに飲まれている人が大半なのである。

中国にはグレートファイアーウォールという情報統制の機能があるが、（その機能に関してはどうあれ）そういった試みは結構面白く、自由過ぎるインターネットをしっかり利用できる人間が少ないという問題をある程度カバーしてあげるという事が現状の課題だと思う。

Yahoo!Japanのポータルなどは実はそのようなポジションとして一役買っていると思っており、ある程度リテラシーに低いユーザのブラウザは起動画面がヤフートップだったりして、それがインターネットの入り口だと思い込んでいるケースがある。ヤフーのトップページはある程度情報の整理された新聞の一面的な機能を果たしているため、偏った情報を選択するケースが少ない。（こういうユーザは選択すら出来ないことが多分にあると思うが）

だが現在のインターネット帖の炎上案件を見れば分かるようにこれだけでは足りていない。インターネットには入り口が必要なのではないかと思う、そこを通れば誰もが自由にアクセスすることが出来る入り口が。

入り口には新聞のような質の高い絞られた情報が並んでおり、そこを通れば後は自由にやってくれ。そんな機能が必要なのではないだろうか。そのようなものがないとテレビや新聞の代わりになるメディアといえる日は来ないと思う。

インターネットで有名な偉い人でも「ネットは自由でなくてはいけない！自由最高！」といってる人が結構いるが、現実は自由を使いこなせるユーザの方が少ないということを認識してテレビや新聞がない、メディアがインターネットだけになった世界でもちゃんと生きていけるような仕組みが無い限りインターネット（笑）のままだと思う。

むしろこういった問題に今のテレビや新聞業界のチャンスがあると思うし、今は個々にしかそれらのメディアにチャンスは無いとも思う。

インターネットは自由だし、その自由を制限することは誰にも止められない。これは妄想で叶うことのない悪夢だからだ。

2013-04-25

引っ越して来ました

次回からこちらで記事を書きます。

以前のはてなダイアリー

http://d.hatena.ne.jp/natsumesouxx/