1 files changed, 32 insertions, 7 deletions

diff --git a/lib/chef/chef_fs/file_system/rest_list_dir.rb b/lib/chef/chef_fs/file_system/rest_list_dir.rb
index 0ac735a2c4..4c520aa71a 100644
--- a/lib/chef/chef_fs/file_system/rest_list_dir.rb
+++ b/lib/chef/chef_fs/file_system/rest_list_dir.rb
@@ -37,52 +37,77 @@ class Chef
           name =~ /\.json$/ && !is_dir
         end
 
+        #
+        # Does GET /<api_path>, assumes the result is of the format:
+        #
+        # {
+        #   "foo": "<api_path>/foo",
+        #   "bar": "<api_path>/bar",
+        # }
+        #
+        # Children are foo.json and bar.json in this case.
+        #
         def children
           begin
+            # Grab the names of the children, append json, and make child entries
             @children ||= root.get_json(api_path).keys.sort.map do |key|
               make_child_entry("#{key}.json", true)
             end
           rescue Timeout::Error => e
-            raise Chef::ChefFS::FileSystem::OperationFailedError.new(:children, self, e), "Timeout retrieving children: #{e}"
+            raise Chef::ChefFS::FileSystem::OperationFailedError.new(:children, self, e, "Timeout retrieving children: #{e}")
           rescue Net::HTTPServerException => e
+            # 404 = NotFoundError
             if $!.response.code == "404"
               raise Chef::ChefFS::FileSystem::NotFoundError.new(self, $!)
+            # Anything else is unexpected (OperationFailedError)
             else
-              raise Chef::ChefFS::FileSystem::OperationFailedError.new(:children, self, e), "HTTP error retrieving children: #{e}"
+              raise Chef::ChefFS::FileSystem::OperationFailedError.new(:children, self, e, "HTTP error retrieving children: #{e}")
             end
           end
         end
 
+        #
+        # Does POST <api_path> with file_contents
+        #
         def create_child(name, file_contents)
+          # Parse the contents to ensure they are valid JSON
           begin
             object = Chef::JSONCompat.parse(file_contents)
           rescue Chef::Exceptions::JSON::ParseError => e
-            raise Chef::ChefFS::FileSystem::OperationFailedError.new(:create_child, self, e), "Parse error reading JSON creating child '#{name}': #{e}"
+            raise Chef::ChefFS::FileSystem::OperationFailedError.new(:create_child, self, e, "Parse error reading JSON creating child '#{name}': #{e}")
           end
 
+          # Create the child entry that will be returned
           result = make_child_entry(name, true)
 
+          # Normalize the file_contents before post (add defaults, etc.)
           if data_handler
             object = data_handler.normalize_for_post(object, result)
             data_handler.verify_integrity(object, result) do |error|
-              raise Chef::ChefFS::FileSystem::OperationFailedError.new(:create_child, self), "Error creating '#{name}': #{error}"
+              raise Chef::ChefFS::FileSystem::OperationFailedError.new(:create_child, self, nil, "Error creating '#{name}': #{error}")
             end
           end
 
+          # POST /api_path with the normalized file_contents
           begin
             rest.post(api_path, object)
           rescue Timeout::Error => e
-            raise Chef::ChefFS::FileSystem::OperationFailedError.new(:create_child, self, e), "Timeout creating '#{name}': #{e}"
+            raise Chef::ChefFS::FileSystem::OperationFailedError.new(:create_child, self, e, "Timeout creating '#{name}': #{e}")
           rescue Net::HTTPServerException => e
+            # 404 = NotFoundError
             if e.response.code == "404"
               raise Chef::ChefFS::FileSystem::NotFoundError.new(self, e)
+            # 409 = AlreadyExistsError
             elsif $!.response.code == "409"
-              raise Chef::ChefFS::FileSystem::AlreadyExistsError.new(:create_child, self, e), "Failure creating '#{name}': #{path}/#{name} already exists"
+              raise Chef::ChefFS::FileSystem::AlreadyExistsError.new(:create_child, self, e, "Failure creating '#{name}': #{path}/#{name} already exists")
+            # Anything else is unexpected (OperationFailedError)
             else
-              raise Chef::ChefFS::FileSystem::OperationFailedError.new(:create_child, self, e), "Failure creating '#{name}': #{e.message}"
+              raise Chef::ChefFS::FileSystem::OperationFailedError.new(:create_child, self, e, "Failure creating '#{name}': #{e.message}")
             end
           end
 
+          # Clear the cache of children so that if someone asks for children
+          # again, we will get it again
           @children = nil
 
           result