Big documentation update.

36 files changed, 1669 insertions, 522 deletions

diff --git a/lib/mauve/alert.rb b/lib/mauve/alert.rb
index fa2ce65..25cee54 100644
--- a/lib/mauve/alert.rb
+++ b/lib/mauve/alert.rb
@@ -6,6 +6,10 @@ require 'mauve/source_list'
 require 'sanitize'
 
 module Mauve
+  #
+  # This is a view of the Alert table, which allows easy finding of the next
+  # alert due to trigger.
+  #
   class AlertEarliestDate
  
     include DataMapper::Resource
@@ -52,9 +56,14 @@ module Mauve
     end
 
   end
-  
+ 
+  #
+  # Woo! An alert.
+  #
   class Alert
+    # @deprecated Not used anymore?
     def bytesize; 99; end
+    # @deprecated Not used anymore?
     def size; 99; end
     
     include DataMapper::Resource
@@ -89,31 +98,23 @@ module Mauve
 
     validates_with_method :check_dates
     
+    default_scope(:default).update(:order => [:source, :importance])
+    
+    # @return [String]
     def to_s 
       "#<Alert #{id}, alert_id #{alert_id}, source #{source}>"
     end
 
-    #
-    # This is to stop datamapper inserting duff dates into the database.
-    #
-    def check_dates
-      bad_dates = self.attributes.find_all do |key, value|
-        value.is_a?(Time) and (value < (Time.now - 3650.days) or value > (Time.now + 3650.days))
-      end
-
-      if bad_dates.empty?
-        true
-      else
-        [ false, "The dates "+bad_dates.collect{|k,v| "#{v.to_s} (#{k})"}.join(", ")+" are invalid." ]
-      end
-    end
-
-    default_scope(:default).update(:order => [:source, :importance])
-   
+    # @return [Log4r::Logger] the logger instance.
     def logger
       @logger ||= self.class.logger
     end
 
+    # @deprecated Not sure if this is used any more.
+    #
+    # @param [Integer] Seconds 
+    #
+    # @return [String]
     def time_relative(secs)
       secs = secs.to_i.abs
       case secs
@@ -127,45 +128,63 @@ module Mauve
     end
 
     #
-    # AlertGroup.matches must always return a an array of groups.
-    #
+    # @return [Mauve::AlertGroup] The first matching AlertGroup for this alert
     def alert_group
       @alert_group ||= AlertGroup.matches(self).first
     end
 
-    #
     # Pick out the source lists that match this alert by subject.
     #
+    # @return [Array] All the SourceList matches
     def source_lists
       Mauve::Configuration.current.source_lists.select{|label, list| list.includes?(self.subject)}.collect{|sl| sl.first}
     end
 
-    def in_source_list?(g)
-      list = Mauve::Configuration.current.source_lists[g]
+    # Checks to see if included in a named source list
+    #
+    # @param [String] listname
+    # @return [Boolean]
+    def in_source_list?(listname)
+      list = Mauve::Configuration.current.source_lists[listname]
+      return false unless list.is_a?(SourceList)
       list.includes?(self.subject)
     end
 
+    # Returns the alert level 
     #
-    #
-    #
+    # @return [Symbol] The alert level, as per its AlertGroup.
     def level
       @level ||= self.alert_group.level
     end
   
+    # An array used to sort compare
+    # 
+    # @return [Array] 
     def sort_tuple
       [AlertGroup::LEVELS.index(self.level), (self.raised_at || self.cleared_at || Time.now)]
     end
 
+    # Comparator.  Uses sort_tuple to compare with another alert
+    #
+    # @param [Mauve::Alert] other Other alert
+    #
+    # @return [Integer]
     def <=>(other)
       other.sort_tuple <=> self.sort_tuple
     end
  
+    # The alert subject
+    #
+    # @return [String]
     def subject; attribute_get(:subject) || attribute_get(:source) || "not set" ; end
+
+    # The alert detail
+    # 
+    # @return [String]
     def detail;  attribute_get(:detail)  || "_No detail set._" ; end
  
     protected
 
-    #
     # This cleans the HTML before saving.
     #
     def do_sanitize_html
@@ -185,8 +204,21 @@ module Mauve
         attribute_set(key, Alert.clean_html(val))
       end
     end
-
+    
+    # This is to stop datamapper inserting duff dates into the database.
     #
+    def check_dates
+      bad_dates = self.attributes.find_all do |key, value|
+        value.is_a?(Time) and (value < (Time.now - 3650.days) or value > (Time.now + 3650.days))
+      end
+
+      if bad_dates.empty?
+        true
+      else
+        [ false, "The dates "+bad_dates.collect{|k,v| "#{v.to_s} (#{k})"}.join(", ")+" are invalid." ]
+      end
+    end
+
     # This allows us to take a copy of the changes before we save.
     #
     def take_copy_of_changes
@@ -196,9 +228,9 @@ module Mauve
       end
     end
 
-    #
     # This sends notifications.  It is called after each save.
     #
+    # @return [Boolean] 
     def notify_if_needed
       #
       # Make sure we don't barf
@@ -243,20 +275,33 @@ module Mauve
       true
     end
 
+    # Remove all history for an alert, when an alert is destroyed.
+    #
+    #
     def destroy_associations
       AlertHistory.all(:alert_id => self.id).destroy
     end
 
     public
     
+    # Send a notification for this alert.
+    #
+    # @return [Boolean] Showing if an alert has been sent.
     def notify
       if self.alert_group.nil?
         logger.warn "Could not notify for #{self} since there are no matching alert groups"
+        false
       else
         self.alert_group.notify(self)
       end
     end
 
+    # Acknowledge an alert
+    #
+    # @param [Mauve::Person] person The person acknowledging the alert
+    # @param [Time] ack_until The time when the alert should unacknowledge
+    #
+    # @return [Boolean] showing the acknowledgment has been successful
     def acknowledge!(person, ack_until = Time.now+3600)
       raise ArgumentError unless person.is_a?(Person)
       raise ArgumentError unless ack_until.is_a?(Time)
@@ -281,6 +326,9 @@ module Mauve
       end
     end
     
+    # Unacknowledge an alert
+    #
+    # @return [Boolean] showing the unacknowledgment has been successful
     def unacknowledge!
       self.acknowledged_by = nil
       self.acknowledged_at = nil
@@ -294,7 +342,12 @@ module Mauve
         true
       end
     end
-    
+   
+    # Raise an alert at a specified time
+    #    
+    # @param [Time] at The time at which the alert should be raised.
+    #
+    # @return [Boolean] showing the raise has been successful
     def raise!(at = Time.now)
       #
       # OK if this is an alert updated in the last run, do not raise, just postpone.
@@ -334,6 +387,11 @@ module Mauve
       end
     end
     
+    # Clear an alert at a specified time
+    #    
+    # @param [Time] at The time at which the alert should be cleared.
+    #
+    # @return [Boolean] showing the clear has been successful
     def clear!(at = Time.now)
       #
       # Postpone clearance if we're in the sleep period.
@@ -379,47 +437,57 @@ module Mauve
       end
     end
       
-    # Returns the time at which a timer loop should call poll_event to either
-    # raise, clear or unacknowldge this event.
-    # 
+    # The next time this alert should be polled, either to raise, clear, or
+    # unacknowledge, or nil if nothing is due.
+    #
+    # @return [Time, NilClass]
     def due_at
       [will_clear_at, will_raise_at, will_unacknowledge_at].compact.sort.first
     end
     
+    # Polls the alert, raising or clearing as needed.
+    #
+    # @return [Boolean] showing the poll was successful
     def poll
       logger.debug("Polling #{self.to_s}")
-      raise! if (will_unacknowledge_at and will_unacknowledge_at <= Time.now) or
+      if (will_unacknowledge_at and will_unacknowledge_at <= Time.now) or
         (will_raise_at and will_raise_at <= Time.now)
-      clear! if will_clear_at && will_clear_at <= Time.now
+        raise!
+      elsif will_clear_at && will_clear_at <= Time.now
+        clear!
+      else
+        true
+      end
     end
 
 
+    # Is the alert raised?
     #
-    # Tests to see if an alert is raised/acknowledged given a certain set of
-    # dates/times.
-    #
-    #
-
+    # @return [Boolean]
     def raised?
       !raised_at.nil? and (cleared_at.nil? or raised_at > cleared_at)
     end
 
+    # Is the alert acknowledged?
+    #
+    # @return [Boolean]
     def acknowledged?
       !acknowledged_at.nil?
     end
 
+    # Is the alert cleared? Cleared is just the opposite of raised.
     #
-    # Cleared is just the opposite of raised.
-    #
+    # @return [Boolean]
     def cleared?
       !raised?
     end
  
     class << self
     
+      # Removes HTML from a string
       #
-      # Utility methods to clean/remove html
-      #
+      # @param [String] txt String to clean
+      # @return [String]
       def remove_html(txt)
         Sanitize.clean(
           txt.to_s,
@@ -427,6 +495,10 @@ module Mauve
         )
       end
 
+      # Cleans HTML in a string, removing dangerous elements/contents.
+      #
+      # @param [String] txt String to clean
+      # @return [String]
       def clean_html(txt)
         Sanitize.clean(
           txt.to_s,
@@ -434,22 +506,30 @@ module Mauve
         )
       end
     
+      # All alerts currently raised
       #
-      # Find stuff
-      #
-      #
+      # @return [Array]
       def all_raised
         all(:raised_at.not => nil, :order => [:raised_at.asc]) & (all(:cleared_at => nil) | all(:raised_at.gte => :cleared_at))
       end
       
+      # All alerts currently raised and unacknowledged
+      #
+      # @return [Array]
       def all_unacknowledged
         all_raised - all_acknowledged
       end
 
+      # All alerts currently acknowledged
+      #
+      # @return [Array]
       def all_acknowledged
         all(:acknowledged_at.not => nil)
       end
 
+      # All alerts currently cleared
+      #
+      # @return [Array]
       def all_cleared
         all - all_raised - all_acknowledged
       end
@@ -469,24 +549,31 @@ module Mauve
         return hash
       end
 
-      # 
-      # Returns the next Alert that will have a timed action due on it, or nil
-      # if none are pending.
+      # Find the next Alert that will have a timed action due on it, or nil if
+      # none are pending.
       #
+      # @return [Mauve::Alert, Nilclass]
       def find_next_with_event
         earliest_alert = AlertEarliestDate.first(:order => [:earliest])
         earliest_alert ? earliest_alert.alert : nil
       end
 
+      # @deprecated Not sure this is used any more.
+      #
+      # @return [Array]
       def all_overdue(at = Time.now)
         AlertEarliestDate.all(:earliest.lt => at, :order => [:earliest]).collect do |earliest_alert|
           earliest_alert ? earliest_alert.alert : nil
         end
       end
      
-      #
       # Receive an AlertUpdate buffer from the wire.
       #
+      # @param [String] update The update string, as received over UDP
+      # @param [Time] reception_time The time the update was received
+      # @param [String] ip_source The IP address of the source of the update
+      #
+      # @return [NilClass]
       def receive_update(update, reception_time = Time.now, ip_source="network")
 
         update = Proto::AlertUpdate.parse_from_string(update) unless update.kind_of?(Proto::AlertUpdate)
@@ -631,6 +718,8 @@ module Mauve
         return nil 
       end
 
+      #
+      # @return [Log4r::Logger] The class logger
       def logger
         Log4r::Logger.new(self.to_s)
       end
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
diff --git a/lib/mauve/alert_group.rb b/lib/mauve/alert_group.rb
index b320f18..7ea7ffb 100644
--- a/lib/mauve/alert_group.rb
+++ b/lib/mauve/alert_group.rb
@@ -3,6 +3,11 @@ require 'mauve/alert'
 require 'log4r'
 
 module Mauve
+  #
+  # This corresponds to a alert_group clause in the configuration.  It is what
+  # is used to classify alerts into levels, and thus who gets notified about it
+  # and when.
+  #
   class AlertGroup < Struct.new(:name, :includes, :acknowledgement_time, :level, :notifications)
 
     # 
@@ -15,6 +20,11 @@ module Mauve
     
     class << self
 
+      # Finds all AlertGroups that match an alert.
+      #
+      # @param [Mauve::Alert] alert
+      #
+      # @return [Array] AlertGroups that match
       def matches(alert)
         grps = all.select { |alert_group| alert_group.includes?(alert) }
 
@@ -26,10 +36,14 @@ module Mauve
         grps
       end
 
+      # @return [Log4r::Logger]
       def logger
         Log4r::Logger.new self.to_s
       end
 
+      # All AlertGroups
+      #
+      # @return [Array]
       def all
         return [] if Configuration.current.nil?
 
@@ -44,6 +58,7 @@ module Mauve
       # the first one should be returned thus making this useless. If you want
       # a list of all the alerts matching a level, use Alert.get_all().
       # 
+      # @return [Array]
       def all_alerts_by_level(level)
         Configuration.current.alert_groups.map do |alert_group|
           alert_group.level == level ? alert_group.current_alerts : []
@@ -52,18 +67,26 @@ module Mauve
 
     end
     
+    # Creates a new AlertGroup
+    #
+    # @param name Name of alert group
+    #
+    # @return [AlertGroup] self
     def initialize(name)
       self.name = name
       self.level = :normal
       self.includes = Proc.new { true }
+      self
     end
     
-    def inspect
+    # @return [String]
+    def to_s
       "#<AlertGroup:#{name} (level #{level})>"
     end
   
     # The list of current raised alerts in this group.
     #
+    # @return [Array] Array of Mauve::Alert
     def current_alerts
       Alert.all(:cleared_at => nil, :raised_at.not => nil).select { |a| includes?(a) }
     end
@@ -71,7 +94,8 @@ module Mauve
     # Decides whether a given alert belongs in this group according to its
     # includes { } clause
     #
-    # @param [Alert] alert An alert to test for belongness to group.
+    # @param [Mauve::Alert] alert
+    #
     # @return [Boolean] Success or failure.
     def includes?(alert)
 
@@ -86,18 +110,22 @@ module Mauve
 
     alias matches_alert? includes?
 
+    # @return [Log4r::Logger]
     def logger ; self.class.logger ; end
 
     # Signals that a given alert (which is assumed to belong in this group)
     # has undergone a significant change.  We resend this to every notify list.
-    #    
+    # 
+    # @param [Mauve::Alert] alert 
+    #
+    # @return [Boolean] indicates success or failure of alert.
     def notify(alert)
       #
       # If there are no notifications defined. 
       #
       if notifications.nil?
         logger.warn("No notifications found for #{self.inspect}")
-        return
+        return false
       end
 
       #
@@ -136,12 +164,15 @@ module Mauve
         sent_to << notification.notify(alert, sent_to)
       end
 
+      return (sent_to.length > 0)
     end
 
-    #
     # This sorts by priority (urgent first), and then alphabetically, so the
     # first match is the most urgent.
     #
+    # @param [Mauve::AlertGroup] other
+    #
+    # @return [Integer]
     def <=>(other)
       [LEVELS.index(self.level), self.name]  <=> [LEVELS.index(other.level), other.name]
     end
