出張！Railsウォッチ
 in 銀座Rails#36
 森 雅智 / @morimorihoge 2021/08/27 1
 特集：～RDoc/YARDでコメントを書く～


About Me
 ● 森 雅智： @morimorihoge
 ● BPS株式会社でRailsの受託開発チームをやってたり、週1大学非常勤で Web開発を教えてたりします
 ● Ruby/Rails歴は11年くらい。Web開発は17年くらい
 ● 銀座Ralis #10でActiveRecordでVIEWを使おうという話をしました
 ● 銀座Rails #27でアプリケーションコンフィグの話をしました
 About BPS & TechRacho
 ● Web受託開発や電子書籍製品開発をやっている会社です
 ● TechRachoという自社技術Blogを運営しています
 ○ 5年ほど前から平日毎日更新してます
 ○ https://techracho.bpsinc.jp/ ● お仕事相談、転職相談、TechRachoへのご意見など気軽にどうぞ
 ○ https://www.bpsinc.jp/ 2


Railsウォッチとは？
 技術ブログTechRachoで毎週連載しているRails / Ruby界隈を中 心とした雑多な情報を提供する技術雑談マガジン
 3


これまでの出張Railsウォッチのピックアップテーマ
 ● 銀座Rails#12: 複数DB対応
 ● 銀座Rails#13: ActionText、Trix
 ● 銀座Rails#14: ActionMailbox
 ● 銀座Rails#15: production、development、 staging環境について
 ● 銀座Rails#16: 機能開発の設計レビューにつ いて
 ● 銀座Rails#17: リソース管理スコープについて
 ● 銀座Rails#19: 開発チームの冗長化について
 ● 銀座Rails#20: Excelと仲良くしよう
 ● 銀座Rails#21: 標準仕様を読むためのABNF
 ● 銀座Rails#22: CLIプログラムにOptionParser を使う
 4
 各回資料に興味がある方はこちらからどうぞ：https://speakerdeck.com/morimorihoge 
 ● 銀座Rails#23: ActiveRecordのSELECTベンチマー ク
 ● 銀座Rails#24: 令和Devise事情
 ● 銀座Rails#28: 2020年の銀座Railsを振り返る
 ● 銀座Rails#29: Serverless Railsを試す
 ● 銀座Rails#30: Railsインフラ環境Overview
 ● 銀座Rails#31: Railsプロジェクトあるある
 ● 銀座Rails#32: MimeMagic騒動を振り返る
 ● 銀座Rails#33: Rails 7.0で入る予定の新機能（暫定 版）
 ● 銀座Rails#34: もっとDBコメントを書こう
 ● 銀座Rails#35: 何かと便利な ActiveSupport::Instrumentation

RDoc/YARDでコメントを書く
 5


Rubyにおけるドキュメント生成ツール事情
 Ruby本体には標準でRDocが搭載されており、恐らく最も一般的に使われている
 ※Rails本体のドキュメントもRDocで書かれている
 自由な形式でドキュメントが記述でき、マークアップも一通りできるのでシンプルな用途 であれば十分。
 
 6
 https://api.rubyonrails.org/

RailsのAPIドキュメントを手元で生成する
 ● Railsガイドに書いてある通りにやればOK
 ○ https://railsguides.jp/api_documentation_guidelines.html 
 1. Railsリポジトリを手元にclone
 2. bundle
 3. bundle exec rake rdoc
 これでdoc/rdocにHTMLが生成されるが、このままindex.htmlを開いてもCSS/JSが読み 込めず動かないので、以下のコマンドを実行
 ruby -rwebrick -e 'WEBrick::HTTPServer.new(DocumentRoot: "doc/rdoc/", Port: 8080).start'
 7
 http://localhost:8080/

Railsに書かれたRDocの例（1）
 8
 一番シンプルな書き方：メソッドやクラス定義の前にコメントとして記述する 
 ソースコードもRDocから参照できる


Railsに書かれたRDocの例（2）
 9
 activerecord/lib/active_record/associations/collection_proxy.rb
 メソッド本体がソースコードになくてもRDocを出力することができる
 ※moduleやdelegeteで動的解決されるようなメソッドにもドキュメントが書ける
 実際のメソッド定義はここにはないのでshowしても中身が空


RDocのPros/Cons
 Pros
 ● gemの追加インストール不要で使い始めることができる
 ● 記述の自由度が高いため、人間が読むことを意識したドキュメントを書くのにはとて も柔軟性があって良い
 Cons
 ● 人間が読む仕様としては問題ないが、IDEやlanguage serverに構造を解析させるド キュメントとしては機能が足りていない（後述）
 ● 記述の自由度の高さ故に複数人開発で人によって方言が出てしまうことがある
 ● RDocの独自マークアップ書式（RDoc::Markup）に慣れが必要
 ○ 現代ではMarkdownも選択可能（@aycabra さんよりfeedback頂きました） 
 ○ 末尾の補講スライドもご参照下さい 󰢛
 10


