Documentation

lib/hydra/master.rb

@@ -1,5 +1,15 @@
 module Hydra #:nodoc:
+  # Hydra class responsible for delegate work down to workers.
+  #
+  # The Master is run once for any given testing session.
   class Master
+    # Create a new Master
+    #
+    # Options:
+    # * :files
+    #   * An array of test files to be run. These should be relative paths from
+    #     the root of the project, since they may be run on different machines
+    #     which may have different paths.
     def initialize(opts = { })
       @files = opts.fetch(:files) { [] }
       @workers = []
@@ -10,7 +20,8 @@ module Hydra #:nodoc:
 
     # Message handling
     
-    # Send a file down to a worker
+    # Send a file down to a worker. If there are no more files, this will shut the
+    # worker down.
     def send_file(worker)
       f = @files.pop
       if f

lib/hydra/message/runner_messages.rb

@@ -11,6 +11,7 @@ module Hydra #:nodoc:
       # Message telling the Runner to run a file
       # TODO: move to worker
       class RunFile < Hydra::Message
+        # The file that should be run
         attr_accessor :file
         def serialize #:nodoc:
           super(:file => @file)
@@ -22,7 +23,9 @@ module Hydra #:nodoc:
 
       # Message for the Runner to respond with its results
       class Results < Hydra::Message
+        # The output from running the test
         attr_accessor :output
+        # The file that was run
         attr_accessor :file
         def serialize #:nodoc:
           super(:output => @output, :file => @file)
@@ -42,9 +45,9 @@ module Hydra #:nodoc:
       
       # Message a runner sends to a worker to verify the connection
       class Ping < Hydra::Message
+        def handle(worker, runner) #:nodoc:
           # We don't do anything to handle a ping. It's just to test
           # the connectivity of the IO
-        def handle(worker, runner)
         end
       end
     end

lib/hydra/message/worker_messages.rb

@@ -3,7 +3,7 @@ module Hydra #:nodoc:
     module Worker #:nodoc:
       # Message indicating that a worker needs a file to delegate to a runner
       class RequestFile < Hydra::Message
-        def handle(master, worker)
+        def handle(master, worker) #:nodoc:
           master.send_file(worker)
         end
       end
@@ -11,14 +11,14 @@ module Hydra #:nodoc:
       # Message telling a worker to delegate a file to a runner
       # TODO: move to master messages
       class RunFile < Hydra::Messages::Runner::RunFile
-        def handle(worker)
+        def handle(worker) #:nodoc:
           worker.delegate_file(self)
         end
       end
 
       # Message relaying the results of a worker up to the master
       class Results < Hydra::Messages::Runner::Results
-        def handle(master, worker)
+        def handle(master, worker) #:nodoc:
           master.send_file(worker)
         end
       end
@@ -26,16 +26,16 @@ module Hydra #:nodoc:
       # Message telling the worker to shut down.
       # TODO: move to master
       class Shutdown < Hydra::Messages::Runner::Shutdown
-        def handle(worker)
+        def handle(worker) #:nodoc:
           worker.shutdown
         end
       end
 
       # Message a worker sends to a master to verify the connection
       class Ping < Hydra::Message
+        def handle(master, worker) #:nodoc:
           # We don't do anything to handle a ping. It's just to test
           # the connectivity of the IO
-        def handle(master, worker)
         end
       end
     end

lib/hydra/messaging_io.rb

@@ -37,6 +37,7 @@ module Hydra #:nodoc:
     # For example, if you tried to write a string, it would fail,
     # because the string is not a message.
     class UnprocessableMessage < RuntimeError
+      # Custom error message
       attr_accessor :message
     end
   end

lib/hydra/runner.rb

@@ -1,5 +1,11 @@
 module Hydra #:nodoc:
-  # Hydra class responsible for running test files
+  # Hydra class responsible for running test files.
+  #
+  # The Runner is never run directly by a user. Runners are created by a
+  # Worker to run test files.
+  #
+  # The general convention is to have one Runner for each logical processor
+  # of a machine.
   class Runner
     # Boot up a runner. It takes an IO object (generally a pipe from its
     # parent) to send it messages on which files to execute.

lib/hydra/worker.rb

@@ -1,5 +1,11 @@
 module Hydra #:nodoc:
   # Hydra class responsible to dispatching runners and communicating with the master.
+  #
+  # The Worker is never run directly by a user. Workers are created by a
+  # Master to delegate to Runners.
+  #
+  # The general convention is to have one Worker per machine on a distributed
+  # network.
   class Worker
     # Create a new worker.
     # * io: The IO object to use to communicate with the master