diff --git a/lib/mauve/authentication.rb b/lib/mauve/authentication.rb
index 74c6780..d0d4596 100644
--- a/lib/mauve/authentication.rb
+++ b/lib/mauve/authentication.rb
@@ -5,10 +5,19 @@ require 'timeout'
 
 module Mauve
 
+  #
+  # Base class for authentication.
+  #
   class Authentication
     
     ORDER = []
 
+    # Autenticates a user.
+    #
+    # @param [String] login
+    # @param [String] password
+    #
+    # @return [FalseClass] Always returns false.
     def authenticate(login, password)
       raise ArgumentError.new("Login must be a string, not a #{login.class}") if String != login.class
       raise ArgumentError.new("Password must be a string, not a #{password.class}") if String != password.class
@@ -19,18 +28,28 @@ module Mauve
       false
     end
 
+    # @return [Log4r::Logger]
     def logger
       self.class.logger
     end
-
+    
+    # @return [Log4r::Logger]
     def self.logger
       @logger ||= Log4r::Logger.new(self.to_s)
     end
 
+    # This calls all classes in the ORDER array one by one.  If all classes
+    # fail, a 5 second sleep rate-limits authentication attempts. 
+    #
+    # @param [String] login
+    # @param [String] password
+    #
+    # @return [Boolean] Success or failure.
+    #
     def self.authenticate(login, password)
       result = false
 
-      ORDER.each do |klass|
+      ORDER.any? do |klass|
         auth = klass.new
 
         result = begin
@@ -41,10 +60,9 @@ module Mauve
           false
         end
 
-        if true == result
-          logger.info "Authenticated #{login} using #{auth.class.to_s}"
-          break
-        end
+        logger.info "Authenticated #{login} using #{auth.class.to_s}" if true == result
+
+        result
       end
 
       unless true == result
@@ -59,12 +77,20 @@ module Mauve
   end
 
 
+  # This is the Bytemark authentication mechansim.
+  #
   class AuthBytemark < Authentication
 
     Mauve::Authentication::ORDER << self
 
+    # Set up the Bytemark authenticator
     #
-    # TODO: allow configuration of where the server is.
+    # @todo allow configuration of where the server is.
+    #
+    # @param [String] srv Authentication server name
+    # @param [String] port Port overwhich authentication should take place
+    #
+    # @return [Mauve::AuthBytemark]
     #
     def initialize (srv='auth.bytemark.co.uk', port=443)
       raise ArgumentError.new("Server must be a String, not a #{srv.class}") if String != srv.class
@@ -72,10 +98,16 @@ module Mauve
       @srv = srv
       @port = port
       @timeout = 7
+
+      self
     end
 
-    ## Not really needed.
-    def ping ()
+    # Tests to see if a server is alive, alive-o.
+    #
+    # @deprecated Not really needed.
+    #
+    # @return [Boolean]
+    def ping
       begin
         Timeout.timeout(@timeout) do
           s = TCPSocket.open(@srv, @port)
@@ -90,6 +122,12 @@ module Mauve
       return false
     end
 
+    # Authenticate against the Bytemark server
+    #
+    # @param [String] login
+    # @param [String] password
+    #
+    # @return [Boolean]
     def authenticate(login, password)
       super
 
@@ -111,10 +149,19 @@ module Mauve
 
   end
 
+  # This is the local authentication mechansim, i.e. against the values in the
+  # Mauve config file.
+  #
   class AuthLocal < Authentication
 
     Mauve::Authentication::ORDER << self
 
+    # Authenticate against the local configuration
+    #
+    # @param [String] login
+    # @param [String] password
+    #
+    # @return [Boolean]
     def authenticate(login,password)
       super
       Digest::SHA1.hexdigest(password) == Mauve::Configuration.current.people[login].password
diff --git a/lib/mauve/calendar_interface.rb b/lib/mauve/calendar_interface.rb
index abce824..cf515d1 100644
--- a/lib/mauve/calendar_interface.rb
+++ b/lib/mauve/calendar_interface.rb
@@ -8,25 +8,20 @@ module Mauve
 
   # Interface to the Bytemark calendar.
   #
-  # Nota Bene that this does not include a chaching mechanism.  Some caching
-  # is implemented in the Person object.
-  #
-  # @see Mauve::Person
-  # @author yann Golanski.
   class CalendarInterface 
     
     class << self
 
+      # @return [Log4r::Logger]
       def logger
         @logger ||= Log4r::Logger.new(self.to_s)
       end
 
       # Gets a list of ssologin on support.
       #
-      # Class method.
-      #
       # @param [String] url A Calendar API url.
-      # @return [Array] A list of all the username on support.
+      #
+      # @return [Array] A list of all the usernames on support.
       def get_users_on_support(url)
         result = do_get_with_cache(url)
 
@@ -41,10 +36,9 @@ module Mauve
 
       # Check to see if the user is on support.
       #
-      # Class method.
-      #
       # @param [String] url A Calendar API url.
       # @param [String] usr User single sign on.
+      #
       # @return [Boolean] True if on support, false otherwise.
       def is_user_on_support?(url, usr)
         return get_users_on_support(url).include?(usr)
@@ -56,6 +50,7 @@ module Mauve
       #
       # @param [String] url A Calendar API url.
       # @param [String] usr User single sign on.
+      # 
       # @return [Boolean] True if on holiday, false otherwise.
       def is_user_on_holiday?(url)
         result = do_get_with_cache(url)
@@ -72,7 +67,7 @@ module Mauve
 
       # Grab a URL from the wide web.
       #
-      # @TODO: boot this in its own class since list of ips will need it too.
+      # @todo boot this in its own class since list of ips will need it too.
       #
       # @param [String] uri -- a URL
       # @return [String or nil] -- the contents of the URI or nil if an error has been encountered.
@@ -136,6 +131,12 @@ module Mauve
         return nil
       end
 
+      # This does HTTP fetches with a 5 minute cache
+      #
+      # @param [String] url
+      # @param [Time] cache_until
+      #
+      # @return [String or nil]
       def do_get_with_cache(url, cache_until = Time.now + 5.minutes)
         @cache ||= {}
 
diff --git a/lib/mauve/configuration.rb b/lib/mauve/configuration.rb
index 56f5e7e..a74165b 100644
--- a/lib/mauve/configuration.rb
+++ b/lib/mauve/configuration.rb
@@ -4,26 +4,52 @@ require 'mauve/mauve_time'
 
 module Mauve
 
-  ## Configuration object for Mauve.
-  #
-  #
-  # @TODO Write some more documentation. This is woefully inadequate.
+  # Configuration object for Mauve.  This is used as the context in
+  # Mauve::ConfigurationBuilder.
   #
   class Configuration
 
     class << self
+      # The current configuration
+      # @param  [Mauve::Configuration]
+      # @return [Mauve::Configuration]
       attr_accessor :current
     end
-    
+
+    # The Server instance
+    # @return [Mauve::Server]
     attr_accessor :server
+
+    # The last AlertGroup to be configured
+    # @return [Mauve::AlertGroup]
     attr_accessor :last_alert_group
+
+    # Notification methods
+    # @return [Hash]
     attr_reader   :notification_methods
+
+    # People
+    # @return [Hash]
     attr_reader   :people
+    
+    # Alert groups
+    # @return [Array]
     attr_reader   :alert_groups
+
+    # People lists
+    # @return [Hash]
     attr_reader   :people_lists
+
+    # The source lists
+    # @return [Hash]
     attr_reader   :source_lists
- 
+
+    #
+    # Set up a base config.
+    #
     def initialize
+      @server = nil
+      @last_alert_group = nil
       @notification_methods = {}
       @people = {}
       @people_lists = Hash.new{|h,k| h[k] = Mauve::PeopleList.new(k)}
diff --git a/lib/mauve/configuration_builder.rb b/lib/mauve/configuration_builder.rb
index fb3c781..1d8d960 100644
--- a/lib/mauve/configuration_builder.rb
+++ b/lib/mauve/configuration_builder.rb
@@ -5,9 +5,11 @@ require 'mauve/people_list'
 require 'mauve/source_list'
 
 module Mauve
+  #
+  # This is the top-level configuration builder
+  #
   class ConfigurationBuilder < ObjectBuilder
 
-    #
     # This overwrites the default ObjectBuilder initialize method, such that
     # the context is set as a new configuration
     #
@@ -16,19 +18,31 @@ module Mauve
       # FIXME: need to test blocks that are not immediately evaluated
     end
 
+    # Adds a source list
+    #
+    # @param [String] label
+    # @param [Array]  list
+    #
+    # @return [Array] the whole source list for label
     def source_list(label, *list)
       _logger.warn "Duplicate source_list '#{label}'" if @result.source_lists.has_key?(label)
       @result.source_lists[label] += list
     end
 
+    # Adds a people list
+    #
+    # @param [String] label
+    # @param [Array]  list
+    #
+    # @return [Array] the whole people list for label
     def people_list(label, *list)
       _logger.warn("Duplicate people_list '#{label}'") if @result.people_lists.has_key?(label)
       @result.people_lists[label] += list
     end
 
-    #
     # Have to use the method _logger here, cos logger is defined as a builder elsewhere.
     #
+    # @return [Log4r::Logger]
     def _logger
       @logger ||= Log4r::Logger.new(self.class.to_s)
     end
diff --git a/lib/mauve/configuration_builders.rb b/lib/mauve/configuration_builders.rb
index 03d666e..7ff6ac9 100644
--- a/lib/mauve/configuration_builders.rb
+++ b/lib/mauve/configuration_builders.rb
@@ -1,6 +1,15 @@
-
 require 'mauve/configuration_builders/logger'
 require 'mauve/configuration_builders/notification_method'
 require 'mauve/configuration_builders/person'
 require 'mauve/configuration_builders/server'
 require 'mauve/configuration_builders/alert_group'
+
+module Mauve
+  #
+  # This is where all the builders for the various configuration stanzas are
+  # kept.
+  #
+  module ConfigurationBuilders
+
+  end
+end
diff --git a/lib/mauve/configuration_builders/alert_group.rb b/lib/mauve/configuration_builders/alert_group.rb
index 9561d4d..c652de8 100644
--- a/lib/mauve/configuration_builders/alert_group.rb
+++ b/lib/mauve/configuration_builders/alert_group.rb
@@ -7,59 +7,81 @@ require 'mauve/notification'
 
 module Mauve
   module ConfigurationBuilders
-
+    #
+    # This corresponds to a new "notify" clause an the alert_group config.
+    #
     class Notification < ObjectBuilder
 
-    def builder_setup(*who)
-      who = who.map do |username|
-        #raise BuildException.new("You haven't declared who #{username} is") unless
-        #  @context.people[username]
-        #@context.people[username]
-        if @context.people[username]
-          @context.people[username]
-        elsif @context.people_lists[username]
-          @context.people_lists[username]
-        else
-          raise BuildException.new("You have not declared who #{username} is")
+      # Sets up the notification
+      # 
+      # @param [Array] who List of usernames or people_lists to notify
+      # @raise [ArgumentError] if a username doesn't exist.
+      #
+      # @return [Mauve::Notification] New notification instance.
+      def builder_setup(*who)
+        who = who.map do |username|
+          #raise BuildException.new("You haven't declared who #{username} is") unless
+          #  @context.people[username]
+          #@context.people[username]
+          if @context.people[username]
+            @context.people[username]
+          elsif @context.people_lists[username]
+            @context.people_lists[username]
+          else
+            raise ArgumentError.new("You have not declared who #{username} is")
+          end
         end
+        @result = Mauve::Notification.new(who, @context.last_alert_group.level)
       end
-      @result = Mauve::Notification.new(who, @context.last_alert_group.level)
-    end
-
-    is_attribute "every"
-    is_block_attribute "during"
-    ##is_attribute "hours_in_day"
-    ##is_attribute "unacknowledged"
-  end
-
-  class AlertGroup < ObjectBuilder
-
-    def builder_setup(name=anonymous_name)
-      @result = Mauve::AlertGroup.new(name)
-      @context.last_alert_group = @result
+      
+      is_attribute "every"
+      is_block_attribute "during"
     end
 
-    is_block_attribute "includes"
-    is_attribute "acknowledgement_time"
-    is_attribute "level"
+    # This corresponds to a new alert_group clause
+    #
+    class AlertGroup < ObjectBuilder
+
+      # Sets up the alert group, and sets the last_alert_group context.
+      # 
+      # @param [String] name Name of the new alert group
+      #
+      # @return [Mauve::AlertGroup] New alert group instance
+      def builder_setup(name="anonymous_name")
+        @result = Mauve::AlertGroup.new(name)
+        @context.last_alert_group = @result
+      end
 
-    is_builder "notify", Notification
+      is_block_attribute "includes"
+      is_attribute "acknowledgement_time"
+      is_attribute "level"
+      is_builder "notify", Mauve::ConfigurationBuilders::Notification
+
+      # Method called after the notify clause has been sorted.  Adds new
+      # notification clause to the result.
+      #
+      # @param [Mauve::Notification] notification
+      #
+      def created_notify(notification)
+        @result.notifications ||= []
+        @result.notifications << notification
+      end
 
-    def created_notify(notification)
-      @result.notifications ||= []
-      @result.notifications << notification
     end
 
   end
 
-  end
-
-  # this should live in AlertGroup but can't due to
+  # These constants define the levels available for alert groups.
+  #
+  # This should live in AlertGroup but can't due to
   # http://briancarper.net/blog/ruby-instance_eval_constant_scoping_broken
   #
   module AlertGroupConstants
+    # Urgent level
     URGENT = :urgent
+    # Normal level
     NORMAL = :normal
+    # Low level
     LOW    = :low
   end
 
@@ -70,9 +92,14 @@ module Mauve
 
     is_builder "alert_group", ConfigurationBuilders::AlertGroup
 
+    # Called after an alert group is created.  Checks to make sure that no more than one alert group shares a name.
+    #
+    # @param [Mauve::AlertGroup] alert_group The new AlertGroup
+    # @raise [ArgumentError] if an AlertGroup with the same name already exists.
+    #
     def created_alert_group(alert_group)
       name = alert_group.name
-      raise BuildException.new("Duplicate alert_group '#{name}'") unless @result.alert_groups.select { |g| g.name == name }.empty?
+      raise ArgumentError.new("Duplicate alert_group '#{name}'") unless @result.alert_groups.select { |g| g.name == name }.empty?
       @result.alert_groups << alert_group
     end
 
diff --git a/lib/mauve/configuration_builders/logger.rb b/lib/mauve/configuration_builders/logger.rb
index 3f60dfe..d757d88 100644
--- a/lib/mauve/configuration_builders/logger.rb
+++ b/lib/mauve/configuration_builders/logger.rb
@@ -7,31 +7,48 @@ module Mauve
 
     class LoggerOutputter < ObjectBuilder
 
+      # Set up a Log4r::Outputter
+      #
+      # @param [String] outputter Outputter basic class name, like Stderr, Stdin, File.
+      #
       def builder_setup(outputter)
         @outputter = outputter.capitalize+"Outputter"
 
         begin
           Log4r.const_get(@outputter)
-        rescue
+        rescue NameError
           require "log4r/outputter/#{@outputter.downcase}"
         end
 
