add some @yield docs

added some FIXMEs because trying to sort out types for random undocumented code was making me completely aggro

16 files changed, 53 insertions, 5 deletions

diff --git a/lib/chef/chef_fs/data_handler/container_data_handler.rb b/lib/chef/chef_fs/data_handler/container_data_handler.rb
index 27bb9dc736..04973b5135 100644
--- a/lib/chef/chef_fs/data_handler/container_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/container_data_handler.rb
@@ -15,10 +15,16 @@ class Chef
           return key == "containername"
         end
 
+        # Verify that the JSON hash for this type has a key that matches its name.
+        #
+        # @param object [Object] JSON hash of the object
+        # @param entry [Chef::ChefFS::FileSystem::BaseFSObject] filesystem object we are verifying
+        # @yield  [s] callback to handle errors
+        # @yieldparam [s<string>] error message
         def verify_integrity(object, entry)
           base_name = remove_dot_json(entry.name)
           if object["containername"] != base_name
-            yield("Name in #{entry.path_for_printing} must be '#{base_name}' (is '#{object['name']}')")
+            yield("Name in #{entry.path_for_printing} must be '#{base_name}' (is '#{object['containername']}')")
           end
         end
 
diff --git a/lib/chef/chef_fs/data_handler/data_bag_item_data_handler.rb b/lib/chef/chef_fs/data_handler/data_bag_item_data_handler.rb
index 89087e159f..c6b6449d52 100644
--- a/lib/chef/chef_fs/data_handler/data_bag_item_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/data_bag_item_data_handler.rb
@@ -42,6 +42,12 @@ class Chef
           Chef::DataBagItem
         end
 
+        # Verify that the JSON hash for this type has a key that matches its name.
+        #
+        # @param object [Object] JSON hash of the object
+        # @param entry [Chef::ChefFS::FileSystem::BaseFSObject] filesystem object we are verifying
+        # @yield  [s] callback to handle errors
+        # @yieldparam [s<string>] error message
         def verify_integrity(object, entry)
           base_name = remove_dot_json(entry.name)
           if object["raw_data"]["id"] != base_name
diff --git a/lib/chef/chef_fs/data_handler/data_handler_base.rb b/lib/chef/chef_fs/data_handler/data_handler_base.rb
index f487218f31..b30ae9c708 100644
--- a/lib/chef/chef_fs/data_handler/data_handler_base.rb
+++ b/lib/chef/chef_fs/data_handler/data_handler_base.rb
@@ -185,10 +185,12 @@ class Chef
           result
         end
 
-        #
         # Verify that the JSON hash for this type has a key that matches its name.
-        # Calls the on_error block with the error, if there is one.
         #
+        # @param object [Object] JSON hash of the object
+        # @param entry [Chef::ChefFS::FileSystem::BaseFSObject] filesystem object we are verifying
+        # @yield  [s] callback to handle errors
+        # @yieldparam [s<string>] error message
         def verify_integrity(object, entry)
           base_name = remove_dot_json(entry.name)
           if object["name"] != base_name
diff --git a/lib/chef/chef_fs/data_handler/organization_data_handler.rb b/lib/chef/chef_fs/data_handler/organization_data_handler.rb
index 4afde75d40..0facd5d55d 100644
--- a/lib/chef/chef_fs/data_handler/organization_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/organization_data_handler.rb
@@ -19,6 +19,12 @@ class Chef
           return key == "name"
         end
 
+        # Verify that the JSON hash for this type has a key that matches its name.
+        #
+        # @param object [Object] JSON hash of the object
+        # @param entry [Chef::ChefFS::FileSystem::BaseFSObject] filesystem object we are verifying
+        # @yield  [s] callback to handle errors
+        # @yieldparam [s<string>] error message
         def verify_integrity(object, entry)
           if entry.org != object["name"]
             yield("Name must be '#{entry.org}' (is '#{object['name']}')")
diff --git a/lib/chef/chef_fs/data_handler/policy_data_handler.rb b/lib/chef/chef_fs/data_handler/policy_data_handler.rb
index f88b41401f..fa7bbe9101 100644
--- a/lib/chef/chef_fs/data_handler/policy_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/policy_data_handler.rb
@@ -26,14 +26,20 @@ class Chef
           normalize_hash(policy, defaults)
         end
 
