Add comments, fix faulty ||=

2 files changed, 39 insertions, 1 deletions

diff --git a/lib/chef/dsl/recipe.rb b/lib/chef/dsl/recipe.rb
index edd7e9aed1..7b467fd867 100644
--- a/lib/chef/dsl/recipe.rb
+++ b/lib/chef/dsl/recipe.rb
@@ -73,10 +73,31 @@ class Chef
         new_recipe.instance_eval(&new_def.recipe)
       end
 
+      #
       # Instantiates a resource (via #build_resource), then adds it to the
       # resource collection. Note that resource classes are looked up directly,
       # so this will create the resource you intended even if the method name
       # corresponding to that resource has been overridden.
+      #
+      # @param type [Symbol] The type of resource (e.g. `:file` or `:package`)
+      # @param name [String] The name of the resource (e.g. '/x/y.txt' or 'apache2')
+      # @param created_at [String] The caller of the resource.  Use `caller[0]`
+      #   to get the caller of your function.  Defaults to the caller of this
+      #   function.
+      # @param resource_attrs_block A block that lets you set attributes of the
+      #   resource (it is instance_eval'd on the resource instance).
+      #
+      # @return [Chef::Resource] The new resource.
+      #
+      # @example
+      #   declare_resource(:file, '/x/y.txy', caller[0]) do
+      #     action :delete
+      #   end
+      #   # Equivalent to
+      #   file '/x/y.txt' do
+      #     action :delete
+      #   end
+      #
       def declare_resource(type, name, created_at=nil, &resource_attrs_block)
         created_at ||= caller[0]
 
@@ -86,10 +107,27 @@ class Chef
         resource
       end
 
+      #
       # Instantiate a resource of the given +type+ with the given +name+ and
       # attributes as given in the +resource_attrs_block+.
       #
       # The resource is NOT added to the resource collection.
+      #
+      # @param type [Symbol] The type of resource (e.g. `:file` or `:package`)
+      # @param name [String] The name of the resource (e.g. '/x/y.txt' or 'apache2')
+      # @param created_at [String] The caller of the resource.  Use `caller[0]`
+      #   to get the caller of your function.  Defaults to the caller of this
+      #   function.
+      # @param resource_attrs_block A block that lets you set attributes of the
+      #   resource (it is instance_eval'd on the resource instance).
+      #
+      # @return [Chef::Resource] The new resource.
+      #
+      # @example
+      #   build_resource(:file, '/x/y.txy', caller[0]) do
+      #     action :delete
+      #   end
+      #
       def build_resource(type, name, created_at=nil, &resource_attrs_block)
         created_at ||= caller[0]
 
diff --git a/lib/chef/resource_builder.rb b/lib/chef/resource_builder.rb
index e076856479..bb0962d128 100644
--- a/lib/chef/resource_builder.rb
+++ b/lib/chef/resource_builder.rb
@@ -90,7 +90,7 @@ class Chef
       # Checks the new platform => short_name => resource mapping initially
       # then fall back to the older approach (Chef::Resource.const_get) for
       # backward compatibility
-      resource_class ||= Chef::Resource.resource_for_node(type, run_context.node)
+      @resource_class ||= Chef::Resource.resource_for_node(type, run_context.node)
     end
 
     def is_trivial_resource?(resource)