diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb
index ff0a7bf6ce730..dc880cd866ae5 100644
--- a/actionpack/lib/action_controller/base.rb
+++ b/actionpack/lib/action_controller/base.rb
@@ -3,11 +3,16 @@
require "action_controller/metal/params_wrapper"
module ActionController
- # The metal anonymous class is simple workaround the ordering issues there are with modules.
- # They need to be included in specific order which makes it impossible for 3rd party libs (like ActiveRecord)
- # to hook up with its own functionality. Having anonymous super class type of Metal with AbstractController::Rendering
- # included, allows us to include ActionView::Rendering (which implements AbstractController::Rendering interface)
- # after the AbstractController::Rendering and before ActionController::Rendering.
+ # The metal anonymous class was introduced to solve issue with including modules in ActionController::Base.
+ # Modules needes to be included in particluar order. First wee need to have AbstractController::Rendering included,
+ # next we should include actuall implementation which would be for example ActionView::Rendering and after that
+ # ActionController::Rendering. This order must be preserved and as we want to have middle module included dynamicaly
+ # metal class was introduced. It has AbstractController::Rendering included and is parent class of
+ # ActionController::Base which includes ActionController::Rendering. If we include ActionView::Rendering
+ # beetween them to perserve the required order, we can simply do this by:
+ #
+ # ActionController::Base.superclass.send(:include, ActionView::Rendering)
+ #
metal = Class.new(Metal) do
include AbstractController::Rendering
end