+        # Verify that the JSON hash for this type has a key that matches its name.
+        #
+        # @param object [Object] JSON hash of the object
+        # @param entry [Chef::ChefFS::FileSystem::BaseFSObject] filesystem object we are verifying
+        # @yield  [s] callback to handle errors
+        # @yieldparam [s<string>] error message
         def verify_integrity(object_data, entry)
           name, revision = name_and_revision(entry.name)
           if object_data["name"] != name
-            yield("Object name '#{object_data['name']}' doesn't match entry '#{entry.name}'.")
+            yield("Object name '#{object_data['name']}' doesn't match entry '#{name}'.")
           end
 
           if object_data["revision_id"] != revision
-            yield("Object revision ID '#{object_data['revision']}' doesn't match entry '#{entry.name}'.")
+            yield("Object revision ID '#{object_data['revision_id']}' doesn't match entry '#{revision}'.")
           end
         end
       end
diff --git a/lib/chef/chef_fs/data_handler/policy_group_data_handler.rb b/lib/chef/chef_fs/data_handler/policy_group_data_handler.rb
index e20676a791..f7aa92373c 100644
--- a/lib/chef/chef_fs/data_handler/policy_group_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/policy_group_data_handler.rb
@@ -15,6 +15,12 @@ class Chef
           result
         end
 
+        # Verify that the JSON hash for this type has a key that matches its name.
+        #
+        # @param object [Object] JSON hash of the object
+        # @param entry [Chef::ChefFS::FileSystem::BaseFSObject] filesystem object we are verifying
+        # @yield  [s] callback to handle errors
+        # @yieldparam [s<string>] error message
         def verify_integrity(object_data, entry)
           if object_data["policies"].empty?
             yield("Policy group #{object_data["name"]} does not have any policies in it.")
diff --git a/lib/chef/http.rb b/lib/chef/http.rb
index 17024c4bdc..dd02550294 100644
--- a/lib/chef/http.rb
+++ b/lib/chef/http.rb
@@ -159,6 +159,9 @@ class Chef
     #
     # If no block is given, the tempfile is returned, which means it's up to
     # you to unlink the tempfile when you're done with it.
+    #
+    # @yield [tempfile] block to process the tempfile
+    # @yieldparams [tempfile<Tempfile>] tempfile
     def streaming_request(path, headers = {})
       url = create_url(path)
       response, rest_request, return_value = nil, nil, nil
diff --git a/lib/chef/http/socketless_chef_zero_client.rb b/lib/chef/http/socketless_chef_zero_client.rb
index 482d4ce292..8c1578b976 100644
--- a/lib/chef/http/socketless_chef_zero_client.rb
+++ b/lib/chef/http/socketless_chef_zero_client.rb
@@ -148,6 +148,7 @@ class Chef
         @url.port
       end
 
+      # FIXME: yard with @yield
       def request(method, url, body, headers)
         request = req_to_rack(method, url, body, headers)
         res = ChefZero::SocketlessServerMap.request(port, request)
diff --git a/lib/chef/knife.rb b/lib/chef/knife.rb
index 1c2c88e540..30825750a8 100644
--- a/lib/chef/knife.rb
+++ b/lib/chef/knife.rb
@@ -510,6 +510,7 @@ class Chef
       response.body
     end
 
+    # FIXME: yard with @yield
     def create_object(object, pretty_name = nil, object_class: nil)
       output = edit_data(object, object_class: object_class)
 
@@ -526,6 +527,7 @@ class Chef
       output(output) if config[:print_after]
     end
 
+    # FIXME: yard with @yield
     def delete_object(klass, name, delete_name = nil)
       confirm("Do you really want to delete #{name}")
 
diff --git a/lib/chef/mixin/command.rb b/lib/chef/mixin/command.rb
index 387292c8f8..0cc3143ec7 100644
--- a/lib/chef/mixin/command.rb
+++ b/lib/chef/mixin/command.rb
@@ -177,6 +177,7 @@ class Chef
 
       # module_function :popen4
 