-        @outputter_name = "Mauve-"+5.times.collect{rand(36).to_s(36)}.join
+        @outputter_name = anonymous_name
 
         @args = {}
       end
 
+      # The new outputter
+      #
+      # @return [Log4r::Outputter]
       def result
         @result ||= Log4r.const_get(@outputter).new("Mauve", @args)
       end
 
+      # Set the formatter for this outputter (see Log4r::PatternFormatter for
+      # allowed patterns).  SyntaxError is caught in the ObjectBuilder#parse
+      # method.
+      # 
+      # @param [String] f The format
+      #
+      # @return [Log4r::PatternFormatter]
       def format(f)
         result.formatter = Log4r::PatternFormatter.new(:pattern => f)
       end
 
-      #
       # This is needed to be able to pass arbitrary arguments to Log4r
-      # outputters.
+      # outputters.  Missing methods / bad arguments are caught in the
+      # ObjectBuilder#parse method.
+      #
+      # @param [String] name
+      # @param [Object] value
       #
       def method_missing(name, value=nil)
         if value.nil?
@@ -47,38 +64,59 @@ module Mauve
 
       is_builder "outputter", LoggerOutputter
 
+      # Set up the new logger
+      #
       def builder_setup
         @result         = Log4r::Logger['Mauve'] || Log4r::Logger.new('Mauve')
         @default_format = nil
         @default_level  = Log4r::RootLogger.instance.level
       end
 
+      # Set the default format.  Syntax erros are caught in the
+      # ObjectBuilder#parse method.
+      #
+      # @param [String] f Any format pattern allowed by Log4r::PatternFormatter.
+      #
+      # @return [Log4r::PatternFormatter]
       def default_format(f)
-        begin
-          @default_formatter = Log4r::PatternFormatter.new(:pattern => f)
-        rescue SyntaxError 
-          raise BuildException.new "Bad log format #{f.inspect}"
-        end
+        @default_formatter = Log4r::PatternFormatter.new(:pattern => f)
+
         #
         # Set all current outputters
         #
         result.outputters.each do |o|
           o.formatter = @default_formatter if o.formatter.is_a?(Log4r::DefaultFormatter)
         end
+
+        @default_formatter
       end
 
+      # Set the default log level.
+      #
+      # @param [Integer] l The log level.
+      # @raise [ArgumentError] If the log level is bad
+      #
+      # @return [Integer] The log level set.
       def default_level(l)
         if Log4r::Log4rTools.valid_level?(l)
           @default_level = l
         else
-          raise "Bad default level set for the logger #{l}.inspect"
+          raise ArgumentError.new "Bad default level set for the logger #{l.inspect}"
         end
 
         result.outputters.each do |o|
           o.level = @default_level if o.level == Log4r::RootLogger.instance.level
         end
+
+        @default_level
       end
 
+      # This is called once an outputter has been created.  It sets the default
+      # formatter and level, if these have been already set.
+      #
+      # @param [Log4r::Outputter] outputter Newly created outputter.
+      #
+      # @return [Log4r::Outputter] The adjusted outputter.
       def created_outputter(outputter)
         #
         # Set the formatter and level for any newly created outputters
@@ -92,7 +130,6 @@ module Mauve
         end
 
         result.outputters << outputter
-#        result.outputter.write("Created logger")
       end
     end
   end
@@ -104,10 +141,15 @@ module Mauve
   module LoggerConstants
     Log4r.define_levels(*Log4r::Log4rConfig::LogLevels) # ensure levels are loaded
 
+    # Debug logging
     DEBUG = Log4r::DEBUG
+    # Info logging
     INFO  = Log4r::INFO
+    # Warn logging
     WARN  = Log4r::WARN
+    # Error logging
     ERROR = Log4r::ERROR
+    # Fatal logging
     FATAL = Log4r::FATAL
   end
 
diff --git a/lib/mauve/configuration_builders/notification_method.rb b/lib/mauve/configuration_builders/notification_method.rb
index 1192078..9596587 100644
--- a/lib/mauve/configuration_builders/notification_method.rb
+++ b/lib/mauve/configuration_builders/notification_method.rb
@@ -1,27 +1,46 @@
 require 'mauve/notifiers'
 require 'mauve/configuration_builder'
 
-# encoding: UTF-8
 module Mauve
   module ConfigurationBuilders
     class NotificationMethod < ObjectBuilder
 
+      #
+      # Set up the notification.  Missing notifiers are caught via NameError in
+      # the ObjectBuilder#parse method.
+      #
+      # @param [String] name Name of the notifier
+      # 
       def builder_setup(name)
-        @notification_type = name.capitalize
+        notifiers_base = Mauve::Notifiers
+
+        @notifier_type = notifiers_base.const_get(name.capitalize)
+
         @name = name
         provider("Default")
       end
 
+      # This allows use of multiple notification providers, e.g. in the case of
+      # SMS.
+      #
+      # Missing providers are caught via NameError in the ObjectBuilder#parse
+      # method.
+      #
       def provider(name)
-        notifiers_base = Mauve::Notifiers
-        notifiers_type = notifiers_base.const_get(@notification_type)
-        @provider_class = notifiers_type.const_get(name)
+        @provider_class = @notifier_type.const_get(name)
       end
       
+      # Returns the result for this builder, depending on the configuration
+      #
       def result
         @result ||= @provider_class.new(@name)
       end
-      
+     
+      # This catches all methods available for a provider, as needed.
+      #
+      # Missing methods / bad arguments etc. are caught in the
+      # ObjectBuilder#parse method, via NoMethodError.
+      #
       def method_missing(name, value=nil)
         if value
           result.send("#{name}=".to_sym, value)
@@ -38,6 +57,9 @@ module Mauve
   class ConfigurationBuilder < ObjectBuilder
     is_builder "notification_method", ConfigurationBuilders::NotificationMethod
 
+    # Method called after a notification method has been created to check for duplicate names.
+    #
+    # @raise [BuildException] when a duplicate notification method is found.
     def created_notification_method(notification_method)
       name = notification_method.name
       raise BuildException.new("Duplicate notification '#{name}'") if @result.notification_methods[name]
diff --git a/lib/mauve/configuration_builders/person.rb b/lib/mauve/configuration_builders/person.rb
index 1c012f2..c5314c5 100644
--- a/lib/mauve/configuration_builders/person.rb
+++ b/lib/mauve/configuration_builders/person.rb
@@ -15,29 +15,21 @@ module Mauve
       is_block_attribute "urgent"
       is_block_attribute "normal"
       is_block_attribute "low"
-      
-      def all(&block); urgent(&block); normal(&block); low(&block); end
-
-      def password (pwd)
-        @result.password = pwd.to_s
-      end
-
-      def holiday_url (url)
-        @result.holiday_url = url.to_s
-      end
+      is_attribute "password"
+      is_attribute "sms"
+      is_attribute "holiday_url"
+      is_attribute "email"
+      is_attribute "xmpp"
+      is_attribute "sms"
      
-      def email(e)
-        @result.email = e.to_s
-      end
+      # Sets the block for all levels of alert
+      #
+      # @param [Block] block 
+      def all(&block); urgent(&block); normal(&block); low(&block); end
 
-      def xmpp(x)
-        @result.xmpp = x.to_s
-      end
-      
-      def sms(x)
-        @result.sms = x.to_s
-      end
-   
+      # Notification suppression hash
+      #
+      # @param [Hash] h
       def suppress_notifications_after(h)
         raise ArgumentError.new("notification_threshold must be specified as e.g. (10 => 1.minute)") unless h.kind_of?(Hash)
 
@@ -54,9 +46,14 @@ module Mauve
 
     is_builder "person", ConfigurationBuilders::Person
 
+    # Method called once a person has been created to check for duplicate names
+    #
+    # @param [Mauve::Person] person
+    # @raise [ArgumentError] if a person has already been declared.
+    #
     def created_person(person)
       name = person.username
-      raise BuildException.new("Duplicate person '#{name}'") if @result.people[name]
+      raise ArgumentError.new("Duplicate person '#{name}'") if @result.people[name]
       #
       # Add a default notification threshold
       #
diff --git a/lib/mauve/configuration_builders/server.rb b/lib/mauve/configuration_builders/server.rb
index 3a9f5ec..c000144 100644
--- a/lib/mauve/configuration_builders/server.rb
+++ b/lib/mauve/configuration_builders/server.rb
@@ -5,74 +5,157 @@ require 'mauve/configuration_builder'
 module Mauve
   module ConfigurationBuilders
 
+    #
+    # This is the HTTP server
+    #
     class HTTPServer < ObjectBuilder
+      # The port the http server listens on
       is_attribute "port"
+      # The IP address the http server listens on.  IPv6 is *NOT* OK.
       is_attribute "ip"
+      # Where all the templates are kept
       is_attribute "document_root"
+      # The secret for the cookies
       is_attribute "session_secret"
+      # The base URL of the server.
       is_attribute "base_url"
 
+      # Sets up a Mauve::HTTPServer singleton as the result
+      #
+      # @return [Mauve::HTTPServer]
       def builder_setup
         @result = Mauve::HTTPServer.instance
       end
     end
 
+    #
+    # This is the UDP server.
+    #
     class UDPServer < ObjectBuilder
+      # This is the port the server listens on
       is_attribute "port"
+      # This is the IP address the server listens on.  IPv6 is OK! e.g. [::] for  all addresses
       is_attribute "ip"
+      # This is the sleep interval for the UDP server.
       is_attribute "poll_every"
     
+      # Sets up a Mauve::UDPServer singleton as the result
+      #
+      # @return [Mauve::UDPServer]
       def builder_setup
         @result = Mauve::UDPServer.instance
       end
     end
 
+    #
+    # This is the thread that pulls packets from the queue for processing.
+    #
     class Processor < ObjectBuilder
+      # This is the interval between polls of the packet queue.
       is_attribute "poll_every"
+      # This is the timeout for the transmission cache, which allows duplicate packets to be discarded.
       is_attribute "transmission_cache_expire_time"
 
+      # Sets up a Mauve::Processor singleton as the result
+      #
+      # @return [Mauve::Processor]
       def builder_setup
         @result = Mauve::Processor.instance
       end
     end
 
+    #
+    # This is the Timer singleton.
+    #
     class Timer < ObjectBuilder
+      #
+      # This is the interval at which the Timer thread is run.  This will limit
+      # the rate at which notifications can be sent, if set.
+      #
       is_attribute "poll_every"
 
+      # Sets up a Mauve::Timer singleton as the result
+      #
+      # @return [Mauve::Timer]
       def builder_setup
         @result = Mauve::Timer.instance
       end
     end
 
     class Notifier < ObjectBuilder
+      #
+      # This is the interval at which the notification queue is polled for new
+      # notifications to be sent.  This will not have any rate-limiting effect.
+      #
       is_attribute "poll_every"
 
+      # Sets up a Mauve::Notifier singleton as the result
+      #
+      # @return [Mauve::Notifier]
       def builder_setup
         @result = Mauve::Notifier.instance
       end
     end
  
+    #
+    # This sends a mauve heartbeat to another Mauve instance elsewhere
+    #
     class Heartbeat < ObjectBuilder
+      #
+      # The destination for the heartbeat
+      #
       is_attribute "destination"
+
+      #
+      # The detail field for the heartbeat
+      #
       is_attribute "detail"
+
+      #
+      # The summary field for the heartbeat.
+      #
       is_attribute "summary"
+
+      #
+      # How long to raise an alert after the last heartbeat.
+      #
       is_attribute "raise_after"
+
+      #
+      # The interval between heartbeats
+      #
       is_attribute "send_every"
-    
+
+      # Sets up a Mauve::Heartbeat singleton as the result
+      #
+      # @return [Mauve::Heartbeat]
       def builder_setup
         @result = Mauve::Heartbeat.instance
       end
     end
 
     class Pop3Server < ObjectBuilder
+      #
+      # The IP adderess the Pop3 server listens on
+      #
       is_attribute "ip"
+
+      #
+      # The POP3 server port
+      #
       is_attribute "port"
 
+      # Sets up a Mauve::Pop3Server singleton as the result
+      #
+      # @return [Mauve::Pop3Server]
       def builder_setup
         @result = Mauve::Pop3Server.instance
       end
     end
 
+    #
+    # This is the main Server singleton.
+    #
     class Server < ObjectBuilder
       #
       # Set up second-level builders
@@ -85,8 +168,19 @@ module Mauve
       is_builder "heartbeat",     Heartbeat
       is_builder "pop3_server",   Pop3Server
 
+      #
+      # The name of the server this instance of Mauve is running on
+      #
       is_attribute "hostname"
+
+      #
+      # The database definition
+      #
       is_attribute "database"
+
+      #
+      # The period of sleep during which no heartbeats are raised.
+      #
       is_attribute "initial_sleep"
    
       def builder_setup
@@ -102,8 +196,12 @@ module Mauve
 
     is_builder "server", ConfigurationBuilders::Server
 
+    # This is called once the server object has been created.
+    #
+    # @raise [SyntaxError] if more than one server clause has been defined.
+    #
     def created_server(server)
-      raise BuildError.new("Only one 'server' clause can be specified") if @result.server
+      raise SyntaxError.new("Only one 'server' clause can be specified") if @result.server
       @result.server = server
     end
 
diff --git a/lib/mauve/heartbeat.rb b/lib/mauve/heartbeat.rb
index 39d3499..1fe2fab 100644
--- a/lib/mauve/heartbeat.rb
+++ b/lib/mauve/heartbeat.rb
@@ -3,17 +3,23 @@ require 'mauve/proto'
 require 'mauve/mauve_thread'
 require 'log4r'
 
-#
-# This class is responsible for sending a heartbeat to another mauve instance elsewhere.
-#
 module Mauve
 
+  #
+  # This class is responsible for sending a heartbeat to another mauve instance elsewhere.
+  #
   class Heartbeat < MauveThread
 
     include Singleton
 
+    #
+    # Allow access to some basics.
+    #
     attr_reader   :raise_after, :destination, :summary, :detail
 
+    #
+    # This sets up the Heartbeat singleton
+    #
     def initialize
       super
 
@@ -24,6 +30,10 @@ module Mauve
       @poll_every     = 60
     end
 
+    #
+    # This is the time period after which an alert is raised by the remote Mauve instance.
+    # @param [Integer] i Seconds
+    # @return [Integer] Seconds
     def raise_after=(i)
       raise ArgumentError "raise_after must be an integer" unless i.is_a?(Integer)      
       @raise_after = i
@@ -31,25 +41,39 @@ module Mauve
 
     alias send_every=  poll_every=
 
+    # Sets the summary of the heartbeat
+    #
+    # @param [String] s Summary
     def summary=(s)
       raise ArgumentError "summary must be a string" unless s.is_a?(String)
       @summary = s
     end
 
+    # Sets the detail of the heartbeat
+    #
+    # @param [String] d Detail
     def detail=(d)
       raise ArgumentError "detail must be a string" unless d.is_a?(String)
       @detail = d
     end
 
+    # Sets the destinantion Mauve instance
+    #
+    # @param [String] d Destination
+    #
     def destination=(d)
       raise ArgumentError "destination must be a string" unless d.is_a?(String)
       @destination = d
     end
 
