Add many comments to DataHandler and FileSystem classes

17 files changed, 139 insertions, 23 deletions

diff --git a/lib/chef/chef_fs/data_handler/client_data_handler.rb b/lib/chef/chef_fs/data_handler/client_data_handler.rb
index 4b6b8f5c79..d81f35e861 100644
--- a/lib/chef/chef_fs/data_handler/client_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/client_data_handler.rb
@@ -22,7 +22,7 @@ class Chef
           result
         end
 
-        def preserve_key(key)
+        def preserve_key?(key)
           return key == 'name'
         end
 
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 8b108bcf73..980453cbab 100644
--- a/lib/chef/chef_fs/data_handler/container_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/container_data_handler.rb
@@ -11,7 +11,7 @@ class Chef
           })
         end
 
-        def preserve_key(key)
+        def preserve_key?(key)
           return key == 'containername'
         end
 
diff --git a/lib/chef/chef_fs/data_handler/cookbook_data_handler.rb b/lib/chef/chef_fs/data_handler/cookbook_data_handler.rb
index d2e2a3ef6c..56b7e0b765 100644
--- a/lib/chef/chef_fs/data_handler/cookbook_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/cookbook_data_handler.rb
@@ -23,7 +23,7 @@ class Chef
           })
         end
 
-        def preserve_key(key)
+        def preserve_key?(key)
           return key == 'cookbook_name' || key == 'version'
         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 240a42756d..1306922081 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
@@ -34,7 +34,7 @@ class Chef
           normalize_for_post(data_bag_item, entry)
         end
 
-        def preserve_key(key)
+        def preserve_key?(key)
           return key == 'id'
         end
 
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 a9bbc0bf1b..a3dc92405c 100644
--- a/lib/chef/chef_fs/data_handler/data_handler_base.rb
+++ b/lib/chef/chef_fs/data_handler/data_handler_base.rb
@@ -1,17 +1,32 @@
 class Chef
   module ChefFS
     module DataHandler
+      #
+      # The base class for all *DataHandlers.
+      #
+      # DataHandlers' job is to know the innards of Chef objects and manipulate
+      # JSON for them, adding defaults and formatting them.
+      #
       class DataHandlerBase
+        #
+        # Remove all default values from a Chef object's JSON so that the only
+        # thing you see are the values that have been explicitly set.
+        # Achieves this by calling normalize({}, entry) to get the list of
+        # defaults, and subtracting anything that is the same.
+        #
         def minimize(object, entry)
           default_object = default(entry)
           object.each_pair do |key, value|
-            if default_object[key] == value && !preserve_key(key)
+            if default_object[key] == value && !preserve_key?(key)
               object.delete(key)
             end
           end
           object
         end
 
+        #
+        # Takes a name like blah.json and removes the .json from it.
+        #
         def remove_dot_json(name)
           if name.length < 5 || name[-5,5] != ".json"
             raise "Invalid name #{path}: must end in .json"
@@ -19,14 +34,34 @@ class Chef
           name[0,name.length-5]
         end
 
-        def preserve_key(key)
+        #
+        # Return true if minimize() should preserve a key even if it is the same
+        # as the default.  Often used for ids and names.
+        #
+        def preserve_key?(key)
           false
         end
 
+        #
+        # Get the default value for an entry.  Calls normalize({}, entry).
+        #
         def default(entry)
           normalize({}, entry)
         end
 
+        #
+        # Utility function to help subclasses do normalize().  Pass in a hash
+        # and a list of keys with defaults, and normalize will:
+        #
+        # 1. Fill in the defaults
+        # 2. Put the actual values in the order of the defaults
+        # 3. Move any other values to the end
+        #
+        # == Example
+        #
+        #   normalize_hash({x: 100, c: 2, a: 1}, { a: 10, b: 20, c: 30})
+        #   -> { a: 1, b: 20, c: 2, x: 100}
+        #
         def normalize_hash(object, defaults)
           # Make a normalized result in the specified order for diffing
           result = {}