+      # FIXME: yard with @yield
       def chdir_or_tmpdir(dir)
         dir ||= Dir.tmpdir
         unless File.directory?(dir)
diff --git a/lib/chef/mixin/provides.rb b/lib/chef/mixin/provides.rb
index a9dc8bc8f0..43a726de8c 100644
--- a/lib/chef/mixin/provides.rb
+++ b/lib/chef/mixin/provides.rb
@@ -13,6 +13,7 @@ class Chef
 
       # Check whether this resource provides the resource_name DSL for the given
       # node.  TODO remove this when we stop checking unregistered things.
+      # FIXME: yard with @yield
       def provides?(node, resource)
         raise NotImplementedError, :provides?
       end
diff --git a/lib/chef/resource_collection/resource_list.rb b/lib/chef/resource_collection/resource_list.rb
index fe96e1a69c..37eb12a107 100644
--- a/lib/chef/resource_collection/resource_list.rb
+++ b/lib/chef/resource_collection/resource_list.rb
@@ -76,6 +76,7 @@ class Chef
         @resources
       end
 
+      # FIXME: yard with @yield
       def execute_each_resource
         @iterator = ResourceCollection::StepableIterator.for_collection(@resources)
         @iterator.each_with_index do |resource, idx|
diff --git a/lib/chef/run_list.rb b/lib/chef/run_list.rb
index 86c28e6824..4dea938423 100644
--- a/lib/chef/run_list.rb
+++ b/lib/chef/run_list.rb
@@ -105,10 +105,12 @@ class Chef
       @run_list_items[pos] = parse_entry(item)
     end
 
+    # FIXME: yard with @yield
     def each
       @run_list_items.each { |i| yield(i) }
     end
 
+    # FIXME: yard with @yield
     def each_index
       @run_list_items.each_index { |i| yield(i) }
     end
diff --git a/lib/chef/shell/model_wrapper.rb b/lib/chef/shell/model_wrapper.rb
index 5f2d89d641..8c3e456a9b 100644
--- a/lib/chef/shell/model_wrapper.rb
+++ b/lib/chef/shell/model_wrapper.rb
@@ -59,6 +59,7 @@ module Shell
 
     alias :load :show
 
+    # FIXME: yard with @yield
     def transform(what_to_transform)
       if what_to_transform == :all
         objects_to_transform = list_objects
diff --git a/lib/chef/util/windows/net_user.rb b/lib/chef/util/windows/net_user.rb
index 1366700304..009252c4c1 100644
--- a/lib/chef/util/windows/net_user.rb
+++ b/lib/chef/util/windows/net_user.rb
@@ -119,6 +119,7 @@ class Chef::Util::Windows::NetUser < Chef::Util::Windows
     NetUser.net_local_group_add_member(nil, "Users", args[:name])
   end
 
+  # FIXME: yard with @yield
   def user_modify
     user = get_info
     user[:last_logon] = user[:units_per_week] = 0 #ignored as per USER_INFO_3 doc
diff --git a/lib/chef/win32/api/file.rb b/lib/chef/win32/api/file.rb
index aeb424bab0..7489c94fd9 100644
--- a/lib/chef/win32/api/file.rb
+++ b/lib/chef/win32/api/file.rb
@@ -535,6 +535,7 @@ BOOL WINAPI VerQueryValue(
         # retrieves a file search handle and passes it
         # to +&block+ along with the find_data.  also
         # ensures the handle is closed on exit of the block
+        # FIXME: yard with @yield
         def file_search_handle(path)
           begin
             # Workaround for CHEF-4419:
@@ -559,6 +560,7 @@ BOOL WINAPI VerQueryValue(
         # retrieves a file handle and passes it
         # to +&block+ along with the find_data.  also
         # ensures the handle is closed on exit of the block
+        # FIXME: yard with @yield
         def file_handle(path)
           begin
             path = canonical_encode_path(path)
@@ -574,6 +576,7 @@ BOOL WINAPI VerQueryValue(
           end
         end
 
+        # FIXME: yard with @yield
         def symlink_file_handle(path)
           begin
             path = encode_path(path)