+    # @return [Log4r::Logger]
     def logger
       @logger ||= Log4r::Logger.new(self.class.to_s)
     end
 
+    private
+
+    # @private This is the main heartbeat loop.
     def main_loop
       #
       # Don't send if no destination set.
diff --git a/lib/mauve/history.rb b/lib/mauve/history.rb
index 76025a0..d9ab8e9 100644
--- a/lib/mauve/history.rb
+++ b/lib/mauve/history.rb
@@ -4,6 +4,10 @@ require 'mauve/alert'
 require 'log4r'
 
 module Mauve
+  # This is the look-up table for Alerts and History to allow one History to
+  # have many Alerts and vice-versa
+  #
+  #
   class AlertHistory
     include DataMapper::Resource
 
@@ -15,6 +19,10 @@ module Mauve
 
     after :destroy, :remove_unreferenced_histories
 
+    # This is a horid migration to allow a move from an older version of Mauve
+    # without this table.
+    #
+    #
     def self.migrate!
       #
       # This copies the alert IDs from the old History table to the new AlertHistories thing, but only if there are no AertHistories 
@@ -45,12 +53,20 @@ module Mauve
 
     private
 
+    # This just removes histories that this AlertHistory used to refer to, if
+    # they have no other alerts associated with them
+    #
+    #
     def remove_unreferenced_histories
       self.history.destroy unless self.history.alerts.count > 0
     end
 
   end
 
+  # This class keeps a history for Mauve.  One History can relate to zero or
+  # more Alerts, allowing notes to be added.
+  #
+  #
   class History
     include DataMapper::Resource
     
@@ -73,7 +89,6 @@ module Mauve
 
     protected
 
-    #
     # This cleans the HTML before saving.
     #
     def do_sanitize_html  
@@ -93,16 +108,21 @@ module Mauve
       end
     end
 
-
+    # Update the created_at time on the object
+    #
     def set_created_at(context = :default)
       self.created_at = Time.now unless self.created_at.is_a?(Time) 
     end
 
     public
 
+    # This adds an alert or an array of alerts to the cache of alerts
+    # associated with this model.
     #
     # Blasted datamapper not eager-loading my model.
     #
+    # @param [Array or Alert] a Array of Alerts or a single Alert
+    # @raise ArgumentError If +a+ is not an Array or an Alert
     def add_to_cached_alerts(a)
       @cached_alerts ||= []
       if a.is_a?(Array) and a.all?{|m| m.is_a?(Alert)}
@@ -114,15 +134,22 @@ module Mauve
       end
     end
 
+    # Find all the alerts for this History.  This caches the alerts found.
+    # Call #reload to get rid of the cache.
+    #
+    # @return [Array] Alerts
     def alerts
       @cached_alerts ||= super
     end
 
+    # Reload the object, and clear the cache.
+    #
     def reload
       @cached_alerts = nil
       super
     end
 
+    # @return Log4r::Logger
     def logger
       Log4r::Logger.new self.class.to_s
     end
diff --git a/lib/mauve/http_server.rb b/lib/mauve/http_server.rb
index 72eb85a..583e6b5 100644
--- a/lib/mauve/http_server.rb
+++ b/lib/mauve/http_server.rb
@@ -21,26 +21,41 @@ require 'rack/handler/webrick'
 # Bodge up thin logging.
 # 
 module Thin
+  #
+  # Bodge up thin logging.
+  #
   module Logging
-    
+
+    # Log a message at "info" level
+    #
+    # @param [String] m
     def log(m=nil)
       # return if Logging.silent?
       logger = Log4r::Logger.new "Mauve::HTTPServer"
       logger.info(m || yield)
     end
     
+    # Log a message at "debug" level
+    #
+    # @param [String] m
     def debug(m=nil)
       # return unless Logging.debug?
       logger = Log4r::Logger.new "Mauve::HTTPServer"
       logger.debug(m || yield)
     end
     
+    # Log a trace at "debug" level
+    #
+    # @param [String] m
     def trace(m=nil)
       return unless Logging.trace?
       logger = Log4r::Logger.new "Mauve::HTTPServer"
       logger.debug(m || yield)
     end
     
+    # Log a message at "error" level
+    #
+    # @param [String] e
     def log_error(e=$!)
       logger = Log4r::Logger.new "Mauve::HTTPServer"
       logger.error(e)
@@ -58,8 +73,16 @@ end
 #
 class RackErrorsProxy
 
+  #
+  # Set up the instance
+  #
+  # @param [Log4r::Logger] l The logger instance.
+  #
   def initialize(l); @logger = l; end
 
+  # Log a message at "error" level
+  #
+  # @param [String or Array] msg
   def write(msg)
     case msg
       when String then @logger.info(msg.chomp)
@@ -72,6 +95,8 @@ class RackErrorsProxy
   alias_method :<<, :write
   alias_method :puts, :write
 
+  # no-op
+  #
   def flush; end
 end
 
@@ -81,7 +106,7 @@ end
 module Mauve
 
   # 
-  # API to control the web server
+  # The HTTP Server object
   #
   class HTTPServer < MauveThread
 
@@ -90,6 +115,9 @@ module Mauve
     attr_reader :port, :ip, :document_root, :base_url
     attr_reader :session_secret 
     
+    #
+    # Initialze the server
+    #
     def initialize
       super
       self.port = 1288
@@ -98,11 +126,18 @@ module Mauve
       self.session_secret = "%x" % rand(2**100)
     end
    
+    # Set the port
+    #
+    # @param [Intger] pr The port number between 1 and 2**16-1
+    # @raise [ArgumentError] If the port is not valid
     def port=(pr)
-      raise ArgumentError, "port must be an integer between 0 and #{2**16-1}" unless pr.is_a?(Integer) and pr < 2**16 and pr > 0
+      raise ArgumentError, "port must be an integer between 1 and #{2**16-1}" unless pr.is_a?(Integer) and pr < 2**16 and pr > 0
       @port = pr
     end
     
+    # Set the listening IP address
+    #
+    # @param [String] i The IP
     def ip=(i)
       raise ArgumentError, "ip must be a string" unless i.is_a?(String)
       #
@@ -112,6 +147,12 @@ module Mauve
       @ip = i
     end
 
+    # Set the document root.
+    # @param [String] d The directory where the templates etc are kept.
+    # @raise [ArgumentError] If d is not a string
+    # @raise [Errno::ENOTDIR] If d does not exist
+    # @raise [Errno::ENOTDIR] If d is not a directory
+    #
     def document_root=(d)
       raise ArgumentError, "document_root must be a string" unless d.is_a?(String)
       raise Errno::ENOENT, d unless File.exists?(d)
@@ -120,6 +161,10 @@ module Mauve
       @document_root = d
     end
 
+    # Set the base URL
+    #
+    # @param [String] b The base URL, including https?://
+    # @raise [ArgumentError] If b is not a string, or https?:// is missing
     def base_url=(b)
       raise ArgumentError, "base_url must be a string" unless b.is_a?(String)
       raise ArgumentError, "base_url should start with http:// or https://" unless b =~ /^https?:\/\//
@@ -128,35 +173,50 @@ module Mauve
       #
       @base_url = b.chomp("/")
     end
-
+    
+    # Set the cookie session secret
+    #
+    # @param [String] s The secret
+    # @raise [ArgumentError] if s is not a string
     def session_secret=(s)
       raise ArgumentError, "session_secret must be a string" unless s.is_a?(String)
       @session_secret = s 
     end
 
-    def main_loop
-      unless @server and @server.running?
-        # 
-        # Sessions are kept for 8 days.
-        #
-        @server = ::Thin::Server.new(@ip, @port, Rack::Session::Cookie.new(WebInterface.new, {:key => "mauvealert", :secret => @session_secret, :expire_after => 8.weeks}), :signals => false)
-        @server.start
-      end
-    end
-
+    # Return the base_url
+    #
+    # @return [String]
     def base_url
       @base_url ||= "http://"+Server.instance.hostname
     end
     
+    # Stop the server
+    #
     def stop
       @server.stop if @server and @server.running?
       super
     end
 
+    # Stop the server, faster than #stop
+    #
     def join
       @server.stop! if @server and @server.running?
       super
     end
 
+    private
+
+    #
+    # @private This is the main loop to keep the server going.
+    #
+    def main_loop
+      unless @server and @server.running?
+        # 
+        # Sessions are kept for 8 days.
+        #
+        @server = ::Thin::Server.new(@ip, @port, Rack::Session::Cookie.new(WebInterface.new, {:key => "mauvealert", :secret => @session_secret, :expire_after => 8.weeks}), :signals => false)
+        @server.start
+      end
+    end
   end    
 end
diff --git a/lib/mauve/mauve_resolv.rb b/lib/mauve/mauve_resolv.rb
index 6c97bef..c6460e3 100644
--- a/lib/mauve/mauve_resolv.rb
+++ b/lib/mauve/mauve_resolv.rb
@@ -1,12 +1,19 @@
 require 'resolv-replace'
 
-#
-#
-#
-
 module Mauve
+  #
+  # This is just a quick class to resolve a hostname to all its IPs, IPv6 and IPv4.
+  #
   class MauveResolv
+
     class << self
+
+      # Get all IPs for a host, both IPv6 and IPv4.  ResolvError and
+      # ResolvTimeout are both rescued.
+      #
+      # @param [String] host The hostname 
+      # @return [Array] Array of IP addresses, as Strings.
+      #
       def get_ips_for(host)
         record_types = %w(A AAAA)
         ips = []
@@ -25,6 +32,7 @@ module Mauve
         ips
       end
 
+      # @return [Log4r::Logger]
       def logger
         @logger ||= Log4r::Logger.new(self.to_s)
       end
diff --git a/lib/mauve/mauve_thread.rb b/lib/mauve/mauve_thread.rb
index 2191d58..42f41a2 100644
--- a/lib/mauve/mauve_thread.rb
+++ b/lib/mauve/mauve_thread.rb
@@ -3,18 +3,39 @@ require 'singleton'
 
 module Mauve
 
+  #
+  # This is a class to wrap our threads that have processing loops.
+  #
+  # The thread is kept in a wrapper to allow it to be frozen and thawed at
+  # convenient times.
+  #
   class MauveThread
 
+    #
+    # The sleep interval between runs of the main loop.  Defaults to 5 seconds.
+    #
     attr_reader :poll_every
 
+    #
+    # Set the thread up
+    #
     def initialize
       @thread = nil
     end
 
+    # @return [Log4r::Logger]
     def logger
       @logger ||= Log4r::Logger.new(self.class.to_s) 
     end
 
+    # Set the sleep interval between runs of the main loop.  This can be
+    # anything greater than or equal to zero.  If a number less than zero gets
+    # entered, it will be increased to zero.
+    #
+    # @param [Numeric] i The number of seconds to sleep
+    # @raise [ArgumentError] If +i+ is not numeric
+    # @return [Numeric] 
+    #
     def poll_every=(i)
       raise ArgumentError.new("poll_every must be numeric") unless i.is_a?(Numeric)
       # 
@@ -28,60 +49,20 @@ module Mauve
       @poll_every = i
     end
 
-    def run_thread(interval = 5.0)
-      #
-      # Good to go.
-      #
-      @thread = Thread.current
-      self.state = :starting
-
-      @poll_every ||= interval
-      #
-      # Make sure we get a number.
-      #
-      @poll_every = 5 unless @poll_every.is_a?(Numeric)
-
-      rate_limit = 0.1
-
-      while self.state != :stopping do
-
-        self.state = :started if self.state == :starting
-
-        #
-        # Schtop!
-        #
-        if self.state == :freezing
-          self.state = :frozen
-          Thread.stop
-          self.state = :started
-        end
-
-        yield_start = Time.now.to_f
-
-        yield
-
-        #
-        # Ah-ha! Sleep with a break clause.  Make sure we poll every @poll_every seconds.
-        #
-        ((@poll_every.to_f - Time.now.to_f + yield_start.to_f)/rate_limit).
-          round.to_i.times do
-
-          break if self.should_stop?
-
-          #
-          # This is a rate-limiting step
-          #
-          Kernel.sleep rate_limit
-        end
-      end
-
-      self.state = :stopped
-    end
-
+    # This determines if a thread should stop
+    # 
+    # @return [Boolean]
     def should_stop?
       [:freezing, :stopping].include?(self.state)
     end
 
+    # This is the current state of the thread.  It can be one of
+    #   [:stopped, :starting, :started, :freezing, :frozen, :stopping, :killing, :killed]
+    # 
+    # If the thread is not alive it will be +:stopped+.
+    #
+    # @return [Symbol] One of [:stopped, :starting, :started, :freezing,
+    #   :frozen, :stopping, :killing, :killed]
     def state
       if self.alive?
         @thread.key?(:state) ?  @thread[:state] : :unknown
@@ -90,9 +71,18 @@ module Mauve
       end
     end
 
+    # This sets the state of a thread.  It also records the last time the
+    # thread changed status.
+    # 
+    # @param [Symbol] s One of [:stopped, :starting, :started, :freezing,
+    #   :frozen, :stopping, :killing, :killed] 
+    # @raise [ArgumentError] if +s+ is not a valid symbol or the thread is not
+    #   ready
+    # @return [Symbol] the current thread state.
+    #
     def state=(s)
-      raise "Bad state for mauve_thread #{s.inspect}" unless [:stopped, :starting, :started, :freezing, :frozen, :stopping, :killing, :killed].include?(s)
-      raise "Thread not ready yet." unless @thread.is_a?(Thread)
+      raise ArgumentError, "Bad state for mauve_thread #{s.inspect}" unless [:stopped, :starting, :started, :freezing, :frozen, :stopping, :killing, :killed].include?(s)
+      raise ArgumentError, "Thread not ready yet." unless @thread.is_a?(Thread)
 
       unless @thread[:state] == s
         @thread[:state] = s
@@ -103,6 +93,9 @@ module Mauve
       @thread[:state]
     end
 
+    # This returns the time of the last state change, or nil if the thread is dead.
+    #
+    # @return [Time or Nilclass]
     def last_state_change
       if self.alive? and @thread.key?(:last_state_change)
         return @thread[:last_state_change]
@@ -111,6 +104,8 @@ module Mauve
       end
     end
 
+    # This asks the thread to freeze at the next opportunity.
+    #
     def freeze
       self.state = :freezing
       
@@ -119,10 +114,16 @@ module Mauve
       logger.warn("Thread has not frozen!") unless @thread.stop?
     end
 
+    # This returns true if the thread has frozen successfully.
+    #
+    # @return [Boolean]
     def frozen?
       self.stop? and self.state == :frozen
     end
 
+    # This starts the thread.  It wakes it up if it is alive, or starts it from
+    # fresh if it is dead.
+    #
     def run
       if self.alive? 
         # Wake up if we're stopped.
@@ -132,7 +133,7 @@ module Mauve
       else
         @logger = nil
         Thread.new do
-          self.run_thread { self.main_loop } 
+          run_thread { main_loop } 
         end
       end
     end
@@ -140,15 +141,23 @@ module Mauve
     alias start run
     alias thaw  run
 
+    # This checks to see if the thread is alive
+    #
+    # @return [Boolean]
     def alive?
       @thread.is_a?(Thread) and @thread.alive?
     end
 