@@ -39,14 +74,25 @@ class Chef
           result
         end
 
+        # Specialized function to normalize an object before POSTing it, since
+        # some object types want slightly different values on POST.
+        # If not overridden, this just calls normalize()
         def normalize_for_post(object, entry)
           normalize(object, entry)
         end
 
+        # Specialized function to normalize an object before PUTing it, since
+        # some object types want slightly different values on PUT.
+        # If not overridden, this just calls normalize().
         def normalize_for_put(object, entry)
           normalize(object, entry)
         end
 
+        #
+        # normalize a run list (an array of run list items).
+        # Leaves recipe[name] and role[name] alone, and translates
+        # name to recipe[name].  Then calls uniq on the result.
+        #
         def normalize_run_list(run_list)
           run_list.map{|item|
             case item.to_s
@@ -60,22 +106,46 @@ class Chef
           }.uniq
         end
 
+        #
+        # Bring in an instance of this object from Ruby.  (Like roles/x.rb)
+        #
         def from_ruby(ruby)
           chef_class.from_file(ruby).to_hash
         end
 
+        #
+        # Turn a JSON hash into a bona fide Chef object (like Chef::Node).
+        #
         def chef_object(object)
           chef_class.json_create(object)
         end
 
+        #
+        # Write out the Ruby file for this instance.  (Like roles/x.rb)
+        #
         def to_ruby(object)
           raise NotImplementedError
         end
 
+        #
+        # Get the class for instances of this type.  Must be overridden.
+        #
         def chef_class
           raise NotImplementedError
         end
 
+        #
+        # Helper to write out a Ruby file for a JSON hash.  Writes out only
+        # the keys specified in "keys"; anything else must be emitted by the
+        # caller.
+        #
+        # == Example
+        #
+        #   to_ruby_keys({"name" => "foo", "environment" => "desert", "foo": "bar"}, [ "name", "environment" ])
+        #   ->
+        #   'name "foo"
+        #   environment "desert"'
+        #
         def to_ruby_keys(object, keys)
           result = ''
           keys.each do |key|
@@ -115,6 +185,10 @@ 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.
+        #
         def verify_integrity(object, entry, &on_error)
           base_name = remove_dot_json(entry.name)
           if object['name'] != base_name
diff --git a/lib/chef/chef_fs/data_handler/environment_data_handler.rb b/lib/chef/chef_fs/data_handler/environment_data_handler.rb
index 9da10ebfa5..5105f2ac49 100644
--- a/lib/chef/chef_fs/data_handler/environment_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/environment_data_handler.rb
@@ -17,7 +17,7 @@ class Chef
           })
         end
 
-        def preserve_key(key)
+        def preserve_key?(key)
           return key == 'name'
         end
 
diff --git a/lib/chef/chef_fs/data_handler/group_data_handler.rb b/lib/chef/chef_fs/data_handler/group_data_handler.rb
index 619822fe70..4d1b10f321 100644
--- a/lib/chef/chef_fs/data_handler/group_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/group_data_handler.rb
@@ -36,7 +36,7 @@ class Chef
           result
         end
 
-        def preserve_key(key)
+        def preserve_key?(key)
           return key == 'name'
         end
 
diff --git a/lib/chef/chef_fs/data_handler/node_data_handler.rb b/lib/chef/chef_fs/data_handler/node_data_handler.rb
index f2c97c734f..04faa527f0 100644
--- a/lib/chef/chef_fs/data_handler/node_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/node_data_handler.rb
@@ -21,7 +21,7 @@ class Chef
           result
         end
 
-        def preserve_key(key)
+        def preserve_key?(key)
           return key == 'name'
         end
 
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 1f2f9ffaf5..da911c08f0 100644
--- a/lib/chef/chef_fs/data_handler/organization_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/organization_data_handler.rb
@@ -15,7 +15,7 @@ class Chef
           result
         end
 
-        def preserve_key(key)
+        def preserve_key?(key)
           return key == 'name'
         end
 
