RubyKaigi 2025セッションレポート：コメントを書くと補完が変わる？Steepのドキュメント連携を検証してみた

eyecatch

こんにちは、ギフティでエンジニアをしているshirai(@shilo_113)です。私は普段、Ruby on Railsを採用したtoC向けプロダクトの開発を担当しています。

今回、4/16（水）〜4/18（金）に愛媛県松山市で開催されたRubyKaigi 2025に参加してきました。３日間ともハイレベルで素晴らしいセッションばかりでした！

rubykaigi2025

今回はその中でも印象的だった松本宗太郎さんの「API for docs」について内容を振り返りしつつ、発表の中で紹介のあった機能を手元の環境で実際に動かしてみたのでその所感などを共有いたします！

セッションの概要

今回、Rubyにおける静的型チェックツール「Steep」に、新たにエディタ統合型のドキュメント機能が追加されました。これにより、RBSに書いたコメントが、コード補完やホバー、シグネチャヘルプとしてリアルタイムに表示されるようになりました。これまでのRubyでは、RDocやYARDといったツールを使ってHTMLなどに出力されたドキュメントを「読む」ことが主流でした。しかしこの機能では、開発中のエディタ上で即座に表示され、補完候補選びにも役立つという、まさに次世代的な体験が実現されています。

それでは、発表の内容を詳しく振り返ってみます。

RBSコメントがリアルタイムに“読める”ように

Steepのドキュメント機能は、RBSファイルに記述されたコメントを次の3つの方法で表示します：

Hover（ホバー）：クラス名やメソッド名の上にカーソルを置くと、コメント内容が表示される。
Completion（補完）：メソッド補完候補に、そのメソッドの説明コメントが添えられる。
Signature Help（シグネチャヘルプ）：メソッド引数を入力しているときに、引数リストと説明がリアルタイムに表示される。

この機能により、ドキュメントを別途読む必要なく、コードの文脈に応じて「読める」ドキュメントが浮かび上がってくる開発体験が可能になります。

従来との違い：静的生成 vs API提供

従来のYARDやRDocでは、コメントをもとにHTMLなどの人が読む用の静的ドキュメントを生成していました。対してSteepでは、LSP（Language Server Protocol）経由で、エディタが必要に応じてコメント情報を要求し、API経由でリアルタイムに表示します。

これにより、ドキュメントの「作成→閲覧」の流れがなくなり、書いた瞬間から補完やツールチップに反映されるという即応性が実現されました。

実装面の工夫：Indexと識別子

型定義に紐づいたコメントを補完などに活用するためには、それらを正しく識別・管理し、必要に応じて取り出せる仕組みが必要になります。そこで導入が提案されたのがドキュメントインデックス（Index）です。

RBSコメントは、classやdefに紐づいてパースされ、ASTに格納される。
それぞれのコメントには、クラス名やメソッド名＋型（Method Type）などを組み合わせた「識別子」が与えられる。
この識別子をキーとして、補完候補表示時にコメントを取り出す。
コメントだけが変更された場合は、型チェック（Steepの本体処理）は再実行せず、インデックスだけ更新される。

この設計により、無駄な再チェックの回避や、将来的なドキュメント共有（例：YARDや他ツールとの連携）も視野に入れられています。

ということで実際に手元で動かしてみました

以前、youbi gemという「指定したフォーマットの曜日を返す」gem を作ったことがあるのですが、今回はこのシンプルなgemにRBS::InlineとSteepを導入したうえでVSCodeにSteep拡張を入れて、エディタ統合型のドキュメント機能を試してみました。

各種導入、セットアップ

RBS::InlineとSteepに関してはGithubリポジトリのReadmeを参照して導入しました。

RBS::Inline：https://github.com/soutaro/rbs-inline
Steep：https://github.com/soutaro/steep

VSCodeのSteep拡張はVSCodeのアクティビティバーの拡張機能マークから素直にインストールしました。 steep_extension

その他、基本的なセットアップについてはRBS::Inline、SteepのGithubリポジトリ、こちらの記事を参考にさせていただきました。

ドキュメント機能

今回はRBSファイルのjapanese_dayというメソッド（指定したフォーマットの曜日を返すメソッド）に以下のようにコメント記載しました。

  # 指定したフォーマットの曜日を返す
  # @rbs format: Symbol
  # @rbs return: String
  def japanese_day: (?format: Symbol) -> String

このようにRBSファイルにコメント形式で記載すると、その情報がAPIを介してリアルタイムにエディタに表示されます。

以下では、それぞれの機能がどのように動作するのか、VSCodeで検証した様子を紹介します。

Hover（ホバー）機能

Rubyコード上のjapanese_dayにカーソルを当てると・・・

hover

「指定したフォーマットの曜日を返す」というコメントがホバー表示されました！これは便利！

Completion（補完）機能

Time.now.jaと入力して補完を出すと・・・

completion

候補一覧にjapanese_dayが表示され、その横にドキュメントが表示されました。コメントがあると補完の信頼感が全然違いますね！

Signature Help（シグネチャヘルプ）機能

Signature Help（シグネチャヘルプ）機能は引数を入力しているときに、引数リストと説明がリアルタイムに表示される機能です。

signature_help

実際にメソッドの引数入力時に説明が表示されています。この機能も日々の開発の中でとても役立ちそうですね！

今回検証に用いたバージョンは本記事の最後に記載しております。

まとめ

本記事ではRubyKaigi 2025の「API for docs」の発表内容の振り返りを行うとともにSteepに新規に追加されたドキュメント機能について実際に手元で試してみました。

手元で試してみた結果、型とドキュメントが同じ文脈で扱われることにより、Rubyの開発体験はよりインタラクティブに進化していくのではないかという期待を非常に感じることができました。今後ぜひプロダクションのコードにもRBS::InlineやSteepを導入してみて実用性などを検証していきたいと思います。

ここまで読んでいただきありがとうございました！また来年のRubyKaigi 2026もぜひ参加したいと思います。函館楽しみですね！