Add ChefFS rdoc, format existing ChefFS rdoc correctlyjk/doc

4 files changed, 148 insertions, 22 deletions

diff --git a/lib/chef/chef_fs/chef_fs_data_store.rb b/lib/chef/chef_fs/chef_fs_data_store.rb
index 09a66a9ab2..484ab07390 100644
--- a/lib/chef/chef_fs/chef_fs_data_store.rb
+++ b/lib/chef/chef_fs/chef_fs_data_store.rb
@@ -27,7 +27,61 @@ require 'fileutils'
 
 class Chef
   module ChefFS
+    #
+    # Translation layer between chef-zero's DataStore (a place where it expects
+    # files to be stored) and ChefFS (the user's repository directory layout).
+    #
+    # chef-zero expects the data store to store files *its* way--for example, it
+    # expects get("nodes/blah") to return the JSON text for the blah node, and
+    # it expects get("cookbooks/blah/1.0.0") to return the JSON definition of
+    # the blah cookbook version 1.0.0.
+    #
+    # The repository is defined the way the *user* wants their layout.  These
+    # two things are very similar in layout (for example, nodes are stored under
+    # the nodes/ directory and their filename is the name of the node).
+    #
+    # However, there are a few differences that make this more than just a raw
+    # file store:
+    #
+    # 1. Cookbooks are stored much differently.
+    #   - chef-zero places JSON text with the checksums for the cookbook at
+    #     /cookbooks/NAME/VERSION, and expects the JSON to contain URLs to the
+    #     actual files, which are stored elsewhere.
+    #   - The repository contains an actual directory with just the cookbook
+    #     files and a metadata.rb containing a version #.  There is no JSON to
+    #     be found.
+    #   - Further, if versioned_cookbooks is false, that directory is named
+    #     /cookbooks/NAME and only one version exists.  If versioned_cookbooks
+    #     is true, the directory is named /cookbooks/NAME-VERSION.
+    #   - Therefore, ChefFSDataStore calculates the cookbook JSON by looking at
+    #     the files in the cookbook and checksumming them, and reading metadata.rb
+    #     for the version and dependency information.
+    #   - ChefFSDataStore also modifies the cookbook file URLs so that they point
+    #     to /file_store/repo/<filename> (the path to the actual file under the
+    #     repository root).  For example, /file_store/repo/apache2/metadata.rb or
+    #     /file_store/repo/cookbooks/apache2/recipes/default.rb).
+    #
+    # 2. Sandboxes don't exist in the repository.
+    #   - ChefFSDataStore lets cookbooks be uploaded into a temporary memory
+    #     storage, and when the cookbook is committed, copies the files onto the
+    #     disk in the correct place (/cookbooks/apache2/recipes/default.rb).
+    # 3. Data bags:
+    #   - The Chef server expects data bags in /data/BAG/ITEM
+    #   - The repository stores data bags in /data_bags/BAG/ITEM
+    #
+    # 4. JSON filenames are generally NAME.json in the repository (e.g. /nodes/foo.json).
+    #
     class ChefFSDataStore
+      #
+      # Create a new ChefFSDataStore
+      #
+      # ==== Arguments
+      #
+      # [chef_fs]
+      #   A +ChefFS::FileSystem+ object representing the repository root.
+      #   Generally will be a +ChefFS::FileSystem::ChefRepositoryFileSystemRoot+
+      #   object, created from +ChefFS::Config.local_fs+.
+      #
       def initialize(chef_fs)
         @chef_fs = chef_fs
         @memory_store = ChefZero::DataStore::MemoryStore.new
diff --git a/lib/chef/chef_fs/config.rb b/lib/chef/chef_fs/config.rb
index ca273b2cca..fcad6c919f 100644
--- a/lib/chef/chef_fs/config.rb
+++ b/lib/chef/chef_fs/config.rb
@@ -22,9 +22,74 @@ require 'chef/chef_fs/path_utils'
 class Chef
   module ChefFS
     #
