YARD + sord で RBS を生成する

README.md

YARD + sord で RBS を生成する

具体的な方法

• 添付の sh script か Rake task で
  • sh script は moon 経由で叩いている想定

sordの注意点

• ヘルプには表示されないが --rbs オプションを与えると RBS を出力する（--rbi は RBI）
  • 2020年リリースの version 3 から
• 入力は1ファイル、かつ元ファイルを上書きする
• yardoc を元に生成するのでファイル外の情報も参照する
  • 逆に Ruby 標準のライブラリには YARD がないのでいっぱい警告が出る

上の挙動から検討した扱い方

• 元の Ruby コードを concat して 1 ファイルとして与える
• これを上書きさせることで RBS の生成を実現する

メリット

• YARD から RBS を生成する方法は元の YARD の記述の質に依存するが、逆に変換を通すことで YARD の質が足りていないことが分かるため、ドキュメントに手を掛ける気があるなら、質は上がる
• RBS を直接書かないと決めてかかればコードの構造含めて二重管理にはならないし、RBS を覚えなくてもなんとかなる
• gem の場合、やはりリッチな YARD は欲しいよね

逆にもともとドキュメントを重視していなかったのなら YARD から入るメリットは薄い

generate-rbs

#! /bin/sh

git ls-files lib | \grep \.rb | xargs cat > sig/${MOON_PROJECT_ID}.rbs
bundle exec sord --rbs sig/${MOON_PROJECT_ID}.rbs

Rakefile

def target
  [
    "sig/",
    File.basename(Dir.glob("*.gemspec").first, ".gemspec"),
    ".rbs"
  ].join
end

namespace :sig do
  desc "generate RBS signatures"
  task :generate => :concat_codes do
    sh "sord --rbs #{target}"
  end
  
  desc "concat codes"
  task :concat_codes do
    FileUtils.mkdir_p("sig")
    File.open(target, "w") { |w|
      w.puts Dir.glob("lib/**/*.rb").map { |r|
        File.read(r)
      }.join("\n")
    }
  end
end