tap method in Rails 3 - Have I understood the API Docs correctly?

The tap method has been in Ruby since 1.8.7:

tap{|x|...} => obj

Yields x to the block, and then returns x. The primary purpose of this method is to “tap into” a method chain, in order to perform operations on intermediate results within the chain.

Note that 1.8.6 did not have Object#tap. Presumably, tap was in older versions of Rails (as a monkey patch on Object) but was added to Ruby itself in 1.8.7. Since 1.8.6 is rather ancient now, the Rails version was deprecated and, in more recent Rails releases, removed entirely.

Object#tap is still around so tap itself has not been deprecated, just the Rails monkey patched version has been removed.

The Object#tap monkey patch from ActiveSupport is deprecated because it has been part of Ruby since 1.9.0 and 1.8.7.