+    # This checks to see if the thread is stopped
+    #
+    # @return [Boolean]
     def stop?
       self.alive? and @thread.stop?
     end
 
-    def join(ok_exceptions=[])
+    # This joins the thread
+    #
+    def join
       @thread.join if @thread.is_a?(Thread)
     end
 
@@ -156,15 +165,24 @@ module Mauve
 #      @thread.raise(ex)
 #    end
 
+    # This returns the thread's backtrace
+    #
+    # @return [Array or Nilclass]
     def backtrace
       @thread.backtrace if @thread.is_a?(Thread)
     end
 
+    # This restarts the thread
+    #
+    #
     def restart
       self.stop
       self.start
     end
     
+    # This stops the thread
+    #
+    #
     def stop
       self.state = :stopping
 
@@ -183,16 +201,79 @@ module Mauve
 
     alias exit stop
 
+    # This kills the thread -- faster than #stop
+    #
     def kill
       self.state = :killing
       @thread.kill
       self.state = :killed
     end
 
+    # This returns the thread itself.
+    # 
+    # @return [Thread] 
     def thread
       @thread
     end
 
+
+    private
+
+    # This is the main run loop for the thread.  In here are all the calls
+    # allowing use to freeze and thaw the thread neatly.
+    #
+    # This thread will run untill the thread state is changed to :stopping.
+    #
+    def run_thread(interval = 5.0)
+      #
+      # Good to go.
+      #
+      @thread = Thread.current
+      self.state = :starting
+
+      @poll_every ||= interval
+      #
+      # Make sure we get a number.
+      #
+      @poll_every = 5 unless @poll_every.is_a?(Numeric)
+
+      rate_limit = 0.1
+
+      while self.state != :stopping do
+
+        self.state = :started if self.state == :starting
+
+        #
+        # Schtop!
+        #
+        if self.state == :freezing
+          self.state = :frozen
+          Thread.stop
+          self.state = :started
+        end
+
+        yield_start = Time.now.to_f
+
+        yield
+
+        #
+        # Ah-ha! Sleep with a break clause.  Make sure we poll every @poll_every seconds.
+        #
+        ((@poll_every.to_f - Time.now.to_f + yield_start.to_f)/rate_limit).
+          round.to_i.times do
+
+          break if self.should_stop?
+
+          #
+          # This is a rate-limiting step
+          #
+          Kernel.sleep rate_limit
+        end
+      end
+
+      self.state = :stopped
+    end
+
   end
 
 end
diff --git a/lib/mauve/mauve_time.rb b/lib/mauve/mauve_time.rb
index 2d9e293..d2949d9 100644
--- a/lib/mauve/mauve_time.rb
+++ b/lib/mauve/mauve_time.rb
@@ -1,14 +1,19 @@
 require 'date'
 require 'time'
 
-
-# Seconds, minutes, hours, days, and weeks... More than that, we 
-# really should not need it.
+#
+# Extra methods for integer to calculate periods in seconds.
+#
 class Integer
+  # @return [Integer]
   def seconds; self; end
+  # @return [Integer] n minutes of seconds
   def minutes; self*60; end
+  # @return [Integer] n hours of seconds
   def hours; self*3600; end
+  # @return [Integer] n days of seconds
   def days; self*86400; end
+  # @return [Integer] n weeks of seconds
   def weeks; self*604800; end
   alias_method :day, :days
   alias_method :hour, :hours
@@ -16,36 +21,22 @@ class Integer
   alias_method :week, :weeks
 end
 
-class Date
-  def to_time
-    Time.parse(self.to_s)
-  end
-end
-
-class DateTime
-  def to_time
-    Time.parse(self.to_s)
-  end
-
-  def to_s_relative(*args)
-    self.to_s_relative(*args)
-  end
-
-  def to_s_human
-    self.to_s_human
-  end
-
-  def in_x_hours(*args)
-    self.in_x_hours(*args)
-  end
-
-end
-
+#
+# Extra methods for Time.
+#
 class Time
+  #
+  # Method to work out when something is due, with different classes of hours.
+  #
+  # @param [Integer] n The number of hours in the future
+  # @param [String] type One of wallclock, working, or daytime.
+  # 
+  # @return [Time]
+  #
   def in_x_hours(n, type="wallclock")
     t = self.dup
     #
-    # Do this in minutes rather than hours
+    # Do this in seconds rather than hours
     #
     n = n.to_i*3600
   
@@ -103,34 +94,42 @@ class Time
     t
   end
 
+  # Test to see if we're in working hours. The working day is from 8.30am until
+  # 17:00
   #
-  # The working day is from 8.30am until 17:00
-  #
+  # @return [Boolean]
   def working_hours?
     (1..5).include?(self.wday) and ((9..16).include?(self.hour) or  (self.hour == 8 && self.min >= 30))
   end
 
+  # Test to see if it is currently daytime.  The daytime day is 14 hours long
   #
-  # The daytime day is 14 hours long
-  #
+  # @return [Boolean]
   def daytime_hours?
     (8..21).include?(self.hour)
   end
   
+  
+  # We're always in wallclock hours
   #
-  # The daytime day is 14 hours long
-  #
+  # @return [true]
   def wallclock_hours?
     true
   end
   
+  # Test to see if we're in the DEAD ZONE!   This is from 3 - 6am every day.
   #
-  # In the DEAD ZONE! 
-  #
+  # @return [Boolean]
   def dead_zone?
     (3..6).include?(self.hour)
   end
-    
+  
+  # Format the time as a string, relative to +now+
+  #
+  # @param [Time] now The time we're using as a base
+  # @raise [ArgumentError] if +now+ is not a Time
+  # @return [String]
+  #
   def to_s_relative(now = Time.now)
     #
     # Make sure now is the correct class
diff --git a/lib/mauve/notification.rb b/lib/mauve/notification.rb
index 00ce989..920f1b1 100644
--- a/lib/mauve/notification.rb
+++ b/lib/mauve/notification.rb
@@ -6,7 +6,7 @@ module Mauve
   # This class provides an execution context for the code found in 'during'
   # blocks in the configuration file.  This code specifies when an alert
   # should cause notifications to be generated, and can access @time and
-  # @alert variables.  There are also some helper methods to provide
+  # \@alert variables.  There are also some helper methods to provide
   # oft-needed functionality such as hours_in_day.
   #
   # e.g. to send alerts only between 10 and 11 am:
@@ -15,7 +15,7 @@ module Mauve
   #   
   # ... later on ...
   #   
-  #   DuringRunner.new(Time.now, my_alert, &during).inside?
+  #   DuringRunner.new(Time.now, my_alert, &during).now?
   #
   # ... or to ask when an alert will next be cued ...
   #
@@ -28,6 +28,14 @@ module Mauve
 
     attr_reader :time, :alert, :during
 
+    #
+    # Sets up the class
+    #
+    # @param [Time] time The time we're going to test
+    # @param [Mauve::Alert or Nilclass] alert The alert that we can use in tests.
+    # @param [Proc] during The Proc that is evaluated inside the instance to decide if now is now!
+    # @raise [ArgumentError] if +time+ is not a Time
+    #
     def initialize(time, alert=nil, &during)
       raise ArgumentError.new("Must supply time (not #{time.inspect})") unless time.is_a?(Time)
       @time = time
@@ -36,14 +44,21 @@ module Mauve
       @logger = Log4r::Logger.new "Mauve::DuringRunner"
     end
     
+    # This evaluates the +during+ block, returning the result.
     #
-    #
-    #
+    # @param [Time] t Set the time at which to evaluate the +during+ block.
+    # @return [Boolean]
     def now?(t=@time)
       @test_time = t
-      res = instance_eval(&@during)
+      instance_eval(&@during) ? true : false
     end
 
+    # This finds the next occurance of the +during+ block evaluating to true.
+    # It returns nil if an occurence cannot be found within the next 8 days.
+    #
+    # @param [Integer] after Skip time forward this many seconds before starting
+    # @return [Time or nil]
+    #
     def find_next(after = 0)
       t = @time+after
       #
@@ -86,18 +101,28 @@ module Mauve
     
     protected
 
+    # Returns true if the current hour is in the list of hours given.
+    # 
+    # @param [Array] hours List of hours (as Integers)
+    # @return [Boolean]
     def hours_in_day(*hours)
       @test_time = @time if @test_time.nil?
       x_in_list_of_y(@test_time.hour, hours.flatten)
-    end
-    
+    end   
+ 
+    # Returns true if the current day is in the list of days given
+    #
+    # @param [Array] days List of days (as Integers)
+    # @return [Boolean]
     def days_in_week(*days)
       @test_time = @time if @test_time.nil?
       x_in_list_of_y(@test_time.wday, days.flatten)
     end
     
-    ## Return true if the alert has not been acknowledged within a certain time.
-    # 
+    # Tests if the alert has not been acknowledged within a certain time.
+    #
+    # @param [Integer] seconds Number of seconds
+    # @return [Boolean]
     def unacknowledged(seconds)
       @test_time = @time if @test_time.nil?
       @alert &&
@@ -106,6 +131,11 @@ module Mauve
         (@test_time - @alert.raised_at) >= seconds
     end
     
+    # Checks to see if x is contained in y
+    #
+    # @param [Array] y Array to search for +x+
+    # @param [Object] x
+    # @return [Boolean]
     def x_in_list_of_y(x,y)
       y.any? do |range|
         if range.respond_to?("include?")
@@ -116,16 +146,17 @@ module Mauve
       end
     end
 
+    # Test to see if we're in working hours.  See Time#working_hours?
+    #
+    # @return [Boolean]
     def working_hours? 
       @test_time = @time if @test_time.nil?
       @test_time.working_hours?
     end
 
-    # Return true in the dead zone between 3 and 7 in the morning.
+    # Test to see if we're in the dead zone.  See Time#dead_zone?
     #
-    # Nota bene that this is used with different times in the reminder section.
-    #
-    # @return [Boolean] Whether now is a in the dead zone or not.
+    # @return [Boolean]
     def dead_zone?
       @test_time = @time if @test_time.nil?
       @test_time.dead_zone?
@@ -139,20 +170,31 @@ module Mauve
   #
   class Notification < Struct.new(:people, :level, :every, :during, :list)
 
-    def to_s
-      "#<Notification:of #{people.map { |p| p.username }.join(',')} at level #{level} every #{every}>"
-    end
- 
-    attr_reader :thread_list
-
+    # Set up a new notification
+    #
+    # @param [Array] people List of Mauve::Person to notify
+    # @param [Symbol] level Level at which to notify
     def initialize(people, level)
       self.level = level
       self.every = 300
       self.people = people
     end
 
+    # @return [String]
+    def to_s
+      "#<Notification:of #{people.map { |p| p.username }.join(',')} at level #{level} every #{every}>"
+    end
+
+    # @return Log4r::Logger 
     def logger ;  Log4r::Logger.new self.class.to_s ; end
 
+    # Push a notification on to the queue for this alert.  The Mauve::Notifier
+    # will then pop it off and do the notification in a separate thread.
+    #
+    # @param [Mauve::Alert or Mauve::AlertChanged] alert The alert in question
+    # @param [Array] already_sent_to A list of people that have already received this alert.
+    #
+    # @return [Array] The list of people that have received this alert.
     def notify(alert, already_sent_to = [])
 
       if people.nil? or people.empty?
@@ -187,7 +229,13 @@ module Mauve
 
       return already_sent_to
     end
-    
+   
+    # Work out when this notification should next get sent.  Nil will be
+    # returned if the alert is not raised.
+    #
+    # @param [Mauve::Alert] alert The alert in question
+    # @return [Time or nil] The time a reminder should get sent, or nil if it
+    #   should never get sent again.
     def remind_at_next(alert)
       return nil unless alert.raised?
 
diff --git a/lib/mauve/notifier.rb b/lib/mauve/notifier.rb
index 2853485..14e188c 100644
--- a/lib/mauve/notifier.rb
+++ b/lib/mauve/notifier.rb
@@ -4,33 +4,45 @@ require 'mauve/notifiers/xmpp'
 
 module Mauve
 
+  # The Notifier is reponsible for popping notifications off the
+  # notification_buffer run by the Mauve::Server instance.  This ensures that
+  # notifications are sent in a separate thread to the main processing /
+  # updating threads, and stops notifications delaying updates.
+  #
+  #
   class Notifier < MauveThread
     
     include Singleton
 
-    def main_loop
-      # 
-      # Cycle through the buffer.
-      #
-      sz = Server.notification_buffer_size
+    # Stop the notifier thread.  This just makes sure that all the
+    # notifications in the buffer have been sent before closing the XMPP
+    # connection.
+    #
+    def stop
+      super
 
-      # Thread.current[:notification_threads] ||= []
-      logger.info "Sending #{sz} alerts" if sz > 0
-  
-      sz.times do
-        person, *args = Server.notification_pop
-        
-        #
-        # Nil person.. that's craaazy too!
-        #
-        next if person.nil?
+      #
+      # Flush the queue.
+      #
+      main_loop
 
-        person.send_alert(*args) 
+      if Configuration.current.notification_methods['xmpp']
+        Configuration.current.notification_methods['xmpp'].close
       end
+
     end
 
-    def start
-      if Configuration.current.notification_methods['xmpp']
+    private
+
+    # This is the main loop that is executed in the thread.
+    #
+    #
+    def main_loop
+
+      #
+      # Make sure we're connected to the XMPP server if needed on every iteration.
+      #
+      if Configuration.current.notification_methods['xmpp'] and !Configuration.current.notification_methods['xmpp'].ready?
         #
         # Connect to XMPP server
         #
@@ -41,37 +53,48 @@ module Mauve
           # 
           # Ignore people without XMPP stanzas.
           #
-          next unless person.xmpp
+          next unless person.xmpp 
+
+          #
+          # Can't do this unless we're ready.
+          #
+          next unless xmpp.ready?
 
           #
           # For each JID, either ensure they're on our roster, or that we're in
           # that chat room.
           #
           jid = if xmpp.is_muc?(person.xmpp)
-            xmpp.join_muc(person.xmpp) 
+            xmpp.join_muc(person.xmpp)
           else
             xmpp.ensure_roster_and_subscription!(person.xmpp)
           end
 
           Configuration.current.people[username].xmpp = jid unless jid.nil?
         end
+
       end
 
-      super
-    end
+      # 
+      # Cycle through the buffer.
+      #
+      sz = Server.notification_buffer_size
 
-    def stop
-      super
+      logger.info "Sending #{sz} alerts" if sz > 0
 
       #
-      # Flush the queue.
+      # Empty the buffer, one notification at a time.
       #
-      main_loop
+      sz.times do
+        person, *args = Server.notification_pop
+        
+        #
+        # Nil person.. that's craaazy too!
+        #
+        next if person.nil?
 
-      if Configuration.current.notification_methods['xmpp']
-        Configuration.current.notification_methods['xmpp'].close
+        person.send_alert(*args) 
       end
-
     end
 
   end