-    # Helpers to take Chef::Config and create chef_fs and local_fs from it
+    # Helpers to take Chef::Config and create chef_fs and local_fs (ChefFS
+    # objects representing the server and local repository, respectively).
     #
     class Config
+      #
+      # Create a new Config object which can produce a chef_fs and local_fs.
+      #
+      # ==== Arguments
+      #
+      # [chef_config]
+      #   A hash that looks suspiciously like +Chef::Config+.  These hash keys
+      #   include:
+      #
+      #   :chef_repo_path::
+      #     The root where all local chef object data is stored.  Mirrors
+      #     +Chef::Config.chef_repo_path+
+      #   :cookbook_path, node_path, ...::
+      #     Paths to cookbooks/, nodes/, data_bags/, etc.  Mirrors
+      #     +Chef::Config.cookbook_path+, etc.  Defaults to
+      #     +<chef_repo_path>/cookbooks+, etc.
+      #   :repo_mode::
+      #     The directory format on disk.  'everything', 'hosted_everything' and
+      #     'static'.  Default: autodetected based on whether the URL has
+      #     "/organizations/NAME."
+      #   :versioned_cookbooks::
+      #     If true, the repository contains cookbooks with versions in their
+      #     name (apache2-1.0.0).  If false, the repository just has one version
+      #     of each cookbook and the directory has the cookbook name (apache2).
+      #     Default: +false+
+      #   :chef_server_url::
+      #     The URL to the Chef server, e.g. https://api.opscode.com/organizations/foo.
+      #     Used as the server for the remote chef_fs, and to "guess" repo_mode
+      #     if not specified.
+      #   :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.
+      #   :versioned_cookbooks:: Whether or not to include versions in cookbook names
+      #
+      # [cwd]
+      #   The current working directory to base relative Chef paths from.
+      #   Defaults to +Dir.pwd+.
+      #
+      # [options]
+      #   A hash of other, not-suspiciously-like-chef-config options:
+      #   :cookbook_version::
+      #     When downloading cookbooks, download this cookbook version instead
+      #     of the latest.
+      #
+      # [ui]
+      #   The object to print output to, with "output", "warn" and "error"
+      #   (looks a little like a Chef::Knife::UI object, obtainable from
+      #   Chef::Knife.ui).
+      #
+      # ==== Example
+      #
+      #   require 'chef/chef_fs/config'
+      #   config = Chef::ChefFS::Config.new
+      #   config.chef_fs.child('cookbooks').children.each do |cookbook|
+      #     puts "Cookbook on server: #{cookbook.name}"
+      #   end
+      #   config.local_fs.child('cookbooks').children.each do |cookbook|
+      #     puts "Local cookbook: #{cookbook.name}"
+      #   end
+      #
       def initialize(chef_config = Chef::Config, cwd = Dir.pwd, options = {}, ui = nil)
         @chef_config = chef_config
         @cwd = cwd
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 050da60389..ac272d4c1a 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
@@ -42,15 +42,17 @@ class Chef
         # 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.
-        # - chef_config - a hash of options that looks suspiciously like the ones
+        # [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.
+        # [chef_config] - a hash of options that looks suspiciously like the ones
         #   stored in Chef::Config, containing at least these keys:
-        #   - :versioned_cookbooks - whether to include versions in cookbook names
+        #   :versioned_cookbooks:: whether to include versions in cookbook names
         def initialize(child_paths, root_paths=[], chef_config=Chef::Config)
           super("", nil)
           @child_paths = child_paths
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 61a224c307..370308ee0a 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
@@ -46,19 +46,24 @@ class Chef
         #
         # == 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.
-        #   - :versioned_cookbooks - whether or not to include versions in cookbook names
-        # - options - other options:
-        #   - :cookbook_version - when cookbooks are retrieved, grab this version for them.
+        # [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.
+        #   :versioned_cookbooks:: whether or not to include versions in cookbook names
+        # [options]
+        #   Other options:
+        #   :cookbook_version:: when cookbooks are retrieved, grab this version for them.
+        #   :freeze:: freeze cookbooks on upload
         #
         def initialize(root_name, chef_config, options = {})
           super("", nil)