RubyのドキュメンテーションツールYARDの使い方を現役エンジニアが解説【初心者向け】
初心者向けにRubyのドキュメンテーションツールYARDの使い方について現役エンジニアが解説しています。ドキュメンテーションとはあるクラスのプロパティやメソッドなどと、その解説などがセットになった文章のことです。Ruby標準のRdocやSdoc、YARDなどの種類があります。
テックアカデミーマガジンは受講者数No.1のプログラミングスクール「テックアカデミー」が運営。初心者向けにプロが解説した記事を公開中。現役エンジニアの方はこちらをご覧ください。 ※ アンケートモニター提供元:GMOリサーチ株式会社 調査期間:2021年8月12日~8月16日 調査対象:2020年8月以降にプログラミングスクールを受講した18~80歳の男女1,000名 調査手法:インターネット調査
RubyのドキュメンテーションツールYARDの使い方について解説します。
そもそもRubyについてよく分からないという方は、Rubyとは何なのか解説した記事を読むとさらに理解が深まります。
なお本記事は、TechAcademyのオンラインブートキャンプRuby講座の内容をもとに紹介しています。
今回は、Rubyに関する内容だね!
どういう内容でしょうか?
RubyのドキュメンテーションツールYARDの使い方について詳しく説明していくね!
お願いします!
ドキュメンテーションツール(ドキュメント生成ツール)を使うメリット
ドキュメンテーションツールを使うメリットは、ソースコードとドキュメントが同時に作成できることです。
API仕様書をWordなどで作成している場合、ソースコードを変更する際にあわせて仕様書の変更が必要になります。
忙しかったり、ちょっとした修正の場合、「あとから修正しよう」となりがちです。そうすると、ドキュメントとソースコードの内容が一致しない状態になり、何が正しいのかが分からずバグを生み出す要因になってしまいます。
ドキュメンテーションツールを適切に使うことで、ソースコードとドキュメントで内容の乖離が起きにくくなります。
Rubyのための主なドキュメンテーションツール
Ruby の主なドキュメンテーションツールは3つあります。
この記事では3つめの YARD について解説します。
[PR] Rubyのプログラミングで挫折しない学習方法を動画で公開中
ドキュメンテーションツール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などのタグがあります。
より詳しく知りたい方は公式リファレンスを参照すると良いでしょう。
コスパとタイパ、両方結果的に良くなる良くなる学び方とは?
「スクールは高いし時間も縛られて効率が悪い」と考える方は多いと思います。
もちろん、時間も費用もかかることは間違いありません。
ただ
結果的に無駄な学びにお金も時間もかける方がリスクが高いという考えもあります。
コスパ・タイパ最適化の参考として、
テックアカデミー卒業生がスクールを選んだ理由
をご紹介します。
- ・困ったときに、質問や相談できる相手がいるため挫折しなかった
- ・プロとして必要なスキルのみを深く学べたので無駄がなかった
- ・副業案件の提供と納品までのサポートがあったので目的を達成できた
安価・短期間で広く浅く学んでも意味がありません。
本当に自分の目的が達成できるか、それが重要です。
自分にどのスキルや学び方が合っているか、どんな学習方法かなど、お気軽に
無料相談
に参加してみませんか?
カウンセラー・現役のプロへ、何でも気軽に無料相談可能。
30分か60分お好きな時間が選べて、かつ3回まで
すべて無料で
ご利用できます。
無理な勧誘は一切ない
ので、お気軽にご参加ください。
筆者プロフィール
メンター稲員さん
フリーランスエンジニア。 経験言語:Ruby、Rails、Python、C/C++、Java、Perl、HTML/CSS3、JavaScript、CoffeeScript,Node.js。 |
内容分かりやすくて良かったです!
ゆかりちゃんも分からないことがあったら質問してね!
分かりました。ありがとうございます!
TechAcademyでは、初心者でもRuby on Railsを使ったプログラミングを習得できるオンラインブートキャンプRuby講座を開催しています。
挫折しない学習方法を知れる説明動画や、現役エンジニアとのビデオ通話とチャットサポート、学習用カリキュラムを体験できる無料体験も実施しているので、ぜひ参加してみてください。
プログラミングを独学で学習していて、このように感じた経験はないでしょうか?
- ・調べてもほしい情報が見つからない
- ・独学のスキルが実際の業務で通用するのか不安
- ・目標への学習プランがわからず、迷子になりそう
テックアカデミーでは、このような
学習に不安を抱えている方へ、マンツーマンで相談できる機会を無料で提供
しています。
30分間、オンラインでどんなことでも質問し放題です。
「受けてよかった」と感じていただけるよう
カウンセラーやエンジニア・デザイナー
があなたの相談に真摯に向き合います。
「自分に合っているか診断してほしい」
「漠然としているが話を聞いてみたい」
こんなささいな悩みでも大丈夫です。
無理な勧誘は一切ありません
ので、まずはお気軽にご参加ください。
※体験用のカリキュラムも無料で配布いたします。(1週間限定)