This might be more a question for the guys in the “Ruby on Rails: Core” group, but I’ll try it out here first…
So, while writing a gem (engine) for rails, I found that I needed to have my app (in a pre-filter) directly query the router. In the “old” days, this was done using ActionController::Routing::Routes.recognize_path(). My 2nd edition of “Agile Web Development with Rails” (which covers rails 1.2) even demonstrates how to use it in a rails console to verify your routes. This is now deprecated (in rails 3.0.x) as indicated by the following warning in my application log:
DEPRECATION WARNING: ActionController::Routing::Routes is deprecated. Instead, use Rails.application.routes.
So, today you use Rails.application.routes.recognize_path(). Beautiful. It works great.
However, when trying to re-learn or re-discover this method (I hadn’t used it in quite a while) I noticed it isn’t documented (http://api.rubyonrails.org/). Rails.application.routes returns an instance of the ActionDispatch::Routing::RouteSet class which, looking at the source, has the “#:nodoc:” rdoc tag to prevent it being included in the project documentation.
This communicates to me that this isn’t considered part of the public API and is therefor subject to change, be renamed, whatever.
So my question is, is this true? Since I’m writing a gem, a rails engine that needs to call this method, am I in danger of a future rails point release breaking my gem? Or, is the lack of documentation superfluous and I can be assured that this method: Rails.application.routes.recognize_path(path, environment = {}) will always be available (with that signature and behavior)?
