Add comments and use def self.x instead of class<<self

4 files changed, 106 insertions, 69 deletions

diff --git a/lib/chef/event_dispatch/base.rb b/lib/chef/event_dispatch/base.rb
index b64c143421..50aee63450 100644
--- a/lib/chef/event_dispatch/base.rb
+++ b/lib/chef/event_dispatch/base.rb
@@ -282,7 +282,7 @@ class Chef
       # 4. Check if why-run safe
       #    - resource_bypassed: (goto 7) if not why-run safe
       # 5. During processing:
-      #    - resource_update_applied: For each actual change
+      #    - resource_update_applied: For each actual change (many per action)
       # 6. Processing complete status:
       #    - resource_failed if the resource threw an exception while running
       #    - resource_failed_retriable: (goto 3) if resource failed and will be retried
diff --git a/lib/chef/provider.rb b/lib/chef/provider.rb
index f3bc67d12f..1d106acccb 100644
--- a/lib/chef/provider.rb
+++ b/lib/chef/provider.rb
@@ -185,13 +185,18 @@ class Chef
 
     #
     # Include attributes, public and protected methods from this Resource in
-    # the provider.  Will delegate to
+    # the provider.
+    #
+    # If this is set to true, delegate methods are included in the provider so
+    # that you can call (for example) `attrname` and it will call
+    # `new_resource.attrname`.
     #
     # The actual include does not happen until the first time the Provider
     # is instantiated (so that we don't have to worry about load order issues).
     #
     # @param include_resource_dsl [Boolean] Whether to include resource DSL or
     #   not (defaults to `false`).
+    #
     def self.include_resource_dsl(include_resource_dsl)
       @include_resource_dsl = include_resource_dsl
     end
diff --git a/lib/chef/resource.rb b/lib/chef/resource.rb
index f70137a7b6..4c4eb84006 100644
--- a/lib/chef/resource.rb
+++ b/lib/chef/resource.rb
@@ -685,14 +685,20 @@ class Chef
     #
     # The provider class for this resource.
     #
+    # If `action :x do ... end` has been declared on this resource or its
+    # superclasses, this will return the `action_provider_class`.
+    #
     # If this is not set, `provider_for_action` will dynamically determine the
     # provider.
     #
     # @param arg [String, Symbol, Class] Sets the provider class for this resource.
     #   If passed a String or Symbol, e.g. `:file` or `"file"`, looks up the
     #   provider based on the name.
+    #
     # @return The provider class for this resource.
     #
+    # @see Chef::Resource.action_provider_class
+    #
     def provider(arg=nil)
       klass = if arg.kind_of?(String) || arg.kind_of?(Symbol)
         lookup_provider_constant(arg)
@@ -923,7 +929,6 @@ class Chef
           @resource_name = nil
         end
       end
-
       @resource_name
     end
     def self.resource_name=(name)
@@ -931,6 +936,19 @@ class Chef
     end
 
     #
+    # Use the class name as the resource name.
+    #
+    # Munges the last part of the class name from camel case to snake case,
+    # and sets the resource_name to that:
+    #
+    # A::B::BlahDBlah -> blah_d_blah
+    #
+    def self.use_automatic_resource_name
+      automatic_name = convert_to_snake_case(self.name.split('::')[-1])
+      resource_name automatic_name
+    end
+
+    #
     # The module where Chef should look for providers for this resource.
     # The provider for `MyResource` will be looked up using
     # `provider_base::MyResource`.  Defaults to `Chef::Provider`.
@@ -1004,74 +1022,90 @@ class Chef
       else
         :nothing
       end
+    end
+    def self.default_action=(action_name)
+      default_action action_name
+    end
 
