[Ruby] YARDを用いてソースコードからドキュメントを生成する

概要

Rubyのドキュメント生成ツールであるYARDを用いて、RubyのソースコードからHTMLのドキュメントを自動生成するやり方の基本を確認する。
今更感のある内容だが、使ったことが無かったのでじっくり確認しながらやってみる。

かなり基本的な内容に限るので、初めての人向け。

前提

以下の環境で動作確認済み

要素 バージョン
debian 8.6
ruby 2.2.2
yard 0.9.9

YARDとは

Rubyのソースコードを元にHTMLのドキュメントを生成するツール。同じ目的のツールにRDocがあるが、こちらはYARDと比べてかなり自由度の高いドキュメントを生成することができる。YARDは逆にある程度限られた内容のドキュメントしか生成できないが、その分ソースコードの書き方も限定されるので、誰が書いても同じような一貫性のあるドキュメントを生成できる。

YARDのインストール

YARDはgemで配布されているので、gemコマンドでインストールする。

$ gem install yard

ソースコード作成

とりあえず今回は、非常に簡単な以下のようなユーザクラスを用意する。
コードの内容にそんなに意味は無いが、とりあえずイニシャライザと、インスタンス変数、公開メソッド、非公開メソッドそれぞれがあるクラスだ。

これをuser.rbのファイル名で保存する。

class User

  def initialize(name, password)
    @name     = name
    @password = password
  end

  def email
    "#{@name}@#{email_domain}"
  end

  def login(password)
    return password === @password
  end

  private
    def email_domain
      "gmail.com"
    end

end

ドキュメントの作成

yardocコマンドで、対象のファイルを指定すると、そのファイルに含まれているクラス、メソッドについてのドキュメントが生成される

$ yardoc user.rb
Files:           1
Modules:         0 (    0 undocumented)
Classes:         1 (    0 undocumented)
Constants:       0 (    0 undocumented)
Attributes:      0 (    0 undocumented)
Methods:         3 (    0 undocumented)
 100.00% documented

デフォルトではdocというディレクトリが作成され、そこにブラウザで閲覧できるドキュメントが配置される

$ ls doc/
class_list.html  css  file_list.html  frames.html  _index.html  index.html  js  method_list.html  top-level-namespace.html  User.html

doc/index.htmlを開いてみると、以下のようにクラスとメソッドの定義を確認することができる。

メソッド一覧を見れたり、ソースコードを表示できたり、クラスの継承関係を確認できたりと、これだけでも充分に便利だが、このままだと個々のクラスやメソッドが一体何者なのか、どう使ったらいいのかがサッパリわからない。

それを解決するために、ソースコードにタグコメントなどを以降で記述する。

タグコメントの記述

YARDにおけるタグコメントは、主にクラスやメソッドの定義部に特定のフォーマットのコメントを記述することで、YARDがそれを認識できるようにするもの。本記事では以下のタグコメントを用いる。

  • @param メソッドの引数情報を記述
  • @return メソッドの戻り値情報を記述

上記のタグコメント含め、クラスやメソッド全体に関する説明のコメントも付与したUserクラスが以下である。

#
# ユーザの操作を行うクラス
#
class User

  #
  # ユーザを作成
  # @param [String] name ユーザ名
  # @param [String] password パスワード
  #
  def initialize(name, password)
    @name     = name
    @password = password
  end

  #
  # メールアドレスを取得
  # メールアドレスはユーザ名を元に決定する
  # @return [String] ユーザごとのメールアドレス
  #
  def email
    "#{@name}@#{email_domain}"
  end

  #
  # システムにログインする
  # @param  [String] password ログイン用パスワード
  # @return [True]  ログイン成功
  # @return [False] ログイン失敗
  #
  def login(password)
    return password === @password
  end

  private
    #
    # メールアドレス用のドメインを取得
    # @return [String] ドメイン
    #
    def email_domain
      "gmail.com"
    end

end

これで先程同様にドキュメントを生成すると、以下のようにクラスやメソッドに関する説明が自動で付与される。

所感

  • 物凄い基本的な部分しか触れなかったが、それでもドキュメント自動生成の恩恵は確かに受け取ることができた
  • 日頃からあまり実装に関するドキュメントの作成ができていなかったが、こういったレベルからの導入なら容易にできそう
  • 生成したドキュメントを閲覧するためのサーバが別途必要かも
  • 当然だがこういったツールはRubyに限らずどの言語でもあるはず
  • キレイなドキュメントを生成することを目的にコーディングしたほうが、単一責務の原則を守れたり、命名に慎重になったり、良いコードが書ける気がする
  • ドキュメントを生成するかはともかく、今後Rubyを書く時はYARDにあわせたコメントを書くようにしよう

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です