verify.rb in mitchellh-sprinkle-0.1.6

- old
+ new

@@ -1,18 +1,77 @@
 module Sprinkle
+  # = Verification Methods
+  #
+  # As documented in Sprinkle::Package, you may define a block on a package
+  # which verifies that a package was installed correctly. If this verification
+  # block fails, Sprinkle will stop the script gracefully, raising the error.
+  # 
+  # In addition to checking post install if it was successfully, verification
+  # blocks are also ran before an install to see if a package is <em>already</em>
+  # installed. If this is the case, the package is skipped and Sprinkle continues
+  # with the next package. This behavior can be overriden by setting the -f flag on
+  # the sprinkle script or setting Sprinkle::OPTIONS[:force] to true if you're
+  # using sprinkle programmatically. 
+  #
+  # == An Example
+  #
+  # The following verifies that rails was installed correctly be checking to see
+  # if the 'rails' command is available on the command line:
+  #
+  #   package :rails do
+  #     gem 'rails'
+  #     
+  #     verify do
+  #       has_executable 'rails'
+  #     end
+  #   end
+  #
+  # == Available Verifiers
+  #
+  # There are a variety of available methods for use in the verification block.
+  # The standard methods are defined in the Sprinkle::Verifiers module, so see
+  # their corresponding documentation.
+  #
+  # == Custom Verifiers
+  # 
+  # If you feel that the built-in verifiers do not offer a certain aspect of
+  # verification which you need, you may create your own verifier! Simply wrap
+  # any method in a module which you want to use:
+  #
+  #   module MagicBeansVerifier
+  #     def has_magic_beans(sauce)
+  #       @commands << '[ -z "`echo $' + sauce + '`"]'
+  #     end
+  #   end
+  #
+  # The method can append as many commands as it wishes to the @commands array. 
+  # These commands will be run on the remote server and <b>MUST</b> give an
+  # exit status of 0 if successful or other if unsuccessful.
+  #
+  # To register your verifier, call the register method on Sprinkle::Verify:
+  #
+  #   Sprinle::Verify.register(MagicBeansVerifier)
+  #
+  # And now you may use it like any other verifier:
+  #
+  #   package :magic_beans do
+  #     gem 'magic_beans'
+  #     
+  #     verify { has_magic_beans('ranch') }
+  #   end
   class Verify
     include Sprinkle::Configurable
-    attr_accessor :package, :description, :commands
+    attr_accessor :package, :description, :commands #:nodoc:
     
     class <<self
       # Register a verification module
       def register(new_module)
         class_eval { include new_module }
       end
     end
     
-    def initialize(package, description = '', &block)
+    def initialize(package, description = '', &block) #:nodoc:
       raise 'Verify requires a block.' unless block
       
       @package = package
       @description = description
       @commands = []
@@ -20,11 +79,11 @@
       @options[:padding] = 4
       
       self.instance_eval(&block)
     end
     
-    def process(roles, pre = false)
+    def process(roles, pre = false) #:nodoc:
       assert_delivery
       
       description = @description.empty? ? @package.name : @description
       
       if logger.debug?
@@ -40,10 +99,10 @@
         end
       end
     end
   end
   
-  class VerificationFailed < Exception
+  class VerificationFailed < Exception #:nodoc:
     attr_accessor :package, :description
     
     def initialize(package, description)
       super("Verifying #{package.name}#{description} failed.")
       
\ No newline at end of file