diff --git a/lib/mauve/notifiers.rb b/lib/mauve/notifiers.rb
index 7ba1d71..7276091 100644
--- a/lib/mauve/notifiers.rb
+++ b/lib/mauve/notifiers.rb
@@ -1,6 +1,13 @@
-# encoding: UTF-8
 require 'mauve/notifiers/email'
 require 'mauve/notifiers/sms_default'
 require 'mauve/notifiers/sms_aql'
 require 'mauve/notifiers/xmpp'
 
+module Mauve
+  #
+  # This is where the various notifiers are kept.
+  #
+  module Notifiers
+
+  end
+end
diff --git a/lib/mauve/notifiers/email.rb b/lib/mauve/notifiers/email.rb
index 3134135..8efdbec 100644
--- a/lib/mauve/notifiers/email.rb
+++ b/lib/mauve/notifiers/email.rb
@@ -30,10 +30,14 @@ module Mauve
 
         def logger
           @logger ||= Log4r::Logger.new self.class.to_s.sub(/::Default$/,"")
-
         end
 
         def send_alert(destination, alert, all_alerts, conditions = {})
+
+          logger.debug [destination, alert, all_alerts, conditions]
+
+          return false if destination.nil?
+
           message = prepare_message(destination, alert, all_alerts, conditions)
           args  = [@server, @port]
           args += [@username, @password, @login_method.to_sym] if @login_method
diff --git a/lib/mauve/notifiers/xmpp.rb b/lib/mauve/notifiers/xmpp.rb
index 5ffe8f4..ae9734f 100644
--- a/lib/mauve/notifiers/xmpp.rb
+++ b/lib/mauve/notifiers/xmpp.rb
@@ -85,15 +85,25 @@ module Mauve
           @client = nil
         end
 
+        # The logger instance
+        # 
+        # @return [Log4r::Logger]
         def logger
           # Give the logger a sane name
           @logger ||= Log4r::Logger.new self.class.to_s.sub(/::Default$/,"")
         end
        
+        # Sets the client's JID
+        #
+        # @param [String] jid The JID required.
+        # @return [Jabber::JID] The client JID.
         def jid=(jid)
           @jid = JID.new(jid)
         end
- 
+
+        # Connects to the XMPP server, and sets up the roster
+        #
+        # @return [Jabber::Client, NilClass] The connected client, or nil in the case of failure
         def connect
           logger.debug "Starting connection to #{@jid}"
 
@@ -156,13 +166,14 @@ module Mauve
           @client = nil
         end  
 
-        #
-        # Kills the processor thread
-        #
         def stop
           @client.stop
         end
-
+  
+        #
+        # Closes the XMPP connection, if possible.  Sets @client to nil.
+        #
+        # @return [NilClass]
         def close
           @closing = true
           if @client 
@@ -177,27 +188,32 @@ module Mauve
           @client = nil
         end
 
+        # Determines if the client is ready.
+        #
+        # @return [Boolean]
         def ready?
           @client.is_a?(Jabber::Client) and @client.is_connected?
         end
         
-        # 
-        # Takes an alert and converts it into a message.
-        #
-        def convert_alert_to_message(alert)
-        end
-
         # Attempt to send an alert using XMPP. 
-        # +destination+ is the JID you're sending the alert to. This should be
-        # a bare JID in the case of an individual, or muc:<room>@<server> for 
-        # chatrooms (XEP0045). The +alert+ object is turned into a pretty
-        # message and sent to the destination as a message, if the +conditions+
-        # are met. all_alerts are currently ignored.
         #
-        # The only suported condition at the moment is :if_presence => [choices]
-        # which checks whether the jid in question has a presence matching one
-        # or more of the choices - see +check_jid_has_presence+ for options.
-
+        # @param [String] destination The JID you're sending the alert to. This should be
+        #   a bare JID in the case of an individual, or +muc:room@server+ for
+        #   chatrooms (XEP0045).
+        #
+        # @param [Mauve::Alert] alert This is turned into a pretty
+        #   message and sent to the destination as a message, if +conditions+
+        #   are met.
+        #
+        # @param [Array] all_alerts Currently ignored.
+        #
+        # @param [Hash] conditions Conditions that determine if an alert should be sent
+        #
+        # @option conditions [Array] :if_presence Checks whether the jid in question
+        #   has a presence matching one or more of the choices - see
+        #   Mauve::Notifiers::Xmpp::Default#check_jid_has_presence for options.
+        #
+        # @return [Boolean] 
         def send_alert(destination, alert, all_alerts, conditions = {})
           destination_jid = JID.new(destination)         
  
@@ -650,7 +666,6 @@ EOF
         #   :unavailable -                  - jabber status is away, dnd or xa
         #   :unknown                        - don't know (not in roster)
         #
-        # For MUCs: TODO
         # Returns true if at least one of the presence specifiers for the jid
         # is met, false otherwise. Note that if the alerter can't see the alertee's
         # presence, only 'unknown' will match - generally, you'll want [:online, :unknown]
diff --git a/lib/mauve/people_list.rb b/lib/mauve/people_list.rb
index b15db3f..6b2ba33 100644
--- a/lib/mauve/people_list.rb
+++ b/lib/mauve/people_list.rb
@@ -4,14 +4,18 @@ require 'mauve/calendar_interface'
 
 module Mauve 
 
-  # Stores a list of name.
+  # Stores a list of Mauve::Person
+  #
   #
-  # @author Yann Golanski
   class PeopleList 
 
     attr_reader :label, :list
 
-    # Default contrustor.
+    # Create a new list
+    #
+    # @param [String] label The name of the list
+    # @raise [ArgumentError] if the label is not a string
+    #
     def initialize(label)
       raise ArgumentError, "people_list label must be a string" unless label.is_a?(String)
       @label = label
@@ -20,6 +24,10 @@ module Mauve
 
     alias username label
 
+    # Append an Array or String to a list
+    #
+    # @param [Array or String] arr
+    # @return [Mauve::PeopleList] self
     def +(arr)
       case arr
         when Array
@@ -44,15 +52,14 @@ module Mauve
 
     alias add_to_list +
 
-    #
-    # Set up the logger
+    # @return Log4r::Logger
     def logger
       @logger ||=  Log4r::Logger.new self.class.to_s
     end
 
-    #
     # Return the array of people
     #
+    # @return [Array]
     def people
 
       l = list.collect do |name|
diff --git a/lib/mauve/person.rb b/lib/mauve/person.rb
index 0df31ee..acab8b7 100644
--- a/lib/mauve/person.rb
+++ b/lib/mauve/person.rb
@@ -6,7 +6,19 @@ module Mauve
   class Person < Struct.new(:username, :password, :holiday_url, :urgent, :normal, :low, :email, :xmpp, :sms)
   
     attr_reader :notification_thresholds, :last_pop3_login, :suppressed
-  
+ 
+    # Set up a new Person
+    #
+    # @param [Hash] args The options for setting up the person
+    #   @option args [String] :username The person's username
+    #   @option args [String] :password The SHA1 sum of the person's password
+    #   @option args [String] :holiday_url The URL that can be checked by Mauve::CalendarInterface#is_user_on_holiday?
+    #   @option args [Proc] :urgent The block to execute when an urgent-level notification is issued
+    #   @option args [Proc] :normal The block to execute when an normal-level notification is issued
+    #   @option args [Proc] :low The block to execute when an low-level notification is issued
+    #   @option args [String] :email The person's email address
+    #   @option args [String] :sms The person's mobile number
+    # 
     def initialize(*args)
       @notification_thresholds = nil
       @suppressed = false
@@ -17,13 +29,19 @@ module Mauve
       super(*args)
     end
    
+    # @return Log4r::Logger
     def logger ; @logger ||= Log4r::Logger.new self.class.to_s ; end
 
+    # Determines if notifications to the user are currently suppressed
+    #
+    # @return [Boolean]
     def suppressed? ; @suppressed ; end
  
+    # Works out if a notification should be suppressed.  If no parameters are supplied, it will 
     #
-    # This 
-    #
+    # @param [Time] Theoretical time of notification
+    # @param [Time] Current time.
+    # @return [Boolean] If suppression is needed.
     def should_suppress?(with_notification_at = nil, now = Time.now)
 
       return self.notification_thresholds.any? do |period, previous_alert_times|
@@ -42,10 +60,10 @@ module Mauve
       end
     end
    
+    # The notification thresholds for this user
+    #
+    # @return [Hash]
     def notification_thresholds
-      #
-      # By default send 10 thresholds in a minute maximum
-      #
       @notification_thresholds ||= { } 
     end
  
@@ -54,6 +72,13 @@ module Mauve
     # 
     class NotificationCaller
 
+      # Set up the notification caller
+      #
+      # @param [Mauve::Person] person
+      # @param [Mauve::Alert] alert
+      # @param [Array] other_alerts
+      # @param [Hash] base_conditions
+      #
       def initialize(person, alert, other_alerts, base_conditions={})
         @person = person
         @alert = alert
@@ -61,40 +86,52 @@ module Mauve
         @base_conditions = base_conditions
       end
       
+      # @return Log4r::Logger
       def logger ; @logger ||= Log4r::Logger.new self.class.to_s ; end
 
+      # This method makes sure things like +xmpp+ and +email+ work.
       #
-      # This method makes sure things like
-      #
-      #   xmpp
-      #
-      #  works
+      # @param [String] name The notification method to use
+      # @param [Array or Hash] args Extra conditions to pass to this notification method
       #
+      # @return [Boolean] if the notifcation has been successful
       def method_missing(name, *args)
         #
+        # Work out the notification method
+        #
+        notification_method = Configuration.current.notification_methods[name.to_s]
+
+        @logger.warn "Notification method '#{name}' not defined  (#{@person.username})" if notification_method.nil?
+
+        #
         # Work out the destination
         #
         if args.first.is_a?(String)
           destination = args.pop
-        else 
+        elsif @person.respond_to?(name)
           destination = @person.__send__(name)
+        else
+          destination = nil
         end
 
+        @logger.warn "#{name} destination for #{@person.username} not set" if destination.nil?
+
         if args.first.is_a?(Array)
           conditions  = @base_conditions.merge(args[0])
         else
           conditions  = @base_conditions
         end
 
-        notification_method = Configuration.current.notification_methods[name.to_s]
-
-        raise NoMethodError.new("#{name} not defined as a notification method") unless notification_method
 
-        # Methods are expected to return true or false so the user can chain
-        # them together with || as fallbacks.  So we have to catch exceptions
-        # and turn them into false.
-        #
-        res = notification_method.send_alert(destination, @alert, @other_alerts, conditions)
+        if notification_method and destination 
+          # Methods are expected to return true or false so the user can chain
+          # them together with || as fallbacks.  So we have to catch exceptions
+          # and turn them into false.
+          #
+          res = notification_method.send_alert(destination, @alert, @other_alerts, conditions)
+        else
+          res = false
+        end
 
         #
         # Log the result
@@ -108,10 +145,12 @@ module Mauve
 
     end 
 
-    #
-    #
     # Sends the alert
     #
+    # @param [Symbol] level Level at which the alert should be sent
+    # @param [Mauve::Alert] alert Alert we're notifiying about
+    #
+    # @return [Boolean] if the notification was successful
     def send_alert(level, alert)
       now = Time.now
 
@@ -132,8 +171,6 @@ module Mauve
         return true 
       end
 
-      # FIXME current_alerts is very slow.  So much so it slows everything
-      # down.  A lot.  
       result = NotificationCaller.new(
         self,
         alert,
@@ -143,7 +180,7 @@ module Mauve
          :was_suppressed => was_suppressed, }
       ).instance_eval(&__send__(level))
 
-      if result
+      if [result].flatten.any?
         # 
         # Remember that we've sent an alert
         #
@@ -168,6 +205,7 @@ module Mauve
     # This is currently very CPU intensive, and slows things down a lot.  So
     # I've commented it out when sending notifications.
     #
+    # @return [Array] alerts relevant to this person
     def current_alerts
       Alert.all_raised.select do |alert|
         my_last_update = AlertChanged.first(:person => username, :alert_id => alert.id)
diff --git a/lib/mauve/pop3_server.rb b/lib/mauve/pop3_server.rb
index 645fe0d..52f31d0 100644
--- a/lib/mauve/pop3_server.rb
+++ b/lib/mauve/pop3_server.rb
@@ -4,25 +4,41 @@ require 'digest/sha1'
 
 module Mauve
   # 
-  # API to control the web server
+  # The POP3 server, where messages can also be read.
   #
   class Pop3Server < MauveThread
 
     include Singleton
 
     attr_reader :port, :ip
-    
+
+    # Initialize the server
+    #
+    # Default port is 1110
+    # Default IP is 0.0.0.0
+    #
     def initialize
       super
       self.port = 1110
       self.ip = "0.0.0.0"
     end
    
+    #
+    # Set the port
+    #
+    # @param [Integer] pr
+    # @raise [ArgumentError] if the port is not sane
+    # ~
     def port=(pr)
       raise ArgumentError, "port must be an integer between 0 and #{2**16-1}" unless pr.is_a?(Integer) and pr < 2**16 and pr > 0
       @port = pr
     end
     
+    #
+    # Set the IP address.  Unfortunately IPv6 is not OK.
+    #
+    # @param [String] i The IP address required.
+    #
     def ip=(i)
       raise ArgumentError, "ip must be a string" unless i.is_a?(String)
       #
@@ -32,22 +48,15 @@ module Mauve
 
       @ip = i
     end
-
+    
+    # @return [Log4r::Logger]
     def logger
       @logger ||= Log4r::Logger.new(self.class.to_s)
     end
 
-    def main_loop
-      unless @server and @server.running?
-        @server = Mauve::Pop3Backend.new(@ip.to_s, @port)
-        logger.info "Listening on #{@server.to_s}"
-        #
-        # The next statment doesn't return.
-        #
-        @server.start
-      end
-    end
-
+    #
+    # This stops the server
+    #
     def stop
       if @server.running?
         @server.stop
@@ -58,25 +67,50 @@ module Mauve
       super
     end
 
+    #
+    # This stops the server faster than stop
+    #
     def join
       @server.stop! if @server
 
       super
     end
 
+    private
+
+    #
+    # This tarts the server, and keeps it going.
+    #
+    def main_loop
+      unless @server and @server.running?
+        @server = Mauve::Pop3Backend.new(@ip.to_s, @port)
+        logger.info "Listening on #{@server.to_s}"
+        #
+        # The next statment doesn't return.
+        #
+        @server.start
+      end
+    end
+
   end    
 
+  #
+  # This is the Pop3 Server itself.  It is based on the Thin HTTP server, and hence EventMachine.
+  #
   class Pop3Backend < Thin::Backends::TcpServer
 
+    #
+    # @return [Log4r::Logger]
     def logger
       @logger ||= Log4r::Logger.new(self.class.to_s)
     end
         
-    # Connect the server
+    # Initialize a new connection to the server
     def connect
       @signature = EventMachine.start_server(@host, @port, Pop3Connection)
     end
         
+    # Disconnect the server, but only if EventMachine is still going.
     def disconnect
       #
       # Only do this if EventMachine is still going.. The http_server may have
@@ -87,17 +121,25 @@ module Mauve
 
   end
 
-
+  #
+  # This class represents and individual connection, and understands some POP3
+  # commands.
+  #
   class Pop3Connection < EventMachine::Connection
 
+    # The username
     attr_reader :user
 
