20210827_出張！Railsウォッチ in 銀座Rails#36

2021/08/27銀座Rails#36で発表したスライドです。
https://ginza-rails.connpass.com/event/220616/

週刊Railsウォッチ: https://techracho.bpsinc.jp/tag/%e9%80%b1%e5%88%8arails%e3%82%a6%e3%82%a9%e3%83%83%e3%83%81

Transcript

1. 出張！Railsウォッチ

   in 銀座Rails#36

   森 雅智 / @morimorihoge
   2021/08/27
   1

   特集：～RDoc/YARDでコメントを書く～

   

   View Slide

2. 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

   

   View Slide

3. Railsウォッチとは？

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

   3

   

   View Slide

4. これまでの出張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
   

   View Slide

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

   5

   

   View Slide

6. Rubyにおけるドキュメント生成ツール事情

   Ruby本体には標準でRDocが搭載されており、恐らく最も一般的に使われている

   ※Rails本体のドキュメントもRDocで書かれている

   自由な形式でドキュメントが記述でき、マークアップも一通りできるのでシンプルな用途
   であれば十分。

   

   6

   https://api.rubyonrails.org/
   

   View Slide

7. 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/
   

   View Slide

8. Railsに書かれたRDocの例（1）

   8

   一番シンプルな書き方：メソッドやクラス定義の前にコメントとして記述する 

   ソースコードもRDocから参照できる

   

   View Slide

9. Railsに書かれたRDocの例（2）

   9

   activerecord/lib/active_record/associations/collection_proxy.rb

   メソッド本体がソースコードになくてもRDocを出力することができる

   ※moduleやdelegeteで動的解決されるようなメソッドにもドキュメントが書ける

   実際のメソッド定義はここにはないのでshowしても中身が空

   

   View Slide

10. RDocのPros/Cons

    Pros

    ● gemの追加インストール不要で使い始めることができる

    ● 記述の自由度が高いため、人間が読むことを意識したドキュメントを書くのにはとて
    も柔軟性があって良い

    Cons

    ● 人間が読む仕様としては問題ないが、IDEやlanguage serverに構造を解析させるド
    キュメントとしては機能が足りていない（後述）

    ● 記述の自由度の高さ故に複数人開発で人によって方言が出てしまうことがある

    ● RDocの独自マークアップ書式（RDoc::Markup）に慣れが必要

    ○ 現代ではMarkdownも選択可能（@aycabra さんよりfeedback頂きました） 

    ○ 末尾の補講スライドもご参照下さい 󰢛

    10

    

    View Slide

11. YARD

    ● RDocと双璧をなすドキュメント生成ツール

    ○ 歴史は相当古く、Changelogを見る限りでも0.1aが2007年から存在 

    ● YARDメタタグを使った書式により、より構造解析可能なドキュメントを宣言的に記述
    できる

    ● APIドキュメントのようなよりプログラムに近い視点のドキュメントを書く場合に優位
    性がある

    ○ 参考：rubocop/ruby-style-guideでは2018年以降APIドキュメントにはYARDを推奨している 

    11

    https://yardoc.org/ 

    

    View Slide

12. YARDを出力してみる

    Railsのリポジトリ直下で

    1. gem install yard

    2. yard server

    3. http://localhost:8808/にアクセス

    12

    

    View Slide

13. YARD版のドキュメント

    13

    Class: ActiveRecord::Associations::CollectionProxy

    RDoc版では表示されなかったmodule include / 継承によって定義されているメソッドも参照できる

    YARDではRDoc形式のコメントも ある程度の互換性を持って出力できる

    よく見るとRDocの :method: で定義されたコメントは出力されていないので、

    RDoc完全互換ではないことに注意

    

    View Slide

14. YARDメタタグの基本

    @タグ名に続けてタグに応じた内容を記述することで、タグに応じた意味を持たせること
    ができる

    14

    @paramで引数の型を指定可能
    @returnで戻り値の型を指定可能
    

    View Slide

15. 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風味なものも書ける 

    

    View Slide

16. YARD with Markdown

    16

    

    View Slide

17. YARDの特徴

    ● YARDメタタグがあることで、RDocよりは記述形式が定まっている

    ● 単体ファイルだけでなく、継承元やモジュールなども解釈して出力することにより、
    よりAPIドキュメントとして使いやすい情報が出力されている

    ● Markdown記法にデフォルト対応してくれていることにより、Markdownネイティブ勢と
    の相性が良い

    17

    ここまでの特徴ではちょっと賢いRDocだが、YARDはさらにもう一歩開発のサポートをし
    てくれる例があるので次から紹介→

    

    View Slide

18. YARD with IDE（RubyMine）

    18

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

    View Slide

19. YARD with IDE（RubyMine） （2）

    19

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

    View Slide

20. YARD解析による開発サポート

    ● YARDメタタグに書かれた情報をIDEが解析することで、疑似的な型チェックを行うこ
    とができる。

    ● language serverであるSolargraphを使えばVS CodeやVim等でも同等のチェックがで
    きるようだ（自分は使っていないので未確認）

    20

    https://solargraph.org/guides/yard
    

    View Slide

21. とはいえちょっと複雑になると・・・？

    21

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

    View Slide

22. ちゃんと型チェックしたいならやはり・・・

    22

    Steepを使えば条件分岐があってもきちんと検出できる
    

    View Slide

23. RDoc/YARDのまとめ

    ● Rubyでドキュメント生成するにはRDocとYARDがメジャーな選択肢

    ○ RDocはRubyビルトインであること、自由にドキュメントが書けることが利点
    

    ○ YARDはメタタグを使うことで、より
    形式の定まったドキュメントを書けること、IDEや
    language serverサポートなどの恩恵をRDocより得られるなどの利点がある
    

    ● 個人的には書く人によってばらつきが少なくなるYARDがオススメです

    ● 今回話題にはしなかったが、以下も気にしつつ導入度合いを検討したい

    ○ そもそもどの程度詳細なドキュメントを書くことにするのか？

    ○ ドキュメントの内容が正しい状態を維持するコストをかけられるのか？

    23

    

    View Slide

24. 補講:RDocでMarkdown

    RDocでもMarkdownは利用できる

    ● rdocコマンドにオプションを指定

    ○ --markup markdown
    ● .rdoc_optionsに以下を記載する

    ○ markup: markdown
    24

    rdocオプションなし実行（ rdocフォーマット）
    --markup markdown（markdownフォーマット）
    ※ @aycabta さんにコメント頂いたのを反映（ありがとうございました 󰢛
    

    View Slide

25. 次回以降もブラッシュアップしていきます

    感想・リクエストなどあればTwitter

    #ginzarails

    @morimorihoge

    @hachi8833

    までお声かけください

    25

    

    View Slide