More documentation and fixed some YARD warnings

lib/vagrant/action.rb

@@ -1,13 +1,56 @@
 module Vagrant
   # Manages action running and registration. Every Vagrant environment
   # has an instance of {Action} to allow for running in the context of
-  # the environment.
+  # the environment, which is accessible at {Environment#actions}. Actions
+  # are the foundation of most functionality in Vagrant, and are implemented
+  # architecturally as "middleware."
+  #
+  # # Registering an Action
+  #
+  # The main benefits of registering an action is the ability to retrieve and
+  # modify that registered action, as well as easily run the action. An example
+  # of registering an action is shown below, with a simple middleware which just
+  # outputs to `STDOUT`:
+  #
+  #     class StdoutMiddleware
+  #       def initialize(app, env)
+  #         @app = app
+  #       end
+  #
+  #       def call(env)
+  #         puts "HI!"
+  #         @app.call(env)
+  #       end
+  #     end
+  #
+  #     Vagrant::Action.register(:stdout, StdoutMiddleware)
+  #
+  # Then to run a registered action, assuming `env` is a loaded {Environment}:
+  #
+  #     env.actions.run(:stdout)
+  #
+  # Or to retrieve the action class for any reason:
+  #
+  #     Vagrant::Action[:stdout]
+  #
+  # # Running an Action
+  #
+  # There are various built-in registered actions such as `start`, `stop`, `up`,
+  # etc. Actions are built to be run in the context of an environment, so use
+  # {Environment#actions} to run all actions. Then simply call {#run}:
+  #
+  #     env.actions.run(:name)
+  #
+  # Where `:name` is the name of the registered action.
+  #
   class Action
     include Util
     @@reported_interrupt = false
 
     class << self
       # Returns the list of registered actions.
+      #
+      # @return [Array]
       def actions
         @actions ||= {}
       end
@@ -18,12 +61,14 @@ module Vagrant
       #
       # @param [Symbol] key
       def register(key, callable)
-        actions[key] = callable
+        actions[key.to_sym] = callable
       end
 
       # Retrieves a registered action by key.
+      #
+      # @param [Symbol] key
       def [](key)
-        actions[key]
+        actions[key.to_sym]
       end
     end
 
@@ -42,6 +87,8 @@ module Vagrant
     # If a symbol is given as the `callable` parameter, then it is looked
     # up in the registered actions list which are registered with {register}.
     #
+    # Any options given are injected into the environment hash.
+    #
     # @param [Object] callable An object which responds to `call`.
     def run(callable, options=nil)
       callable = Builder.new.use(callable) if callable.kind_of?(Class)

lib/vagrant/action/environment.rb

@@ -31,13 +31,17 @@ module Vagrant
       end
 
       # Marks an environment as interrupted (by an outside signal or
-      # anything)
+      # anything). This will trigger any middleware sequences using this
+      # environment to halt. This is automatically set by {Action} when
+      # a SIGINT is captured.
       def interrupt!
         @interrupted = true
       end
 
       # Returns a boolean denoting if environment has been interrupted
       # with a SIGINT.
+      #
+      # @return [Bool]
       def interrupted?
         !!@interrupted
       end

lib/vagrant/action/warden.rb

@@ -2,10 +2,13 @@ module Vagrant
   class Action
     # The action warden is a middleware which injects itself between
     # every other middleware, watching for exceptions which are raised
-    # and performing proper cleanup on every action by calling the {#recover}
+    # and performing proper cleanup on every action by calling the `recover`
     # method. The warden therefore allows middlewares to not worry about
     # exceptional events, and by providing a simple callback, can clean up
     # in any erroneous case.
+    #
+    # Except for those who are curious about the internal workings of Vagrant,
+    # Warden will "just work" behind the scenes.
     class Warden
       attr_accessor :actions, :stack
 
@@ -33,6 +36,9 @@ module Vagrant
         end
       end
 
+      # Begins the recovery sequence for all middlewares which have run.
+      # It does this by calling `recover` (if it exists) on each middleware
+      # which has already run, in reverse order.
       def begin_rescue(env)
         @stack.each do |act|
           act.recover(env) if act.respond_to?(:recover)
@@ -43,6 +49,8 @@ module Vagrant
         @stack.clear
       end
 
+      # A somewhat confusing function which simply initializes each
+      # middleware properly to call the next middleware in the sequence.
       def finalize_action(action, env)
         klass, args, block = action
 

lib/vagrant/box_collection.rb

@@ -1,7 +1,16 @@
 module Vagrant
   # Represents a collection of boxes, providing helpful methods for
-  # finding boxes.
+  # finding boxes. An instance of this is returned by {Environment#boxes}.
+  #
+  # # Finding a Box
+  #
+  # To find a box, use the {#find} method with the name of the box. The name
+  # is an exact match search.
+  #
+  #     env.boxes.find("base") # => #<Vagrant::Box>
+  #
   class BoxCollection < Array
+    # The environment this box collection belongs to
     attr_reader :env
 
     def initialize(env)

lib/vagrant/data_store.rb

@@ -3,8 +3,15 @@ module Vagrant
   # as JSON in a local file which is specified in the initializer.
   # The data store itself is accessed via typical hash accessors: `[]`
   # and `[]=`. If a key is set to `nil`, then it is removed from the
-  # datastore. The data store is only updated on disk when {commit}
+  # datastore. The data store is only updated on disk when {#commit}
   # is called on the data store itself.
+  #
+  # The data store is a hash with indifferent access, meaning that
+  # while all keys are persisted as strings in the JSON, you can access
+  # them back as either symbols or strings. Note that this is only true
+  # for the top-level data store. As soon as you set a hash inside the
+  # data store, unless you explicitly use a {Util::HashWithIndifferentAccess},
+  # it will be a regular hash.
   class DataStore < Util::HashWithIndifferentAccess
     attr_reader :file_path
 
@@ -27,6 +34,7 @@ module Vagrant
       clean_nil_and_empties
 
       if empty?
+        # Delete the file since an empty data store is not useful
         File.delete(file_path) if File.file?(file_path)
       else
         File.open(file_path, "w") { |f| f.write(to_json) }

lib/vagrant/environment.rb

@@ -233,7 +233,7 @@ module Vagrant
       self
     end
 
-    # Loads this environment's configuration and stores it in the {config}
+    # Loads this environment's configuration and stores it in the {#config}
     # variable. The configuration loaded by this method is specified to
     # this environment, meaning that it will use the given root directory
     # to load the Vagrantfile into that context.

lib/vagrant/hosts/base.rb

@@ -45,7 +45,7 @@ module Vagrant
       end
 
       # Initialzes a new host. This method shouldn't be called directly,
-      # typically, since it will be called by {Environment#load_host!}
+      # typically, since it will be called by {Environment#load!}.
       #
       # @param [Environment] env
       def initialize(env)