+    # Default CR+LF combo.
     CRLF = "\r\n"
 
+    # @return [Log4r::Logger]
     def logger
       @logger ||= Log4r::Logger.new(self.class.to_s)
     end
 
+    # This is called once the connection has been established.  It says hello
+    # to the client, and resets the state.
     def post_init
       logger.info "New connection"
       send_data "+OK #{self.class.to_s} started"
@@ -107,6 +149,11 @@ module Mauve
       @level    = nil
     end
 
+    # This returns a list of commands allowed in a state.
+    #
+    # @param [Symbol] The state to query, defaults to the current state.
+    # @return [Array] An array of permitted comands.
+    #
     def permitted_commands(state=@state)
      case @state
         when :authorization
@@ -118,6 +165,10 @@ module Mauve
       end
     end
 
+    # This returns a list of capabilities in a given state.
+    #
+    # @param [Symbol] The state to query, defaults to the current state.
+    # @return [Array] An array of capabilities.
     def capabilities(state=@state)
      case @state
         when :transaction
@@ -129,6 +180,27 @@ module Mauve
       end
     end
 
+    # This method handles a command, and parses it.
+    #
+    # The following POP3 commands are understood:
+    #   QUIT
+    #   USER
+    #   PASS
+    #   STAT
+    #   LIST
+    #   RETR
+    #   DELE
+    #   NOOP
+    #   RSET
+    #   CAPA
+    #   UIDL
+    #
+    # The command is checked against a list of permitted commands, given the
+    # state of the connection, and returns an error if the command is
+    # forbidden.
+    #
+    # @param [String] data The data to process.
+    #
     def receive_data (data)
       data.split(CRLF).each do |cmd|
         break if error?
@@ -165,16 +237,39 @@ module Mauve
         end
       end
     end
-  
+ 
+    # This sends the data back to the user.  A CR+LF is joined to the end of
+    # the data.
+    #
+    # @param [String] d The data to send back.
     def send_data(d)
       d += CRLF
       super unless error?
     end
 
+    private
+
+    # This deals with CAPA, returning a string of capabilities in the current
+    # connection state.
+    #
+    # @param [String] a The complete CAPA command sent by the client.
+    #
     def do_process_capa(a)
       send_data (["+OK Capabilities follow:"] + self.capabilities + ["."]).join(CRLF)
     end
 
+    # This deals with the USER command.
+    #
+    # Any of low, normal, urgent can be appended to the username, to select
+    # only alarms of that level to be shown.
+    #
+    # e.g.
+    #   patrick+low
+    #
+    # will show only alerts of a LOW level.
+    #
+    # @param [String] s The complete USER command sent by the client.
+    #
     def do_process_user(s)
       allowed_levels = Mauve::AlertGroup::LEVELS.collect{|l| l.to_s}
 
@@ -195,6 +290,10 @@ module Mauve
       end
     end
 
+    # This processes the PASS command.  It uses the Mauve::Authenticate class
+    # to authenticate the user.  Once authenticated, the state is set to :transaction.
+    #
+    # @param [String] s The complete PASS command sent by the client.
     def do_process_pass(s)
       
       if @user and s =~ /\APASS +(\S+)/
@@ -209,16 +308,27 @@ module Mauve
       end
     end
 
+    #
+    # This just sends an "ERR Unknown command" string back to the user.
+    #
+    # @param [String] a The complete command from the client that caused this error.
     def do_process_error(a)
       send_data "-ERR Unknown comand."
     end
 
+    # This does a NOOP.
+    #
+    # @param [String] a The complete NOOP command from the client.
     def do_process_noop(a)
       send_data "+OK Thanks."
     end
 
+    # Delete is processed as a NOOP
     alias do_process_dele do_process_noop
 
+    # This logs a user out, and closes the connection.  The state is set to :update.
+    #
+    # @param [String] a The complete QUIT command from the client.
     def do_process_quit(a)
       @state = :update
 
@@ -227,10 +337,17 @@ module Mauve
       close_connection_after_writing
     end
 
+    # This sends the number of messages, and their size back to the client.
+    #
+    # @param [String] a The complete STAT command from the client.
     def do_process_stat(a)
       send_data "+OK #{self.messages.length} #{self.messages.inject(0){|s,m| s+= m[1].length}}"
     end
 
+    # This sends a list of the messages back to the client.
+    #
+    # @param [String] a The complete LIST command from the client.
+    #
     def do_process_list(a)
       d = []
       if a =~ /\ALIST +(\d+)\b/
@@ -249,6 +366,9 @@ module Mauve
       send_data d.join(CRLF)
     end
 
+    # This sends the UID of a message back to the client.
+    #
+    # @param [String] a The complete UIDL command from the client.
     def do_process_uidl(a)
       if a =~ /\AUIDL +(\d+)\b/
         ind = $1.to_i
@@ -267,6 +387,10 @@ module Mauve
       end
     end
 
+    # This retrieves a message for the client.
+    #
+    # @param [String] a The complete RETR command from the client.
+    #
     def do_process_retr(a)
       if a =~ /\ARETR +(\d+)\b/
         ind = $1.to_i
@@ -287,7 +411,11 @@ module Mauve
     end
 
     #
-    # These are the messages in the mailbox.
+    # These are the messages in the mailbox.  It looks for the first 100 alert_changed, and formats them into emails, and returns an array of
+    #
+    #  [alert_changed, email]
+    #
+    # @return [Array] Array of alert_changeds and emails.
     #
     def messages
       if @messages.empty?
diff --git a/lib/mauve/processor.rb b/lib/mauve/processor.rb
index d68c551..c8a1dfb 100644
--- a/lib/mauve/processor.rb
+++ b/lib/mauve/processor.rb
@@ -4,12 +4,23 @@ require 'mauve/mauve_thread'
 
 module Mauve
 
+  #
+  # This class is a singlton thread which pops updates off the
+  # Server#packet_buffer and processes them as alert updates.
+  #
+  # It is responsible for de-bouncing updates, i.e. ones with duplicate
+  # transmission IDs.
+  #
   class Processor < MauveThread
 
     include Singleton
 
+    # This is the time after which transmission IDs are expired.
+    #
     attr_reader :transmission_cache_expire_time
 
+    # Initialize the processor
+    #
     def initialize
       super
       #
@@ -20,15 +31,58 @@ module Mauve
       @transmission_cache_checked_at = Time.now
     end
 
+    # @return [Log4r::Logger]
     def logger
       @logger ||= Log4r::Logger.new(self.class.to_s)
     end
 
+    # Set the expiry time
+    #
+    # @param [Integer] i The number of seconds after which transmission IDs are considered unseen.
+    # @raise [ArgumentError] If +i+ is not an Integer
     def transmission_cache_expire_time=(i)
       raise ArgumentError, "transmission_cache_expire_time must be an integer" unless i.is_a?(Integer)
       @transmission_cache_expire_time = i
     end
 
+    # This expries the transmission cache
+    #
+    #
+    def expire_transmission_id_cache
+      now = Time.now
+      #
+      # Only check once every minute.
+      #
+      return unless (now - @transmission_cache_checked_at) > 60
+
+      to_delete = []
+
+      @transmission_id_cache.each do |tid, received_at|
+        to_delete << tid if (now - received_at) > @transmission_cache_expire_time
+      end
+
+      to_delete.each do |tid|
+        @transmission_id_cache.delete(tid)
+      end
+      
+      @transmission_cache_checked_at = now
+    end
+
+    # This stops the processor, making sure all pending updates are saved.
+    #
+    def stop
+      super
+
+      # 
+      # flush the queue
+      #
+      main_loop
+    end
+
+    private
+
+    # This is the main loop that does the processing.
+    #
     def main_loop
       
       sz = Server.packet_buffer_size
@@ -92,33 +146,7 @@ module Mauve
       Timer.instance.thaw if Timer.instance.frozen?
     end
 
-    def expire_transmission_id_cache
-      now = Time.now
-      #
-      # Only check once every minute.
-      #
-      return unless (now - @transmission_cache_checked_at) > 60
-
-      to_delete = []
-
-      @transmission_id_cache.each do |tid, received_at|
-        to_delete << tid if (now - received_at) > @transmission_cache_expire_time
-      end
-
-      to_delete.each do |tid|
-        @transmission_id_cache.delete(tid)
-      end
-      
-      @transmission_cache_checked_at = now
-    end
-
-    def stop
-      super
-
-      # 
-      # flush the queue
-      #
-      main_loop
-    end
   end   
+
 end
+
diff --git a/lib/mauve/sender.rb b/lib/mauve/sender.rb
index 6685de5..c84dcb0 100644
--- a/lib/mauve/sender.rb
+++ b/lib/mauve/sender.rb
@@ -4,12 +4,40 @@ require 'socket'
 require 'mauve/mauve_resolv'
 require 'mauve/mauve_time'
 
-module Mauve 
+module Mauve
+  #
+  # This is the class that send the Mauve packets.
+  #
   class Sender
+    #
+    # This is the default mauve receiving port.
+    #
     DEFAULT_PORT = 32741
 
     include Resolv::DNS::Resource::IN
-    
+
+    # Set up a new sender.  It takes a list of destinations and uses DNS to
+    # resolve names to addresses.
+    #
+    # A destination can look like
+    #
+    #   1.2.3.4:5678
+    #   1.2.3.4
+    #   [2001:1af:ba8::dead]:5678
+    #   [2001:1af:ba8::dead]
+    #   mauve.host:5678
+    #   mauve.host
+    #
+    # If no port is specified, DEFAULT_PORT is used.
+    #
+    # If a hostname is used, SRV records are used, with the prefix
+    # +_mauvealert._udp+ to determine the real hostname and port to which
+    # alerts should be sent.
+    #
+    # Otherwise AAAA and A records are looked up.
+    #
+    # @param [Array] destinations List of destinations to which the update is to be sent.
+    #
     def initialize(*destinations)
       destinations = destinations.flatten
       
@@ -101,9 +129,12 @@ module Mauve
 
     end
 
+    # Send an update.
     #
-    # Returns the number of packets sent.
+    # @param [Mauve::Proto] update The update to send
+    # @param [Integer] vebose The verbosity -- higher is more.
     #
+    # @return [Integer] the number of packets sent.
     def send(update, verbose=0)
 
       #
diff --git a/lib/mauve/server.rb b/lib/mauve/server.rb
index a217aab..41a76dc 100644
--- a/lib/mauve/server.rb
+++ b/lib/mauve/server.rb
@@ -25,11 +25,14 @@ module Mauve
     #
     THREAD_CLASSES = [UDPServer, HTTPServer, Pop3Server, Processor, Timer, Notifier, Heartbeat]
 
-    attr_reader :hostname, :database, :initial_sleep
+    attr_reader   :hostname, :database, :initial_sleep
     attr_reader   :packet_buffer, :notification_buffer, :started_at
 
     include Singleton
 
+    # Initialize the Server, setting up a blank configuration if no
+    # configuration has been created already.
+    #
     def initialize
       super
       @hostname    = "localhost"
@@ -51,29 +54,47 @@ module Mauve
       Configuration.current = Configuration.new if Mauve::Configuration.current.nil?
     end
 
+    # Set the hostname of this Mauve instance.
+    #
+    # @param [String] h The hostname
     def hostname=(h)
       raise ArgumentError, "hostname must be a string" unless h.is_a?(String)
       @hostname = h
     end
 
+    # Set the database
+    #
+    # @param [String] d The database
     def database=(d)
       raise ArgumentError, "database must be a string" unless d.is_a?(String)
       @database = d
     end
-
+    
+    # Set the sleep period during which notifications about old alerts are
+    # suppressed.
+    #
+    # @param [Integer] s The initial sleep period.
     def initial_sleep=(s)
       raise ArgumentError, "initial_sleep must be numeric" unless s.is_a?(Numeric)
       @initial_sleep = s
     end
 
+    # Test to see if we should suppress alerts because we're in the initial sleep period
+    #
+    # @return [Boolean]
     def in_initial_sleep?
       Time.now < self.started_at + self.initial_sleep
     end
 
+    # return [Log4r::Logger]
     def logger
       @logger ||= Log4r::Logger.new(self.class.to_s)
     end
 
+    # This sorts out the Server.  It empties the notification and packet
+    # buffers.  It configures and migrates the database.
+    #  
+    # @return [NilClass]
     def setup
       #
       #
@@ -103,15 +124,45 @@ module Mauve
       return nil
     end
 
+    # This sets up the server, and then starts the main loop.
+    #
     def start
 #      self.state = :starting
 
-      self.setup
+      setup
       
-      self.run_thread { self.main_loop }
+      run_thread { main_loop }
     end
 
     alias run start 
+    
+    #
+    # This stops the main loop, and all the threads that are defined in THREAD_CLASSES above.
+    #
+    def stop
+      if self.state == :stopping
+        # uh-oh already told to stop.
+        logger.error "Stop already called.  Killing self!"
+        Kernel.exit 1 
+      end
+
+      self.state = :stopping
+
+      THREAD_CLASSES.each do |klass|
+        klass.instance.stop unless klass.instance.nil?
+      end
+      
+      thread_list = Thread.list 
+      thread_list.delete(Thread.current)
+
+      thread_list.each do |t|
+        t.exit
+      end      
+
+      self.state = :stopped
+    end
+
+    private
 
     def main_loop
       thread_list = Thread.list 
@@ -185,29 +236,6 @@ module Mauve
       end
     end
     
-    def stop
-      if self.state == :stopping
-        # uh-oh already told to stop.
-        logger.error "Stop already called.  Killing self!"
-        Kernel.exit 1 
-      end
-
-      self.state = :stopping
-
-      THREAD_CLASSES.each do |klass|
-        klass.instance.stop unless klass.instance.nil?
-      end
-      
-      thread_list = Thread.list 
-      thread_list.delete(Thread.current)
-
-      thread_list.each do |t|
-        t.exit
-      end      
-
-      self.state = :stopped
-    end
-
 
     class << self
 
@@ -218,17 +246,23 @@ module Mauve
       # processing them crash, the buffer itself is not lost with the thread.
       #
 
-      #
-      # These methods pop things on and off the packet_buffer
-      #
+      # Push a packet onto the back of the +packet_buffer+
+      # 
+      # @param [String] a Packet from the UDP server
       def packet_enq(a)
         instance.packet_buffer.push(a)
       end
 
+      # Shift a packet off the front of the +packet buffer+
+      #
+      # @return [String] the oldest UDP packet
       def packet_deq
         instance.packet_buffer.shift
       end
 
+      # Returns the current length of the +packet_buffer+
+      #
+      # @return [Integer}
       def packet_buffer_size
         instance.packet_buffer.size
       end
@@ -236,17 +270,23 @@ module Mauve
       alias packet_push packet_enq
       alias packet_pop  packet_deq
       
+      # Push a notification on to the back of the +notification_buffer+
       #
-      # These methods pop things on and off the notification_buffer
-      #
+      # @param [Array] a Notification array, consisting of a Person and the args to Mauve::Person#send_alert
       def notification_enq(a)
         instance.notification_buffer.push(a)
       end
 