-      #
-      # Define an action on this resource.
-      #
-      # The action is defined as a *recipe* block that will be compiled and then
-      # converged when the action is taken (when Resource is converged).  The recipe
-      # has access to the resource's attributes and methods, as well as the Chef
-      # recipe DSL.
-      #
-      # Resources in the action recipe may notify and subscribe to other resources
-      # within the action recipe, but cannot notify or subscribe to resources
-      # in the main Chef run.
-      #
-      # Resource actions are *inheritable*: if resource A defines `action :create`
-      # and B is a subclass of A, B gets all of A's actions.  Additionally,
-      # resource B can define `action :create` and call `super()` to invoke A's
-      # action code.
-      #
-      # @param name [Symbol] The action name to define.
-      # @param recipe_block The recipe to run when the action is taken. This block
-      #   takes no parameters, and will be evaluated in a new context containing:
-      #
-      #   - The resource's public and protected methods (including attributes)
-      #   - The Chef Recipe DSL (file, etc.)
-      #   - super() referring to the parent version of the action (if any)
-      #
-      # @return The Action class implementing the action
-      #
-      def action(action, &recipe_block)
-        action = action.to_sym
-        create_action_provider_class.action(action, &recipe_block)
-        self.allowed_actions += [ action ]
-        default_action action if default_action == :nothing
-      end
+    #
+    # Define an action on this resource.
+    #
+    # The action is defined as a *recipe* block that will be compiled and then
+    # converged when the action is taken (when Resource is converged).  The recipe
+    # has access to the resource's attributes and methods, as well as the Chef
+    # recipe DSL.
+    #
+    # Resources in the action recipe may notify and subscribe to other resources
+    # within the action recipe, but cannot notify or subscribe to resources
+    # in the main Chef run.
+    #
+    # Resource actions are *inheritable*: if resource A defines `action :create`
+    # and B is a subclass of A, B gets all of A's actions.  Additionally,
+    # resource B can define `action :create` and call `super()` to invoke A's
+    # action code.
+    #
+    # The first action defined (besides `:nothing`) will become the default
+    # action for the resource.
+    #
+    # @param name [Symbol] The action name to define.
+    # @param recipe_block The recipe to run when the action is taken. This block
+    #   takes no parameters, and will be evaluated in a new context containing:
+    #
+    #   - The resource's public and protected methods (including attributes)
+    #   - The Chef Recipe DSL (file, etc.)
+    #   - super() referring to the parent version of the action (if any)
+    #
+    # @return The Action class implementing the action
+    #
+    def self.action(action, &recipe_block)
+      action = action.to_sym
+      create_action_provider_class.action(action, &recipe_block)
+      self.allowed_actions += [ action ]
+      default_action action if default_action == :nothing
+    end
 
-      #
-      # The created action provider class for this resource, or nil if it has
-      # not been / does not need to be created.
-      #
-      # @api private
-      def action_provider_class
-        @action_provider_class ||
-          # If the superclass needed one, then we need one as well.
-          if superclass.respond_to?(:action_provider_class) && superclass.action_provider_class
-            create_action_provider_class
-          end
-      end
+    #
+    # The action provider class is an automatic `Provider` created to handle
+    # actions declared by `action :x do ... end`.
+    #
+    # This class will be returned by `resource.provider` if `resource.provider`
+    # is not set. `provider_for_action` will also use this instead of calling
+    # out to `Chef::ProviderResolver`.
+    #
+    # If the user has not declared actions on this class or its superclasses
+    # using `action :x do ... end`, then there is no need for this class and
+    # `action_provider_class` will be `nil`.
+    #
+    # @api private
+    #
+    def self.action_provider_class
+      @action_provider_class ||
+        # If the superclass needed one, then we need one as well.
+        if superclass.respond_to?(:action_provider_class) && superclass.action_provider_class
+          create_action_provider_class
+        end
+    end
 
-      #
-      # Create the action provider class
-      #
-      # @api private
-      def create_action_provider_class
-        return @action_provider_class if @action_provider_class
+    #
+    # Ensure the action provider class actually gets created. This is called
+    # when the user does `action :x do ... end`.
+    #
+    # @api private
+    def self.create_action_provider_class
+      return @action_provider_class if @action_provider_class
 
-        if superclass.respond_to?(:action_provider_class)
-          base_provider = superclass.action_provider_class
-        end
-        base_provider ||= Chef::Provider
-
-        resource_class = self
-        @action_provider_class = Class.new(base_provider) do
-          use_inline_resources
-          include_resource_dsl true
-          define_singleton_method(:to_s) { "#{resource_class} action provider" }
-          define_singleton_method(:inspect) { to_s }
-          define_method(:load_current_resource) {}
-        end
+      if superclass.respond_to?(:action_provider_class)
+        base_provider = superclass.action_provider_class
+      end
+      base_provider ||= Chef::Provider
+
+      resource_class = self
+      @action_provider_class = Class.new(base_provider) do
+        use_inline_resources
+        include_resource_dsl true
+        define_singleton_method(:to_s) { "#{resource_class} action provider" }
+        define_singleton_method(:inspect) { to_s }
+        define_method(:load_current_resource) {}
       end
     end
     def self.default_action=(action_name)
diff --git a/lib/chef/resource/reboot.rb b/lib/chef/resource/reboot.rb
index 801c066881..401f2f338f 100644
--- a/lib/chef/resource/reboot.rb
+++ b/lib/chef/resource/reboot.rb
@@ -26,8 +26,6 @@ class Chef
     class Reboot < Chef::Resource
       allowed_actions :request_reboot, :reboot_now, :cancel
 
-      allowed_actions :request_reboot, :reboot_now, :cancel
-
       def initialize(name, run_context=nil)
         super
         @provider = Chef::Provider::Reboot