application.rb in plow-1.0.0

- old
+ new

@@ -1,11 +1,37 @@
 # encoding: UTF-8
 require 'plow/generator'
 
 class Plow
+  # It's probably no surprise that `Plow::Application` is an **application** class.
+  #
+  # With a single public method, `.launch`, it has the distinct honor of being the point of
+  # execution for the library.  As described further in the documentation, it designed to
+  # accept and parse raw command-line arguments (i.e. the `ARGV` constant).
+  #
+  # @see Plow::Application.launch
   class Application
     class << self
+      # The starting point of executation for the Plow library.  The procedure for launching the 
+      # `Plow::Application` is as follows:
+      #
+      # 1. Output a version stamp.
+      # 2. Ensure at least 2 arguments are provided or aborting execution with a usage message.
+      # 3. Parse the user-supplied arguments.
+      # 4. Start a new `Plow::Generator` while handling any library specific exceptions raised.
+      #
+      # @example A simple executable file (assume a working Ruby $LOAD_PATH)
+      #   #!/usr/bin/env ruby1.9
+      #   require 'plow'
+      #   Plow::Application.launch(*ARGV)
+      #
+      # @param [Array] *arguments A splatted `Array` of user-specified, command-line arguments.
+      #   At least 2 arguments must be provided.
+      # @return [Number] Success returns 0, while failure results in any raised `Exception`. :(
+      # @raise [SystemExit] Raised when a critical, library-specific exception is rescued and
+      #   executation must be terminiated.
+      # @see http://www.ruby-doc.org/ruby-1.9/classes/SystemExit.html
       def launch(*arguments)
         puts version_stamp
         
         if arguments.length < 2
           abort <<-MESSAGE
@@ -56,11 +82,17 @@
         end
       end
       
       private
       
+      # Similar to a time stamp, this will return a version stamp of the Plow library containing
+      # the version number along with the copyright and license details.
+      #
+      # @return [String] Version stamp
+      # @example Sample version stamp
+      #   Plow 1.0.0. Copyright (c) 2009 Ryan Sobol. Licensed under the MIT license.
       def version_stamp
-        "Plow v#{Plow::VERSION}. Copyright (c) 2009 Ryan Sobol. Licensed under the MIT license."
+        "Plow #{Plow::VERSION}. Copyright (c) 2009 Ryan Sobol. Licensed under the MIT license."
       end
     end
   end
 end
\ No newline at end of file