+      # Shift a notification off the front of the +notification_buffer+
+      #
+      # @return [Array] Notification array, consisting of a Person and the args to Mauve::Person#send_alert
       def notification_deq
         instance.notification_buffer.shift
       end
 
+      # Return the current length of the +notification_buffer+
+      #
+      # @return [Integer]
       def notification_buffer_size
         instance.notification_buffer.size
       end
diff --git a/lib/mauve/source_list.rb b/lib/mauve/source_list.rb
index caa9f9a..b8c89cc 100644
--- a/lib/mauve/source_list.rb
+++ b/lib/mauve/source_list.rb
@@ -9,20 +9,14 @@ module Mauve
 
   # A simple construct to match sources.
   #
-  # This class stores mamed lists of IP addresses.  It stores them in a hash
-  # indexed by the name of the list.  One can pass IPv4, IPv6 and hostnames
-  # as list elements but they will all be converted into IP addresses at 
-  # the time of the list creation.
-  #
   # One can ask if an IPv4, IPv6, hostname or url (match on hostname only) is
   # contained within a list.  If the query is not an IP address, it will be
-  # converted into one before the checks are made.
+  # converted into one as the checks are made.
   #
   # Note that the matching is greedy.  When a hostname maps to several IP
   # addresses and only one of tbhose is included in the list, a match 
-  # will occure.  
+  # will occur.
   #
-  # @author Yann Golanski
   class SourceList 
 
     attr_reader :label, :list
@@ -37,6 +31,26 @@ module Mauve
 
     alias username label
 
+    # Adds a source onto the list.
+    #
+    # The source can be a string, or array of strings.  Each one can be an IPv6
+    # or IPv4 address or range, or a hostname.
+    #
+    # Hostnames can have *, or numeric ranges in their name.  A '*' represents
+    # any character except ".".  A range can be specified as 1..4, meaning 1,
+    # 2, 3 or 4.
+    #
+    # e.g.  1.2.3.4/24
+    #       2001:dead::beef/64
+    #       app1..10.my-customer.com
+    #       *.db.my-customer.com
+    #
+    # Hostnames are also resolved into IP addresses, and re-resolved every 30
+    # minutes.
+    #
+    # @param [String or Array] l The source(s) to add.
+    # @return [SourceList]
+    #
     def +(l)
       arr = [l].flatten.collect do |h|
         # "*"              means [^\.]+
@@ -52,12 +66,15 @@ module Mauve
               gsub(/\./, "\\.").
               gsub(/\*/, "[0-9a-z\\-]+") +
               "\\.?$")
-        elsif h.is_a?(String) and h =~ /^[0-9a-f\.:\/]+$/i
+        elsif h.is_a?(String) and h =~ /^[0-9a-f\.:]+(\/\d+)?$/i
           IPAddr.new(h)
-        else
+        elsif h.is_a?(String) or h.is_a?(Regexp)
           h
+        else
+          logger.warn "Cannot add #{h.inspect} to source list #{@label} as it is not a string or regular expression."
+          nil
         end
-      end.flatten
+      end.flatten.reject{|h| h.nil?}
 
       arr.each do |source|
         ##
@@ -79,13 +96,26 @@ module Mauve
 
     alias add_to_list +
 
+    # @return [Log4r::Logger]
     def logger
       @logger ||= Log4r::Logger.new self.class.to_s
     end
 
-    ## 
+    # 
     # Return whether or not a list contains a source.
-    ##
+    #
+    # First the hostname is checked for a URI, using URI#parse, and then the
+    # hostname is extracted from there.  If that fails, the original hostname
+    # is used.
+    #
+    # Next we check against our list, including all IPs for any hostnames in
+    # that list.
+    #
+    # If nothing is found, the hostname is then resolved to its IPs, and we
+    # check to see if those IPs are in our list. 
+    #
+    # @param [String] host The host to look for.
+    # @return [Boolean]
     def includes?(host)
       #
       # Redo resolution every thirty minutes
@@ -133,14 +163,20 @@ module Mauve
         ips.any?{|ip| list_ip.include?(ip)}
       end
       
+      return false
     end
 
+    # 
+    # Resolve all hostnames in the list to IP addresses.
+    #
+    # @return [Array] The new list.
+    #
     def resolve
       @last_resolved_at = Time.now
 
       new_list = @list.collect do |host| 
         if host.is_a?(String)
-          ips = [host] + MauveResolv.get_ips_for(host).collect{|i| IPAddr.new(i)}
+          [host] + MauveResolv.get_ips_for(host).collect{|i| IPAddr.new(i)}
         else
           host
         end
diff --git a/lib/mauve/timer.rb b/lib/mauve/timer.rb
index a00d66d..5a43b60 100644
--- a/lib/mauve/timer.rb
+++ b/lib/mauve/timer.rb
@@ -7,6 +7,9 @@ require 'log4r'
 
 module Mauve
 
+  #
+  # This is the thread that looks for reminders and heartbeat alerts to poll.
+  #
   class Timer < MauveThread
 
     include Singleton
@@ -20,6 +23,14 @@ module Mauve
       super
     end
 
+    private
+
+    # This is the trigger for heartbeats and reminders.
+    # 
+    # It looks up the next event, and sleeps until it is due.  If an update
+    # comes in (via the processor) it is broken out of its sleep, and starts
+    # again when woken up.
+    #
     def main_loop
       #
       # Get the next alert.
diff --git a/lib/mauve/udp_server.rb b/lib/mauve/udp_server.rb
index 080a04b..e3362e8 100644
--- a/lib/mauve/udp_server.rb
+++ b/lib/mauve/udp_server.rb
@@ -8,12 +8,22 @@ require 'ipaddr'
 
 module Mauve
 
+  #
+  # This is the thread that accepts the packets.
+  #
   class UDPServer < MauveThread
 
     include Singleton
 
     attr_reader   :ip, :port
 
+    # Yup.  Creates a new UDPServer.
+    #
+    # Defaults:
+    #   * listening IP: 127.0.0.1
+    #   * listening port: 32741
+    #   * polls every: 0 seconds
+    #
     def initialize
       #
       # Set up some defaults.
@@ -26,16 +36,50 @@ module Mauve
       super
     end
  
+    #
+    # This sets the IP which the server will listen on.
+    # 
+    # @param [String] i The new IP 
+    # @return [IPAddr]
+    #
     def ip=(i)
       raise ArgumentError, "ip must be a string" unless i.is_a?(String)
       @ip = IPAddr.new(i)
     end
  
+    # Sets the listening port
+    #
+    # @param [Integer] pr The new port
+    # @return [Integer]
+    #
     def port=(pr)
       raise ArgumentError, "port must be an integer between 0 and #{2**16-1}" unless pr.is_a?(Integer) and pr < 2**16 and pr > 0
       @port = pr
     end
+   
+    # This stops the UDP server, by signalling to the thread to stop, and
+    # sending a zero-length packet to the socket.
+    #
+    def stop
+      @stop = true
+      #
+      # Triggers loop to close socket.
+      #
+      UDPSocket.open(Socket.const_get(@socket.addr[0])).send("", 0, @socket.addr[2], @socket.addr[1]) unless @socket.nil? or @socket.closed?
+
+      super
+    end
+
+    private
 
+    #
+    # This opens the socket for listening.
+    #
+    # It tries to increase the default receiving buffer to 10M, and will warn
+    # if this fails to increase the buffer at all.
+    #
+    # @return [Nilclass]
+    #
     def open_socket
       #
       # Specify the family when opening the socket.
@@ -48,7 +92,7 @@ module Mauve
       @socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVBUF, 10*1024*1024)
       new = @socket.getsockopt(Socket::SOL_SOCKET, Socket::SO_RCVBUF).unpack("i").first
 
-      raise "Could not increase Socket::SO_RCVBUF.  Had #{old} ended up with #{new}!" if old > new 
+      logger.warn "Could not increase Socket::SO_RCVBUF.  Had #{old} ended up with #{new}!" if old > new 
 
       logger.debug("Successfully increased Socket::SO_RCVBUF from #{old} to #{new}.")
 
@@ -57,6 +101,8 @@ module Mauve
       logger.info("Opened socket on #{@ip.to_s}:#{@port}")
     end
 
+    # This closes the socket.  IOErrors are caught and logged.
+    #
     def close_socket
       return if @socket.nil?  or @socket.closed?
 
@@ -71,6 +117,13 @@ module Mauve
       logger.info("Closed socket")
     end
 
+    # This is the main loop.  It receives from the UDP port, and records the
+    # time the packet arrives.  It then pushes the packet onto the Server's
+    # packet buffer for the processor to pick up later.
+    #
+    # If a zero-length packet is received, and the thread has been signalled to
+    # stop, then the socket is closed, and the thread exits.
+    #
     def main_loop
       return if self.should_stop?
 
@@ -99,7 +152,7 @@ module Mauve
       # If we get a zero length packet, and we've been flagged to stop, we stop!
       #
       if packet.first.length == 0 and self.should_stop?
-        self.close_socket 
+        close_socket 
         return
       end
 
@@ -109,16 +162,6 @@ module Mauve
       Server.packet_push([packet[0], packet[1], received_at])
     end
 
-    def stop
-      @stop = true
-      #
-      # Triggers loop to close socket.
-      #
-      UDPSocket.open(Socket.const_get(@socket.addr[0])).send("", 0, @socket.addr[2], @socket.addr[1]) unless @socket.nil? or @socket.closed?
-
-      super
-    end
-
   end
 
 end
diff --git a/lib/mauve/version.rb b/lib/mauve/version.rb
index 56ac522..2b35608 100644
--- a/lib/mauve/version.rb
+++ b/lib/mauve/version.rb
@@ -1,5 +1,10 @@
+#
+# This is Mauve!
+#
 module Mauve
 
+  #
+  # Current version
   VERSION="3.5.8"
 
 end
diff --git a/lib/object_builder.rb b/lib/object_builder.rb
index a455b3e..8f338ff 100644
--- a/lib/object_builder.rb
+++ b/lib/object_builder.rb
@@ -45,13 +45,21 @@ class ObjectBuilder
   
   attr_reader   :result
   attr_accessor :block_result
-  
+ 
+  # Generates a new builder
+  # 
+  # @param [ObjectBuidler] context The level of the builder
+  # @param [Array] args The arguments to pass on to the builder_setup
+  #
   def initialize(context, *args)
     @context = context
     @result  = nil
     builder_setup(*args)
   end
   
+  # Generates an anonymous name
+  #
+  # @return [String]
   def anonymous_name
     @@sequence ||= 0 # not inherited, don't want it to be
     @@sequence  += 1
@@ -60,6 +68,15 @@ class ObjectBuilder
   
   class << self
   
+    # Defines a new builder
+    #
+    # @param [String] word The builder's name
+    # @param [Class] clazz The Class the builder represents
+    #
+    # @macro [attach] is_builder
+    #   @return The +$1+ builder.
+    #
+    # @return [NilClass]
     def is_builder(word, clazz)
       define_method(word.to_sym) do |*args, &block|
         builder = clazz.new(*([@context] + args))
@@ -72,59 +89,84 @@ class ObjectBuilder
           end
         end
       end
+
+      return nil
     end
     
     # FIXME: implement is_builder_deferred to create object at end of block?
     
+    # Defines a new block attribute
+    # @param [String] word The block attribute's name
+    # @macro [attach] is_block_attribute
+    #   @return [NilClass] Allows use of the +$1+ word to define a block.
     def is_block_attribute(word)
       define_method(word.to_sym) do |*args, &block|
         @result.__send__("#{word}=".to_sym, block)
       end
     end
-    
+   
+    # Defines a new attribute
+    # @param [String] word The attribute's name
+    # @macro [attach] is_attribute
+    #   @return [NilClass] Allows use of the +$1+ word to set an attribute.
+    #
     def is_attribute(word)
       define_method(word.to_sym) do |*args, &block|
         @result.__send__("#{word}=".to_sym, args[0])
       end
     end
     
+    # Defines a new boolean attribute
+    # @param [String] word The boolean attribute's name
+    # @macro [attach] is_flag_attribute
+    #   @return [NilClass] Allows use of the +$1+ word to set an boolean attribute.
     def is_flag_attribute(word)
       define_method(word.to_sym) do |*args, &block|
         @result.__send__("#{word}=".to_sym, true)
       end
     end
   
+    # Loads a new file
+    # 
+    # @param [String] file
     def load(file)
       parse(File.read(file), file)
     end
    
+    # Parses a string
+    #
+    # @param [String] string The string to parse
+    # @param [String] file The filename that the string was read from, for helpful error messages.
+    #
+    # @raise [BuildException] When an expected exception is raised
+    # @raise [NameError]
+    # @raise [SyntaxError] 
+    # @raise [ArgumentError]
+    #
+    # @return [ObjectBuidler] The 
     def parse(string, file="string")
       builder = self.new
-      begin
-        builder.instance_eval(string, file)
-      rescue NameError => ex
-        # 
-        # Ugh.  Catch NameError and re-raise as a BuildException
-        #
-        f,l = ex.backtrace.first.split(":").first(2)
-        if f == file
-          build_ex = BuildException.new "Unknown word `#{ex.name}' in #{file} at line #{l}"
-          build_ex.set_backtrace ex.backtrace
-          raise build_ex
-        else
-          raise ex
-        end
-      rescue SyntaxError, ArgumentError => ex
-        if ex.backtrace.find{|l| l =~ /^#{file}:(\d+):/}
-          build_ex = BuildException.new "#{ex.message} in #{file} at line #{$1}"
-          build_ex.set_backtrace ex.backtrace
-          raise build_ex
-        else
-          raise ex
-        end
-      end
-
+      builder.instance_eval(string, file)
       builder.result
+    rescue NameError, NoMethodError => ex
+      # 
+      # Ugh.  Catch NameError and re-raise as a BuildException
+      #
+      if ex.backtrace.find{|l| l =~ /^#{file}:(\d+):/}
+        build_ex = BuildException.new "Unknown word `#{ex.name}' in #{file} at line #{$1}"
+        build_ex.set_backtrace ex.backtrace
+        raise build_ex
+      else
+        raise ex
+      end
+    rescue SyntaxError, ArgumentError => ex
+      if ex.backtrace.find{|l| l =~ /^#{file}:(\d+):/}
+        build_ex = BuildException.new "#{ex.message} in #{file} at line #{$1}"
+        build_ex.set_backtrace ex.backtrace
+        raise build_ex
+      else
+        raise ex
+      end
     end
  
     def inherited(*args)
diff --git a/test/tc_mauve_notification.rb b/test/tc_mauve_notification.rb
index 4243874..0b3bc04 100644
--- a/test/tc_mauve_notification.rb
+++ b/test/tc_mauve_notification.rb
@@ -39,12 +39,12 @@ class TcMauveDuringRunner < Mauve::UnitTest
   def test_now?
     alert = Alert.new
     time = Time.now
-    during = Proc.new { @test_time }
+    during = Proc.new { Time.now == @test_time }
 
     dr = DuringRunner.new(time, alert, &during)
     
-    assert_equal(time, dr.now?)
-    assert_equal(time+3600, dr.now?(time+3600))
+    assert_equal(true, dr.now?)
+    assert_equal(false, dr.now?(time+3600))
     assert_equal(time, dr.time)
   end