diff --git a/lib/chef/chef_fs/data_handler/role_data_handler.rb b/lib/chef/chef_fs/data_handler/role_data_handler.rb
index bc1c076280..21c3013e9f 100644
--- a/lib/chef/chef_fs/data_handler/role_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/role_data_handler.rb
@@ -23,7 +23,7 @@ class Chef
           result
         end
 
-        def preserve_key(key)
+        def preserve_key?(key)
           return key == 'name'
         end
 
diff --git a/lib/chef/chef_fs/data_handler/user_data_handler.rb b/lib/chef/chef_fs/data_handler/user_data_handler.rb
index 99a247f2db..2b50ce38d8 100644
--- a/lib/chef/chef_fs/data_handler/user_data_handler.rb
+++ b/lib/chef/chef_fs/data_handler/user_data_handler.rb
@@ -17,7 +17,7 @@ class Chef
           })
         end
 
-        def preserve_key(key)
+        def preserve_key?(key)
           return key == 'name'
         end
 
diff --git a/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb b/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb
index 14f3e8413b..1e180a8f57 100644
--- a/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb
+++ b/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb
@@ -33,7 +33,22 @@ require 'chef/chef_fs/data_handler/container_data_handler'
 class Chef
   module ChefFS
     module FileSystem
+      #
+      # Represents the root of a local Chef repository, with directories for
+      # nodes, cookbooks, roles, etc. under it.
+      #
       class ChefRepositoryFileSystemRootDir < BaseFSDir
+        #
+        # Create a new Chef Repository File System root.
+        #
+        # == Parameters
+        # - child_paths - a hash of child paths, e.g.:
+        #   "nodes" => [ '/var/nodes', '/home/jkeiser/nodes' ],
+        #   "roles" => [ '/var/roles' ],
+        #   ...
+        # - root_paths - an array of paths representing the top level, where
+        #   org.json, members.json, and invites.json will be stored.
+        #
         def initialize(child_paths, root_paths=nil)
           super("", nil)
           @child_paths = child_paths
@@ -67,7 +82,6 @@ class Chef
 
         def create_child(name, file_contents = nil)
           if file_contents
-            d = root_dir
             child = root_dir.create_child(name, file_contents)
           else
             child_paths[name].each do |path|
@@ -86,7 +100,7 @@ class Chef
           nil
         end
 
-        # Used to print out the filesystem
+        # Used to print out a human-readable file system description
         def fs_description
           repo_paths = root_paths || [ File.dirname(child_paths['cookbooks'][0]) ]
           result = "repository at #{repo_paths.join(', ')}\n"
@@ -105,6 +119,10 @@ class Chef
 
         private
 
+        #
+        # A FileSystemEntry representing the root path where invites.json,
+        # members.json and org.json may be found.
+        #
         def root_dir
           MultiplexedDir.new(root_paths.select { |path| File.exists?(path) }.map do |path|
             dir = ChefRepositoryFileSystemEntry.new(name, parent, path)
@@ -113,6 +131,12 @@ class Chef
           end)
         end
 
+        #
+        # Create a child entry of the appropriate type:
+        # cookbooks, data_bags, acls, etc.  All will be multiplexed (i.e. if
+        # you have multiple paths for cookbooks, the multiplexed dir will grab
+        # cookbooks from all of them when you list or grab them).
+        #
         def make_child_entry(name)
           paths = child_paths[name].select do |path|
             File.exists?(path)
diff --git a/lib/chef/chef_fs/file_system/chef_server_root_dir.rb b/lib/chef/chef_fs/file_system/chef_server_root_dir.rb
index 069a2e29fa..755fd5dca3 100644
--- a/lib/chef/chef_fs/file_system/chef_server_root_dir.rb
+++ b/lib/chef/chef_fs/file_system/chef_server_root_dir.rb
@@ -36,7 +36,29 @@ require 'chef/chef_fs/data_handler/container_data_handler'
 class Chef
   module ChefFS
     module FileSystem
+      #
+      # Represents the root of a Chef server (or organization), under which
+      # nodes, roles, cookbooks, etc. can be found.
+      #
       class ChefServerRootDir < BaseFSDir
