Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

Masato Mori

August 27, 2021
Tweet

More Decks by Masato Mori

Other Decks in Programming

Transcript

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

  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
  3. 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/
  4. RDocのPros/Cons
 Pros
 • gemの追加インストール不要で使い始めることができる
 • 記述の自由度が高いため、人間が読むことを意識したドキュメントを書くのにはとて も柔軟性があって良い
 Cons
 • 人間が読む仕様としては問題ないが、IDEやlanguage

    serverに構造を解析させるド キュメントとしては機能が足りていない(後述)
 • 記述の自由度の高さ故に複数人開発で人によって方言が出てしまうことがある
 • RDocの独自マークアップ書式(RDoc::Markup)に慣れが必要
 ◦ 現代ではMarkdownも選択可能(@aycabra さんよりfeedback頂きました) 
 ◦ 末尾の補講スライドもご参照下さい 󰢛
 10

  5. YARD
 • RDocと双璧をなすドキュメント生成ツール
 ◦ 歴史は相当古く、Changelogを見る限りでも0.1aが2007年から存在 
 • YARDメタタグを使った書式により、より構造解析可能なドキュメントを宣言的に記述 できる
 •

    APIドキュメントのようなよりプログラムに近い視点のドキュメントを書く場合に優位 性がある
 ◦ 参考:rubocop/ruby-style-guideでは2018年以降APIドキュメントにはYARDを推奨している 
 11
 https://yardoc.org/ 

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

  7. RDoc/YARDのまとめ
 • Rubyでドキュメント生成するにはRDocとYARDがメジャーな選択肢
 ◦ RDocはRubyビルトインであること、自由にドキュメントが書けることが利点 
 ◦ YARDはメタタグを使うことで、より 形式の定まったドキュメントを書けること、IDEや language

    serverサポートなどの恩恵をRDocより得られるなどの利点がある 
 • 個人的には書く人によってばらつきが少なくなるYARDがオススメです
 • 今回話題にはしなかったが、以下も気にしつつ導入度合いを検討したい
 ◦ そもそもどの程度詳細なドキュメントを書くことにするのか?
 ◦ ドキュメントの内容が正しい状態を維持するコストをかけられるのか?
 23

  8. 補講:RDocでMarkdown
 RDocでもMarkdownは利用できる
 • rdocコマンドにオプションを指定
 ◦ --markup markdown • .rdoc_optionsに以下を記載する
 ◦

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