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

初心者向けにRubyのドキュメンテーションツールYARDの使い方について現役エンジニアが解説しています。ドキュメンテーションとはあるクラスのプロパティやメソッドなどと、その解説などがセットになった文章のことです。Ruby標準のRdocやSdoc、YARDなどの種類があります。

TechAcademyマガジンはオンラインのプログラミングスクールTechAcademy [テックアカデミー]が運営。初心者向けに解説した記事が4,000以上あります。現役エンジニアの方はこちらをご覧ください。

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

Rubyについてそもそもよく分からないという方は、Rubyとは何なのか解説した記事をまずご覧ください。

 

なお本記事は、TechAcademyのWebアプリケーションオンラインブートキャンプの内容をもとに紹介しています。
 

田島悠介

今回は、Rubyに関する内容だね!

大石ゆかり

どういう内容でしょうか?

田島悠介

RubyのドキュメンテーションツールYARDの使い方について詳しく説明していくね!

大石ゆかり

お願いします!

 

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

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

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

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

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

 

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

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

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

 

[PR] Rubyのプログラミングで挫折しない学習方法を動画で公開中

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

ソースコードのクラス定義やメソッド定義箇所に、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を開いてみましょう。

YARDの最初のページ

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

YARDのクラスの概要

 

仕様詳細を記述しよう

これだけでも十分便利なのですが、他の人がドキュメントを参照することを考えると情報が不足しています。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で作成されたドキュメントの概要

 

その他のYARDタグ

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

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

 

筆者プロフィール

メンター稲員さん

フリーランスエンジニア。
大手SEからフリーランスのWeb系エンジニアにジョブチェンジ。

経験言語:Ruby、Rails、Python、C/C++、Java、Perl、HTML/CSS3、JavaScript、CoffeeScript,Node.js。
おうち大好きマンです。

 

大石ゆかり

内容分かりやすくて良かったです!

田島悠介

ゆかりちゃんも分からないことがあったら質問してね!

大石ゆかり

分かりました。ありがとうございます!

TechAcademyでは初心者でも最短4週間でエンジニアになれるRuby on Railsオンラインブートキャンプを開催しています。

現役エンジニアがパーソナルメンターとして受講生に1人ずつつき、マンツーマンのメンタリングで学習をサポートし、最短4週間でオリジナルWebサービスを開発することが可能です。

また、現役エンジニアから学べる無料のプログラミング体験会も実施しているので、ぜひ参加してみてください。