Rubyのドキュメンテーション YARD編　（１）

プログラミング

cuzic です。

WMI でいろいろとプロパティなどを観察していて、Description という Qualifier でその WMI クラスのプロパティに関する詳細な説明が得られることに気がつきました。

簡単な例としては、

    require 'win32ole'
    loc = WIN32OLE.new("WbemScripting.SWbemLocator")
    service = loc.ConnectServer

    service.SubclassesOf("", 131072).each do |klass|
      desc = klass.Qualifiers_.Item("Description") rescue nil
      puts "#{klass.Name} #{desc}\n" if desc
    end

とすると、さまざまな WMI クラスの説明を表示できます。131072 (= 0x20_000)

プロパティ、メソッド、メソッドの引数などについて、Description の Qualifier が設定されているため、ドキュメントとして、十分な情報が得られます。

そこで、Ruby のドキュメント作成方法について学ぶための題材として WMI の Description の Qualifier が使うというアイデアを思いついてみました。

まずは、Ruby のリファレンスマニュアルとして使われている bitclust を利用して、ドキュメントの作成を検討してみたのですが、どうも標準ライブラリが前提からなのか、やり方がよく分かりませんでした。
次に、Ruby でよく使われているドキュメント作成ツールである RDoc を採用しようと思ったのですが、パラメータ引数の説明の書き方などがよく分からなかったり、attr_reader とかと、メソッド定義をいい感じに区別して表示させたかったのですが、やり方を見つけられませんでした。

次に試したのは、RDoc の後継（？）の YARD です。YARD を使うとやりたいことが一通りできそうな上、書き方が私にとって、すんなり理解できたのですぐに気に入りました。

  ##
  #  Caption プロパティは、オブジェクトについての簡単な説明 (1 行分の文字列) です。
  # @return [string] Caption
  attr_reader :Caption

のように、@return や、@param のような JavaDoc の書き方は見慣れていて、すんなりついていけます。

そこで、YARD を使って WMI のドキュメントを作成してみました。ここにおいてみています。

YARD を使ってみて、思ったことは、

  • デフォルトの色合いとかはけっこうそつがないかんじで、見やすい
  • カスタマイズは柔軟そう。ドキュメントもいろいろと書かれていて、探求する価値がありそうです。
  • 生成がとても遅い。今回はかなりの分量があったせいかもしれませんが１０分以上かかってびっくりしました。

といったところです。

YARDは拡張性やカスタマイズが容易そうな印象なので、そのあたりについても探求していきたいな、と思いました。