From bf738d4db54eac5813dd303bcf0744789f414cce Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
Date: Thu, 4 Mar 2010 20:58:50 -0800
Subject: [PATCH] Developer documentation for box actions

---
 lib/vagrant/actions/box/add.rb       | 8 +++++++-
 lib/vagrant/actions/box/destroy.rb   | 2 ++
 lib/vagrant/actions/box/download.rb  | 6 +++++-
 lib/vagrant/actions/box/unpackage.rb | 2 ++
 4 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/lib/vagrant/actions/box/add.rb b/lib/vagrant/actions/box/add.rb
index 426a68e77..c1107241d 100644
--- a/lib/vagrant/actions/box/add.rb
+++ b/lib/vagrant/actions/box/add.rb
@@ -1,12 +1,18 @@
 module Vagrant
   module Actions
     module Box
+      # A meta-action which adds a box by downloading and unpackaging it.
+      # This action downloads and unpackages a box with a given URI. This
+      # is a _meta action_, meaning it simply adds more actions to the
+      # action chain, and those actions do the work.
+      #
+      # This is the action called by {Box#add}.
       class Add < Base
         def prepare
           if File.exists?(@runner.directory)
             raise ActionException.new("A box with the name '#{@runner.name}' already exists, please use another name or use `vagrant box remove #{@runner.name}`")
           end
-          
+
           @runner.add_action(Download)
           @runner.add_action(Unpackage)
         end
diff --git a/lib/vagrant/actions/box/destroy.rb b/lib/vagrant/actions/box/destroy.rb
index a6db3fdb8..ff9d6bd04 100644
--- a/lib/vagrant/actions/box/destroy.rb
+++ b/lib/vagrant/actions/box/destroy.rb
@@ -1,6 +1,8 @@
 module Vagrant
   module Actions
     module Box
+      # Action to destroy a box. This action is not reversible and expects
+      # to be called by a {Box} object.
       class Destroy < Base
         def execute!
           logger.info "Deleting box directory..."
diff --git a/lib/vagrant/actions/box/download.rb b/lib/vagrant/actions/box/download.rb
index 0aea26530..dfea09410 100644
--- a/lib/vagrant/actions/box/download.rb
+++ b/lib/vagrant/actions/box/download.rb
@@ -2,7 +2,11 @@ module Vagrant
   module Actions
     module Box
       # An action which acts on a box by downloading the box file from
-      # the given URI into a temporary location.
+      # the given URI into a temporary location. This action parses a
+      # given URI and handles downloading it via one of the many Vagrant
+      # downloads (such as {Vagrant::Downloaders::File}).
+      #
+      # This action cleans itself up by removing the downloaded box file.
       class Download < Base
         BASENAME = "box"
         BUFFERSIZE = 1048576 # 1 MB
diff --git a/lib/vagrant/actions/box/unpackage.rb b/lib/vagrant/actions/box/unpackage.rb
index 67a3c65d0..7b257789a 100644
--- a/lib/vagrant/actions/box/unpackage.rb
+++ b/lib/vagrant/actions/box/unpackage.rb
@@ -1,6 +1,8 @@
 module Vagrant
   module Actions
     module Box
+      # This action unpackages a downloaded box file into its final
+      # box destination within the vagrant home folder.
       class Unpackage < Base
         TAR_OPTIONS = [File::RDONLY, 0644, Tar::GNU]