diff --git a/actionpack/lib/abstract_controller/url_for.rb b/actionpack/lib/abstract_controller/url_for.rb
index e5d5bef6b4aa55938b06cbf2549352cc866bf495..d2245d0b0decebd7ed7e3cac73f54eee6c14fe1a 100644
--- a/actionpack/lib/abstract_controller/url_for.rb
+++ b/actionpack/lib/abstract_controller/url_for.rb
@@ -1,3 +1,9 @@
+# Includes #url_for into the host class (e.g. an abstract controller or mailer). The class
+# has to provide a RouteSet by implementing the #_routes methods. Otherwise, an exception
+# will be raised.
+#
+# Note that this module is completely decoupled from HTTP - the only requirement is a valid 
+# #_routes implementation.
 module AbstractController
   module UrlFor
     extend ActiveSupport::Concern
diff --git a/actionpack/lib/action_controller/metal/url_for.rb b/actionpack/lib/action_controller/metal/url_for.rb
index 6fc0cf1fb860404d044487c8d04f52e90acbe0ef..9a03033f4806310b7848cd33599141378531958a 100644
--- a/actionpack/lib/action_controller/metal/url_for.rb
+++ b/actionpack/lib/action_controller/metal/url_for.rb
@@ -1,3 +1,9 @@
+# Includes #url_for into the host class. The class has to provide a RouteSet by implementing 
+# the #_routes methods. Otherwise, an exception will be raised.
+#
+# In addition to AbstractController::UrlFor, this module accesses the HTTP layer to define 
+# url options like the +host+. In order to do so, this module requires the host class
+# to implement #env, which needs to be a Rack-compatible environment hash.
 module ActionController
   module UrlFor
     extend ActiveSupport::Concern