Question

I’d like to mark a method as deprecated, so the people using it can easily check their code and catch up. In Java you set @Deprecated and everybody knows what this means.

So is there a preferred way (or even tools) to mark and check for deprecations in Ruby?

Answer 1

For almost all cases, depending on a library or metaprogramming for a deprecation is overkill. Just add a comment to the rdoc and call the Kernel#warn method. For example:

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 

---

If you’re using Yard instead of rdoc, your doc comment should look like this:

# @deprecated Please use {#useful} instead 

Lastly, if you adhere to tomdoc, make your comment look like this:

# Deprecated: Please use `useful` instead 

Deprecated: Indicates that the method is deprecated and will be removed in a future version. You SHOULD use this to document methods that were Public but will be removed at the next major version.

---

Also, don’t forget to remove the deprecated method in some future (and properly semver‘d) release. Don’t make the same mistakes that the Java libraries did.