Big documentation update.

1 files changed, 45 insertions, 6 deletions

diff --git a/lib/mauve/alert_changed.rb b/lib/mauve/alert_changed.rb
index ac864a0..c36c4c8 100644
--- a/lib/mauve/alert_changed.rb
+++ b/lib/mauve/alert_changed.rb
@@ -3,6 +3,9 @@ require 'mauve/datamapper'
 require 'log4r'
 
 module Mauve
+  #
+  # Class to record changes to alerts.  Also responsible for keeping records for reminders.
+  #
   class AlertChanged
     include DataMapper::Resource
     
@@ -17,26 +20,37 @@ module Mauve
     property :level, String, :required  => true
     property :update_type, String, :required  => true
     property :remind_at, Time
-    # property :updated_at, Time, :required => true
+    
+    belongs_to :alert
+    
 
+    # @return [String]
     def to_s
       "#<AlertChanged #{id}: alert_id #{alert_id}, for #{person}, update_type #{update_type}>"
     end
 
-    belongs_to :alert
-    
+    # @deprecated I don't think was_relevant is used any more.
+    #
     def was_relevant=(value)
       attribute_set(:was_relevant, value)
     end
 
+    # The time this object was last updated
+    # 
+    # @return [Time]
     def updated_at
       self.at
     end
     
+    # Set the time this object was last updated
+    #
+    # @param [Time] t
+    # @return [Time]
     def updated_at=(t)
       self.at = t
     end
 
+    # @return [Log4r::Logger]
     def logger
      Log4r::Logger.new self.class.to_s
     end
@@ -44,6 +58,7 @@ module Mauve
     # Sends a reminder about this alert state change, or forget about it if
     # the alert has been acknowledged
     #
+    # @return [Boolean] indicating successful update of the AlertChanged object
     def remind
       unless alert.is_a?(Alert)
         logger.info "#{self.inspect} lost alert #{alert_id}.  Killing self."
@@ -83,28 +98,52 @@ module Mauve
       save
     end
     
-    def due_at # mimic interface from Alert
+    # The time this AlertChanged should next be polled at, or nil.  Mimics
+    # interaface from Alert.
+    #
+    # @return [Time, NilClass]
+    def due_at 
       remind_at ? remind_at : nil
     end
     
+    # Sends a reminder, if needed. Mimics interaface from Alert.
+    #
+    # @return [Boolean] showing polling was successful
     def poll # mimic interface from Alert
       logger.debug("Polling #{self.to_s}")
-      remind if remind_at.is_a?(Time) and remind_at <= Time.now
+
+      if remind_at.is_a?(Time) and remind_at <= Time.now
+        remind 
+      else
+        true
+      end
     end
 
+    # The AlertGroup for this object
+    #
+    # @return [Mauve::AlertGroup]
     def alert_group
       alert.alert_group
     end
     
     class << self
+      # Finds the next reminder due, or nil if nothing due.
+      #
+      # @return [Mauve::AlertChanged, NilClass]
       def next_reminder
         first(:remind_at.not => nil, :order => [:remind_at])
       end
       
-      def find_next_with_event # mimic interface from Alert
+      # Finds the next event due.  Mimics interface from Alert.
+      #
+      # @return [Mauve::AlertChanged, NilClass]
+      def find_next_with_event 
         next_reminder
       end
 
+      # @deprecated  I don't think this is used any more.
+      #
+      # @return [Array]
       def all_overdue(at = Time.now)
         all(:remind_at.not => nil, :remind_at.lt => at, :order => [:remind_at]).to_a
       end