Add docs for Railtie, Engine, Plugin and Application.

1 files changed, 15 insertions, 0 deletions

diff --git a/railties/lib/rails/plugin.rb b/railties/lib/rails/plugin.rb
index 64d03e7599..2a746e0fa6 100644
--- a/railties/lib/rails/plugin.rb
+++ b/railties/lib/rails/plugin.rb
@@ -1,6 +1,21 @@
 require 'rails/engine'
 
 module Rails
+  # Rails::Plugin is nothing more than a Rails::Engine, but since it's loaded too late
+  # in the boot process, it does not have the same configuration powers as a bare
+  # Rails::Engine.
+  #
+  # Opposite to Rails::Railtie and Rails::Engine, you are not supposed to inherit from
+  # Rails::Plugin. Rails::Plugin is automatically configured to be an engine by simply
+  # placing inside vendor/plugins. Since this is done automatically, you actually cannot
+  # declare a Rails::Engine inside your Plugin, otherwise it would cause the same files
+  # to be loaded twice. This means that if you want to ship an Engine as gem it cannot
+  # be used as plugin and vice-versa.
+  #
+  # Besides this conceptual difference, the only difference between Rails::Engine and
+  # Rails::Plugin is that plugins automatically load the file "init.rb" at the plugin
+  # root during the boot process.
+  # 
   class Plugin < Engine
     def self.inherited(base)
       raise "You cannot inherit from Rails::Plugin"