Share
Embed
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
Masato Mori
August 27, 2021
Transcript
25 slides
-
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ウォッチのピックアップテーマ • 銀座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 -
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/ -
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のサポートするメタタグの例 • @param name [Types] description ◦ メソッドの引数 • @return
[Types] description ◦ 戻り値 • @raise [Types] description ◦ メソッドが投げうる例外 • @yield [parameters] description ◦ ブロック引数 • @yieldreturn [Types] description ◦ ブロック引数の戻り値 15 そのほかにも @abstract や @deprecated など使えそうなものがあるし、ユーザー定義で追加することもできる。 あちこちにcheatsheetを作ってる人もいるので、使い始めの時はその辺りを参考にしてみると良い。 Typeには Array<String> や Hash{Symbol => String}などgenerics風味なものも書ける -
YARDの特徴 • YARDメタタグがあることで、RDocよりは記述形式が定まっている • 単体ファイルだけでなく、継承元やモジュールなども解釈して出力することにより、 よりAPIドキュメントとして使いやすい情報が出力されている • Markdown記法にデフォルト対応してくれていることにより、Markdownネイティブ勢と の相性が良い 17
ここまでの特徴ではちょっと賢いRDocだが、YARDはさらにもう一歩開発のサポートをし てくれる例があるので次から紹介→ -
YARD with IDE(RubyMine) 18 YARD定義上Stringが期待されているのに nilが返る ケースを検出すると Warningしてくれる [String] ->
[String, nil] にすることで収まる -
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 さんにコメント頂いたのを反映(ありがとうございました