Add CHANGELOG entry and documentation for Routing Concerns

2 files changed, 68 insertions, 0 deletions

diff --git a/actionpack/CHANGELOG.md b/actionpack/CHANGELOG.md
index 2e683e7c47..d674fae9d4 100644
--- a/actionpack/CHANGELOG.md
+++ b/actionpack/CHANGELOG.md
@@ -1,5 +1,35 @@
 ## Rails 4.0.0 (unreleased) ##
 
+*   Add Routing Concerns to declare common routes that can be reused inside
+    others resources and routes.
+
+    Code before:
+
+        resources :messages do
+          resources :comments
+        end
+
+        resources :posts do
+          resources :comments
+          resources :images, only: :index
+        end
+
+    Code after:
+
+        concern :commentable do
+          resources :comments
+        end
+
+        concern :image_attachable do
+          resources :images, only: :index
+        end
+
+        resources :messages, concerns: :commentable
+
+        resources :posts, concerns: [:commentable, :image_attachable]
+
+    *David Heinemeier Hansson + Rafael Mendonça França*
+
 *   Add start_hour and end_hour options to the select_hour helper. *Evan Tann*
 
 *   Raises an ArgumentError when the first argument in `form_for` contain `nil`
diff --git a/actionpack/lib/action_dispatch/routing/mapper.rb b/actionpack/lib/action_dispatch/routing/mapper.rb
index 5ff2420921..ea5028a7c0 100644
--- a/actionpack/lib/action_dispatch/routing/mapper.rb
+++ b/actionpack/lib/action_dispatch/routing/mapper.rb
@@ -1584,11 +1584,49 @@ module ActionDispatch
           end
       end
 
+      # Routing Concerns allows you to declare common routes that can be reused
+      # inside others resources and routes.
+      #
+      #   concern :commentable do
+      #     resources :comments
+      #   end
+      #
+      #   concern :image_attachable do
+      #     resources :images, only: :index
+      #   end
+      #
+      # These concerns are used in Resources routing:
+      #
+      #   resources :messages, concerns: [:commentable, :image_attachable]
+      #
+      # or in a scope or namespace:
+      #
+      #   namespace :posts do
+      #     concerns :commentable
+      #   end
       module Concerns
+        # Define a routing concern using a name.
+        #
+        #   concern :commentable do
+        #     resources :comments
+        #   end
+        #
+        # Any routing helpers can be used inside a concern.
         def concern(name, &block)
           @concerns[name] = block
         end
 
+        # Use the named concerns
+        #
+        #   resources :posts do
+        #     concerns :commentable
+        #   end
+        #
+        # concerns also work in any routes helper that you want to use:
+        #
+        #   namespace :posts do
+        #     concerns :commentable
+        #   end
         def concerns(*names)
           names.flatten.each do |name|
             if concern = @concerns[name]