From a901b432e3183f310a7fe68718f4be425b2f5519 Mon Sep 17 00:00:00 2001
From: Steve Kemp <steve@steve.org.uk>
Date: Sat, 24 Nov 2012 17:03:01 +0000
Subject:   Updated comments considerably.

---
 lib/custodian/alertfactory.rb | 36 ++++++++++++++++++++++++------------
 1 file changed, 24 insertions(+), 12 deletions(-)

(limited to 'lib/custodian/alertfactory.rb')

diff --git a/lib/custodian/alertfactory.rb b/lib/custodian/alertfactory.rb
index 3df6233..39cf8cd 100644
--- a/lib/custodian/alertfactory.rb
+++ b/lib/custodian/alertfactory.rb
@@ -2,13 +2,11 @@
 
 #
 #
-# Base class for custodian alerters.
+# Base class for custodian notifiers.
 #
-# Each subclass will register themselves, via the call
-# to 'register_alert_type'.
+# Each subclass will register themselves, via the call to 'register_alert_type'.
 #
-# This class is a factory that will return the correct
-# derived class.
+# This class is a factory that will return the correct derived class.
 #
 #
 module Custodian
@@ -18,21 +16,31 @@ module Custodian
     #
     # The target for the alert.
     #
+    # The meaning of the target is notifier-specific.
+    # In the case of the smtp-notifier the target is the
+    # email address to notify, for example.
+    #
     attr_reader :target
 
+
+
     #
     # The subclasses we have.
     #
     @@subclasses = { }
 
 
+
+    #
+    # Create an notifier object, based upon name given to us.
     #
-    # Create an alerter object, based upon the type
+    # The "obj" here is the test-case that will be generating the
+    # raise/clear event.
     #
     def self.create( alert_type, obj )
 
-      raise ArgumentError, "The type of alerter to create cannot be nil" if ( alert_type.nil? )
-      raise ArgumentError, "The type of alerter to create must be a string" unless ( alert_type.kind_of? String )
+      raise ArgumentError, "The type of notifier to create cannot be nil" if ( alert_type.nil? )
+      raise ArgumentError, "The type of notifier to create must be a string" unless ( alert_type.kind_of? String )
 
       c = @@subclasses[alert_type]
       if c
@@ -44,7 +52,7 @@ module Custodian
 
 
     #
-    # Register a new test type - this must be called by our derived classes
+    # Register a new type of notifier - this must be called by our derived classes
     #
     def self.register_alert_type name
       @@subclasses[name] = self
@@ -52,7 +60,7 @@ module Custodian
 
 
     #
-    # Return an array of test-types we know about
+    # Return an array of the notifiers we know about.
     #
     # i.e. Derived classes that have registered themselves.
     #
@@ -84,13 +92,17 @@ module Custodian
     end
 
 
-
+    #
+    # Raise an alert.
+    #
     def raise
       puts "NOP"
     end
 
 
-
+    #
+    # Clear an alert.
+    #
     def clear
       puts "NOP"
     end
-- 
cgit v1.2.1