LoginSignup
0

More than 1 year has passed since last update.

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

Last updated at Posted at 2022-04-22

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

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

参考元:

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0