受講料が最大70%OFF 受講料が最大70%OFF

Rubyには、ソースコードとそのコメントからドキュメントを自動で作成してくれる便利なツールがあるますが、多くのRubyのプログラマーが注目しているツールがYARDです。

Rubyは短い記述で読みやすいプログラムが書けるプログラム言語ですが、ドキュメントが不要ということはありません。独自に作ったクラスやメソッドの仕様など、後からプログラムを修正する際にはドキュメントは必須です。

今回はRuby用のドキュメント自動生成ツールに興味のある方に、RubyGemsから入手できるYARDの機能と使い方を紹介します。

Rubyでコードのドキュメントを作るには

今回紹介するYARDは、RubyのプログラムのソースコードからHTML形式のドキュメントを自動作成するツールです。YARDについて解説する前に、ドキュメントを生成する際の課題と、自動生成の仕組みについて紹介します。

ソースコードだけでは不十分

Rubyをはじめとするプログラム言語は、言語と言われるとおり、それを読めばシステムがどのように動作するか理解できます。しかし、プログラムによってはソースコードがかなり大きく、ソースコードだけでシステム全体の動作を理解するのは大変です。

そこで使われているクラスの仕様や扱うデータモデル、変数に格納される内容などを解説したドキュメントを作成して、プログラムを作成したり修正する際に利用します。

さらにプログラムを作成したらそれで終わりではありません。機能の追加や不具合の修正などのメンテナンス作業が発生します。そのような作業で別の担当者がプログラムを修正するためにドキュメントが必要です。

ドキュメント作成の課題

先ほど説明したようにプログラムのソースコードを作成したら、そのドキュメントも必要です。しかし限れた時間でプログラムを作成し、さらにドキュメントも作成するのは面倒です。

かつてはプログラムを作成したエンジニアがドキュメントの作成も担当していました。しかいプログラム作成時間が足りないケースではドキュメントを書く時間が取れず、まともなドキュメントが無いケースもあり、そのようなケースではその後のメンテナンスが大変でした。

そこで今使われている方法は、ソースコードの内容とそこに書かれたコメントから、ドキュメントを自動で生成するツールの利用です。これならプログラムを書いた後に、時間をかけずにドキュメントを作成できます。

Rubyで使えるドキュメント生成ツール

Rubyには標準でRDocというドキュメントを自動生成するツールが付属しています。しかし、RDocは使いやすいとはいえません。そこでより使いやすいドキュメント自動生成ツールとして作られたのがYARDです。

もし、Ruby on Railsのプログラムコードからドキュメントを自動生成して活用しようと考えているようなら、ぜひ、YARDの利用を検討してください。

YARDとは

今回紹介するYARDは、Rubyのプログラムのソースコードとそこに記載されたコメントからHTML形式のドキュメントを自動的に生成するツールです。そしてYARDは、RubyGemsからインストールすることで利用できます。

次からYARDの特徴をRubyに標準で付属しているRDocと比較しながら解説します。

ドキュメント生成ツールの機能

YRADとRDocは、どちらもRUbyのソースコードを解析し、クラス、モジュール、メソッドの定義を抜き出し、その前後に書かれたコメントと組み合わせて、HTML形式のドキュメントを生成します。

Rubyはオブジェクト指向プログラムであり、プログラムの中で使われる要素は全て何らかのクラスに属しています。そのためプログラムの中の要素のことを知るには、それがどのクラスに定義され、どのように定義されているか知らなければなりません。YARDやRDocが生成するドキュメントは、Rubyのソースコードを読む際に必須の情報を提供してくれます。

YARDはRubyGemからインストールできる

先ほど紹介したようにRubyのプログラムを編集するドキュメントが必要ですが、それを作るRDocはRubyに標準で付いているツールのため、インストールしなくても使えます。一方、YARDはRubyGemで提供されているツールです。そのためYARDを使うには、gemコマンドなどでインストールしてください。

YARDをインストールするgemコマンドの例

$ gem install yard

YARDをインストールできたら、yardocコマンドが実行できるかチェックしてみてください。下記のコマンドを実行してインストールしたyardのバージョンが表示されたら正常です。

yardocコマンドのバージョンを表示するコマンド

$ yardoc --version

YARDとRDocの違いとは

先ほど紹介したようにRDocとYARDはどちらもソースコードからドキュメントを作成しますが、ソースコードに書かれたコメントを利用する機能が違います。

RDocとYARDはどちらもコメントに属性を記述し、より見やすいドキュメントを作ることが可能です。ただしYARDは機能が多く、より見やすいドキュメントを記述できます。ただし、専用のマークアップ言語を使うことから、YARDを使いこなすには、そのマークアップ言語を覚えて、見やすく書くスキルの習得が必要です。