+        #
+        # Create a new Chef server root.
+        #
+        # == Parameters
+        #
+        # - root_name - a friendly name for the root, for printing--like "remote" or "chef_central".
+        # - chef_config - a hash with options that look suspiciously like Chef::Config, including the
+        #                 following keys:
+        #   - :chef_server_url - the URL to the Chef server or top of the organization
+        #   - :node_name - the username to authenticate to the Chef server with
+        #   - :client_key - the private key for the user for authentication
+        #   - :environment - the environment in which you are presently working
+        #   - :repo_mode - the repository mode, :hosted_everything, :everything or :static.
+        #                  This determines the set of subdirectories the Chef server
+        #                  will offer up.
+        # - options - other options:
+        #   - :cookbook_version - when cookbooks are retrieved, grab this version for them.
+        #
         def initialize(root_name, chef_config, options = {})
           super("", nil)
           @chef_server_url = chef_config[:chef_server_url]
diff --git a/lib/chef/chef_fs/file_system/organization_invites_entry.rb b/lib/chef/chef_fs/file_system/organization_invites_entry.rb
index a83e058b77..cb26326050 100644
--- a/lib/chef/chef_fs/file_system/organization_invites_entry.rb
+++ b/lib/chef/chef_fs/file_system/organization_invites_entry.rb
@@ -5,10 +5,9 @@ class Chef
   module ChefFS
     module FileSystem
       # /organizations/NAME/invitations.json
-      # Represents the actual data at
-      # read:
+      # read data from:
       # - GET /organizations/NAME/association_requests
-      # write:
+      # write data to:
       # - remove from list: DELETE /organizations/NAME/association_requests/id
       # - add to list: POST /organizations/NAME/association_requests
       class OrganizationInvitesEntry < RestListEntry
diff --git a/lib/chef/chef_fs/file_system/organization_members_entry.rb b/lib/chef/chef_fs/file_system/organization_members_entry.rb
index c1151413f5..eb524d5ea2 100644
--- a/lib/chef/chef_fs/file_system/organization_members_entry.rb
+++ b/lib/chef/chef_fs/file_system/organization_members_entry.rb
@@ -5,10 +5,9 @@ class Chef
   module ChefFS
     module FileSystem
       # /organizations/NAME/members.json
-      # Represents the actual data at
-      # read:
+      # reads data from:
       # - GET /organizations/NAME/users
-      # write:
+      # writes data to:
       # - remove from list: DELETE /organizations/NAME/users/name
       # - add to list: POST /organizations/NAME/users/name
       class OrganizationMembersEntry < RestListEntry
diff --git a/lib/chef/chef_fs/parallelizer.rb b/lib/chef/chef_fs/parallelizer.rb
index f29a2deae7..116a626869 100644
--- a/lib/chef/chef_fs/parallelizer.rb
+++ b/lib/chef/chef_fs/parallelizer.rb
@@ -53,7 +53,6 @@ class Chef
       end
 
       def resize(to_threads, wait = true, timeout = nil)
-        to_threads = 0
         if to_threads < num_threads
           threads_to_stop = @threads[to_threads..num_threads-1]
           @threads = @threads.slice(0, to_threads)
@@ -90,7 +89,6 @@ class Chef
         begin
           while !@stop_thread[Thread.current]
             begin
-              puts "Got a task!"
               task = @tasks.pop
               task.call
             rescue
diff --git a/spec/integration/knife/delete_spec.rb b/spec/integration/knife/delete_spec.rb
index a9ba9dc3e1..e56469e102 100644
--- a/spec/integration/knife/delete_spec.rb
+++ b/spec/integration/knife/delete_spec.rb
@@ -962,7 +962,7 @@ EOM
     end
   end
 
-  when_the_chef_server "is in Enterprise mode", :focus, :osc_compat => false, :single_org => false do
+  when_the_chef_server "is in Enterprise mode", :osc_compat => false, :single_org => false do
     before do
       organization 'foo' do
         container 'x', {}