Rubyで非推奨のコードをマークするベストプラクティスは?

概要

メソッドを非推奨としてマークして、それを使用しているユーザーがコードを簡単にチェックして最新情報を確認できるようにしたいと考えています。 Java では @Deprecated を設定すると、これが何を意味するか誰もが知っています。

それでは、Ruby で非推奨をマークしてチェックするための好ましい方法 (またはツール) はあるのでしょうか?

解決策

ほとんどの場合、非推奨をライブラリやメタプログラミングに依存するのは過剰です。 Rdoc にコメントを追加して、Kernel#warn メソッドを呼び出すだけです。例えば：

class Foo
  # <b>DEPRECATED:</b> Please use <tt>useful</tt> instead.
  def useless
    warn "[DEPRECATION] `useless` is deprecated. Please use `useful` instead."
    useful
  end

  def useful
    # ...
  end
end

rdoc の代わりに Yard を使用している場合、ドキュメント コメントは次のようになります。

# @deprecated Please use {#useful} instead

最後に、tomdoc に従う場合は、コメントを次のようにします。

# Deprecated: Please use `useful` instead

また、将来の (そして適切にサポートされた) リリースでは、非推奨のメソッドを削除することを忘れないでください。 Java ライブラリと同じ間違いを犯さないでください。