yardocコマンドの使い方

先ほど紹介したようにYARDは、RubyのプログラムのソースコードからHTML形式のドキュメントを自動的に生成するツールです。次からその使い方を紹介します。

ドキュメントの作り方

YARDでRubyのプログラムのドキュメントを生成するには、次のようにyardocコマンドにRubyのプログラムのソースファイルを指定します。

YARDの実行例

$ yardoc sample.rb

yardocコマンドを実行すると、実行したディレクトリにdocが作られて、その下にHTML形式のドキュメントが作成されます。なお、対象のソースファイルにクラスが定義されていれば、そのクラス名のファイルが作られます。

yardocコマンド実行時に作成されるファイル

(クラス名).html
_index.html
class_list.html
file_list.html
frames.html
index.html
method_list.html
top-level-namespace.html
css/
js/

ドキュメントの例

YARDを使って作成したドキュメントの例を次に紹介します。

Rubyのプログラムの例

class Oneclass
  # テスト用のクラス
  # @param [String] val1 処理開始時のメッセージ
  # @param [String] val2 処理終了時のメッセージ
  def initialize( val1, val2)
    @val1 = val1
    @val2 = val2
  end
  # 処理開始時
  # @return [String] 処理開始時のメッセージを返す
  def do_start()
    msg = @val1
  end
  # 処理終了時
  # @return [String] 処理終了時のメッセージを返す
  def do_end()
    msg = @val2
  end
end

上記のRubyのプログラムでは、「@param」と「@return」の2つのYARD形式のタグを使ったコメントを記載しています。そして、これらのタグは、yardocコマンドで生成したドキュメントにも記載されています。

よく使われるYARD形式のタグ

先ほどの例で紹介したようにyardocコマンドで生成したHTMLのドキュメントは、YARD形式のタグを追加することで、より読みやすくできます。

なお、YARD形式のタグは、コメントに「@」または「@!」で始まるタグ名を指定し、続いて型指定子リストを[]の中に指定し、その次にドキュメントに反映させるコメントを記載します。

YARD形式のタグの記述方法

# @タグ名 [型指定子リスト] ドキュメントに反映させるコメント

次によく使われるYARD形式のタグを紹介します。

@params メソッドに渡す引数の説明
@raise メソッドで発生しえる例外クラスの説明
@return メソッドの返り値の説明
@option メソッドに渡すオプションハッシュ引数の説明
@see URLや他のオブジェクトを書くとリンクになる
@note オブジェクトを使うときに注意して欲しい点を説明

まとめ

Rubyは短く読みやすいプログラムが書ける言語ですが、ドキュメントが不要という訳ではありません。しかしプログラムを書いて、さらにドキュメントも書くのは面倒です。

これまで紹介したように、yardocコマンドにRubyのソースファイルを指定して実行するとHTML形式のドキュメントを生成できます。さらに、コメントにYARD形式のタグを使って書いておくと、そのコメントをドキュメントに反映することが可能です。

Rubyのプログラムに対応するドキュメントを作成するなら、ぜひ、ドキュメントを自動生成できるYRADの利用を検討してください。

エンジニアになりたい人に選ばれるプログラミングスクール「ポテパンキャンプ 」

ポテパンキャンプは卒業生の多くがWebエンジニアとして活躍している実践型プログラミングスクールです。 1000名以上が受講しており、その多くが上場企業、ベンチャー企業のWebエンジニアとして活躍しています。

基礎的な学習だけで満足せず、実際にプログラミングを覚えて実践で使えるレベルまで学習したいという方に人気です。 プログラミングを学習し実践で使うには様々な要素が必要です。

それがマルっと詰まっているポテパンキャンプでプログラミングを学習してみませんか?

卒業生の多くがWebエンジニアとして活躍

卒業生の多くがWeb企業で活躍しております。
実践的なカリキュラムをこなしているからこそ現場でも戦力となっております。
活躍する卒業生のインタビューもございますので是非御覧ください。

経験豊富なエンジニア陣が直接指導

実践的なカリキュラムと経験豊富なエンジニアが直接指導にあたります。
有名企業のエンジニアも多数在籍し品質高いWebアプリケーションを作れるようサポートします。

満足度高くコスパの高いプログラミングスクール「ポテパンキャンプ」

運営する株式会社ポテパンは10,000人以上のエンジニアのキャリアサポートを行ってきております。
そのノウハウを活かして実践的なカリキュラムを随時アップデートしております。

代表の宮崎もプログラミングを覚えサイトを作りポテパンを創業しました。
本気でプログラミングを身につけたいという方にコスパ良く受講していただきたいと思っておりますので、気になる方はぜひスクール詳細をのぞいてくださいませ。