RubyのドキュメンテーションツールYARDの使い方を現役エンジニアが解説【初心者向け】

RubyのドキュメンテーションツールYARDの使い方について解説します。

 
そもそもRubyについてよく分からないという方は、Rubyとは何なのか解説した記事を読むとさらに理解が深まります。

なお本記事は、TechAcademyのオンラインブートキャンプRuby講座の内容をもとに紹介しています。

 

 

ドキュメンテーションツール（ドキュメント生成ツール）を使うメリット

ドキュメンテーションツールを使うメリットは、ソースコードとドキュメントが同時に作成できることです。

API仕様書をWordなどで作成している場合、ソースコードを変更する際にあわせて仕様書の変更が必要になります。

忙しかったり、ちょっとした修正の場合、「あとから修正しよう」となりがちです。そうすると、ドキュメントとソースコードの内容が一致しない状態になり、何が正しいのかが分からずバグを生み出す要因になってしまいます。

ドキュメンテーションツールを適切に使うことで、ソースコードとドキュメントで内容の乖離が起きにくくなります。

 

Rubyのための主なドキュメンテーションツール

Ruby の主なドキュメンテーションツールは3つあります。

• RDoc
• SDoc
• YARD

この記事では3つめの YARD について解説します。

 

[PR] 未経験からWebエンジニアを目指す方法とは

ドキュメンテーションツールYARDとは

ソースコードのクラス定義やメソッド定義箇所に、YARDの記法に従いコメントをつけることで、以下の画像のようなドキュメントを生成することができるツールです。

YARDのインストール方法

gem install yard でインストールできます。

bundlerをお使いの方はGemfileにgem ‘yard’ を追加して、bundle install でインストールできます。

 

YARDの使い方

サンプルコード

以下のPersonクラスを例に解説します。Personクラスは、自己紹介をするintroduceメソッドと、年の差を求めるage_diffメソッドを持ちます。

またPrivateメソッドとしてwho_is_olderというメソッドも持ちます。

 

class Person
  def initialize(name, age)
    @name = name
    @age = age
  end
  def introduce
    "はじめまして, #{@name}です。"
  end
  def age_diff(other_age)
    msg = "あなたとは#{(@age - other_age).abs}歳差ですね。"
    msg += who_is_older(other_age)
  end
  private
  def who_is_older(other_age)
    if other_age > @age
      "あなたの方が年上ですね。"
    elsif other_age < @age
      "わたしの方が年上ですね。"
    else
      "同い年ですね。"
    end
  end
end

 

ドキュメントの生成方法

まずは何もコメントをしていない状態でドキュメントを生成してみましょう。

yardoc person.rbでdocフォルダにドキュメントが生成されます。中にある_index.htmlを開いてみましょう。

Personクラスへのリンクにアクセスすると、以下のようなページが表示されます。コンストラクタや、Public メソッドについて自動でドキュメントが生成されています。

 

仕様詳細を記述しよう

これだけでも十分便利なのですが、他の人がドキュメントを参照することを考えると情報が不足しています。YARD記法に従って、コメントを追加していきましょう。

利用者のことを考えると、何をするメソッドなのか、引数は何か、戻り値は何か、あたりは最低限必要そうです。メソッド概要はコメント冒頭部に、引数は @param [型] 引数名 説明、戻り値は @return [型] 説明 で記述します。

 

class Person
  # 人物を作成
  # @param [String] name 名前
  # @param [Integer] age 年齢
  def initialize(name, age)
    @name = name
    @age = age
  end
  # 自己紹介
  # @return [String] 名前を含んだ自己紹介メッセージ
  def introduce
    "はじめまして, #{@name}です。"
  end
  # 年の差を求める
  # @param [Integer] other_age 相手の年齢
  # @return [String] 年齢差とどちらが年上かに関するメッセージ
  def age_diff(other_age)
    msg = "あなたとは#{(@age - other_age).abs}歳差ですね。"
    msg += who_is_older(other_age)
  end
  private
  def who_is_older(other_age)
    if other_age > @age
      "あなたの方が年上ですね。"
    elsif other_age < @age
      "わたしの方が年上ですね。"
    else
      "同い年ですね。"
    end
  end
end

 

コメントを追加したらyardoc person.rbでドキュメントを更新しましょう。

引数や戻り値についての説明が追加されて、どのようなメソッドなのかがわかりやすくなりました。

 

その他のYARDタグ

@param,@return以外にも、例外について記述する@raiseや、注意点などを記述する@noteなどのタグがあります。

より詳しく知りたい方は公式リファレンスを参照すると良いでしょう。

 

筆者プロフィール

メンター稲員さん フリーランスエンジニア。 大手SEからフリーランスのWeb系エンジニアにジョブチェンジ。 経験言語：Ruby、Rails、Python、C/C++、Java、Perl、HTML/CSS3、JavaScript、CoffeeScript,Node.js。 おうち大好きマンです。

 

 

TechAcademyでは、初心者でもRuby on Railsを使ったプログラミングを習得できるオンラインブートキャンプRuby講座を開催しています。

挫折しない学習方法を知れる説明動画や、現役エンジニアとのビデオ通話とチャットサポート、学習用カリキュラムを体験できる無料体験も実施しているので、ぜひ参加してみてください。