FFIやFiddleで自動生成したメソッドをYardドキュメントに掲載させる

不完全な情報だが、ググっても出てきにくい情報だと思うので、忘れる前にメモする。

Rubyは動的な性質の強い言語で、動的にメソッドを定義する機会は多い。Ruby-FFIやFiddleはC言語の関数をRubyから呼び出すためのライブラリで、メソッドをモジュールに動的に追加する。そのため生成されたメソッドはYardドキュメントに掲載されない。（ユーザーはFFIやFiddleで追加されたメソッドを直接呼び出すべきではなく、きちんとエラー処理などを施したラッパーメソッドを作成してそれを呼び出すべきだ。だからYardで生成したドキュメントにそういったメソッドは載せるべきではない、という話があるが、今回それはおいておく。）

Yardにはマクロ機能がついており、これを利用すれば、かなり高い完成度でFFIやFiddleのドキュメントを自動生成できる。

具体的には下記のように、attach_function メソッドを再定義し、そこにマクロを追加する。

（ここでは、目的の関数が見つからなくてもRubyが停止しないようにしているが、それはこの記事には関係ない）

module HTS
  module LibHTS
    extend FFI::Library

    begin
      ffi_lib HTS.lib_path
    rescue LoadError => e
      raise LoadError, "#{e}\nCould not find #{HTS.lib_path}"
    end

    # @!macro attach_function
    #   @!method $1(${2--2})
    #   @return [${-1}] the return value of $0
    def self.attach_function(*)
      super
    rescue FFI::NotFoundError => e
      warn e.message
    end
  end
end

これでYardが attach_function で追加したメソッドを補足してくれるようになる。$1 ${2--2} などは、公式ドキュメント参照。この記事は以上です。

公式ドキュメント @macro：

参考元：