diff --git a/actionpack/lib/abstract_controller/url_for.rb b/actionpack/lib/abstract_controller/url_for.rb
index <HASH>..<HASH> 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 <HASH>..<HASH> 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
added docs for AbC::UrlFor and AC::UrlFor.