YARD
 ● RDocと双璧をなすドキュメント生成ツール
 ○ 歴史は相当古く、Changelogを見る限りでも0.1aが2007年から存在 
 ● YARDメタタグを使った書式により、より構造解析可能なドキュメントを宣言的に記述 できる
 ● APIドキュメントのようなよりプログラムに近い視点のドキュメントを書く場合に優位 性がある
 ○ 参考：rubocop/ruby-style-guideでは2018年以降APIドキュメントにはYARDを推奨している 
 11
 https://yardoc.org/ 


YARDを出力してみる
 Railsのリポジトリ直下で
 1. gem install yard
 2. yard server
 3. http://localhost:8808/にアクセス
 12


YARD版のドキュメント
 13
 Class: ActiveRecord::Associations::CollectionProxy
 RDoc版では表示されなかったmodule include / 継承によって定義されているメソッドも参照できる
 YARDではRDoc形式のコメントも ある程度の互換性を持って出力できる
 よく見るとRDocの :method: で定義されたコメントは出力されていないので、
 RDoc完全互換ではないことに注意


YARDメタタグの基本
 @タグ名に続けてタグに応じた内容を記述することで、タグに応じた意味を持たせること ができる
 14
 @paramで引数の型を指定可能 @returnで戻り値の型を指定可能

YARDのサポートするメタタグの例
 ● @param name [Types] description ○ メソッドの引数
 ● @return [Types] description ○ 戻り値
 ● @raise [Types] description ○ メソッドが投げうる例外 
 ● @yield [parameters] description ○ ブロック引数
 ● @yieldreturn [Types] description ○ ブロック引数の戻り値 
 15
 そのほかにも @abstract や @deprecated など使えそうなものがあるし、ユーザー定義で追加することもできる。 あちこちにcheatsheetを作ってる人もいるので、使い始めの時はその辺りを参考にしてみると良い。 
 Typeには Array や Hash{Symbol => String}などgenerics風味なものも書ける 


YARD with Markdown
 16


YARDの特徴
 ● YARDメタタグがあることで、RDocよりは記述形式が定まっている
 ● 単体ファイルだけでなく、継承元やモジュールなども解釈して出力することにより、 よりAPIドキュメントとして使いやすい情報が出力されている
 ● Markdown記法にデフォルト対応してくれていることにより、Markdownネイティブ勢と の相性が良い
 17
 ここまでの特徴ではちょっと賢いRDocだが、YARDはさらにもう一歩開発のサポートをし てくれる例があるので次から紹介→


YARD with IDE（RubyMine）
 18
 YARD定義上Stringが期待されているのに nilが返る ケースを検出すると Warningしてくれる [String] -> [String, nil] にすることで収まる

YARD with IDE（RubyMine） （2）
 19
 関数呼び出し時も明らかに YARD定義に違反 することが分かる場合は警告してくれる

YARD解析による開発サポート
 ● YARDメタタグに書かれた情報をIDEが解析することで、疑似的な型チェックを行うこ とができる。
 ● language serverであるSolargraphを使えばVS CodeやVim等でも同等のチェックがで きるようだ（自分は使っていないので未確認）
 20
 https://solargraph.org/guides/yard

とはいえちょっと複雑になると・・・？
 21
 変数や条件分岐を挟むと警告が出なくなってしまうため、 あまり信頼しすぎてはいけない。 ただ、他人の作ったメソッドを使う場合などには有用なこ ともある

ちゃんと型チェックしたいならやはり・・・
 22
 Steepを使えば条件分岐があってもきちんと検出できる

RDoc/YARDのまとめ
 ● Rubyでドキュメント生成するにはRDocとYARDがメジャーな選択肢
 ○ RDocはRubyビルトインであること、自由にドキュメントが書けることが利点 
 ○ YARDはメタタグを使うことで、より 形式の定まったドキュメントを書けること、IDEや language serverサポートなどの恩恵をRDocより得られるなどの利点がある 
 ● 個人的には書く人によってばらつきが少なくなるYARDがオススメです
 ● 今回話題にはしなかったが、以下も気にしつつ導入度合いを検討したい
 ○ そもそもどの程度詳細なドキュメントを書くことにするのか？
 ○ ドキュメントの内容が正しい状態を維持するコストをかけられるのか？
 23


補講:RDocでMarkdown
 RDocでもMarkdownは利用できる
 ● rdocコマンドにオプションを指定
 ○ --markup markdown ● .rdoc_optionsに以下を記載する
 ○ markup: markdown 24
 rdocオプションなし実行（ rdocフォーマット） --markup markdown（markdownフォーマット） ※ @aycabta さんにコメント頂いたのを反映（ありがとうございました 󰢛

次回以降もブラッシュアップしていきます
 感想・リクエストなどあればTwitter
 #ginzarails
 @morimorihoge
 @hachi8833
 までお声かけください
 25