# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1427055822 -3600
# Node ID d79aa0aad5f3ffe44baa4561ec4923ddcc47ab71
# Parent  b98f64c7e5592e24fb0caa3b40eee9efebf14724
Introduced comments, docstrings and some minor simplifications.

diff -r b98f64c7e559 -r d79aa0aad5f3 imiptools/handlers/person.py
--- a/imiptools/handlers/person.py	Sun Mar 22 19:04:48 2015 +0100
+++ b/imiptools/handlers/person.py	Sun Mar 22 21:23:42 2015 +0100
@@ -32,6 +32,15 @@
 
     def _record(self, from_organiser=True, queue=False, cancel=False):
 
+        """
+        Record details from the current object given a message originating
+        from an organiser if 'from_organiser' is set to a true value, queuing a
+        request if 'queue' is set to a true value, or cancelling an event if
+        'cancel' is set to a true value.
+        """
+
+        # Obtain valid organiser and attendee details.
+
         oa = self.require_organiser_and_attendees(from_organiser)
         if not oa:
             return False
@@ -78,7 +87,7 @@
 
                 self.update_freebusy_from_organiser(attendee, organiser_item)
 
-        # As organiser, update attendance.
+        # As organiser, update attendance from valid attendees.
 
         else:
             if self.merge_attendance(attendees, organiser):
@@ -88,7 +97,10 @@
 
     def _record_freebusy(self, from_organiser=True):
 
-        "Record free/busy information for the received information."
+        """
+        Record free/busy information for a message originating from an organiser
+        if 'from_organiser' is set to a true value.
+        """
 
         if from_organiser:
             organiser_item = self.require_organiser(from_organiser)
diff -r b98f64c7e559 -r d79aa0aad5f3 imiptools/handlers/person_outgoing.py
--- a/imiptools/handlers/person_outgoing.py	Sun Mar 22 19:04:48 2015 +0100
+++ b/imiptools/handlers/person_outgoing.py	Sun Mar 22 21:23:42 2015 +0100
@@ -46,7 +46,11 @@
 
     def _record(self, from_organiser=True, update_freebusy=False):
 
-        "Record free/busy and object information."
+        """
+        Record details from the current object given a message originating
+        from an organiser if 'from_organiser' is set to a true value, updating
+        free/busy information if 'update_freebusy' is set to a true value.
+        """
 
         item = self._get_identity(from_organiser)
         if not item:
@@ -68,7 +72,10 @@
                 self.store.remove_recurrences(identity, self.uid)
 
         else:
-            organiser_item, attendees = self.require_organiser_and_attendees(from_organiser)
+            # Obtain valid attendees, merging their attendance with the stored
+            # object.
+
+            attendees = self.require_attendees(from_organiser)
             self.merge_attendance(attendees, identity)
 
         # Remove any associated request.
@@ -90,6 +97,8 @@
             # recurrence information.
 
             obj = self.get_object(identity)
+            if not obj:
+                return False # although this should not happen
 
             # If newer than any old version, discard old details from the
             # free/busy record and check for suitability.
@@ -126,6 +135,8 @@
         # NOTE: cancellations.
 
         obj = self.get_object(identity)
+        if not obj:
+            return False
 
         attendees = uri_dict(obj.get_value_map("ATTENDEE"))
         all_attendees = set(attendees.keys())
diff -r b98f64c7e559 -r d79aa0aad5f3 imiptools/handlers/resource.py
--- a/imiptools/handlers/resource.py	Sun Mar 22 19:04:48 2015 +0100
+++ b/imiptools/handlers/resource.py	Sun Mar 22 21:23:42 2015 +0100
@@ -31,6 +31,12 @@
 
     def _record_and_respond(self, handle_for_attendee):
 
+        """
+        Record details from the incoming message, using the given
+        'handle_for_attendee' callable to process any valid message
+        appropriately.
+        """
+
         oa = self.require_organiser_and_attendees()
         if not oa:
             return None
@@ -58,6 +64,11 @@
 
     def _schedule_for_attendee(self, attendee, attendee_attr):
 
+        """
+        Schedule for the given 'attendee' and accompanying 'attendee_attr' the
+        current object.
+        """
+
         # Interpretation of periods can depend on the time zone.
 
         tzid = self.get_tzid(attendee)
@@ -114,6 +125,11 @@
 
     def _cancel_for_attendee(self, attendee, attendee_attr):
 
+        """
+        Cancel for the given 'attendee' and accompanying 'attendee_attr' their
+        attendance of the event described by the current object.
+        """
+
         self.store.cancel_event(attendee, self.uid, self.recurrenceid)
 
         freebusy = self.store.get_freebusy(attendee)