# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1460991272 -7200
# Node ID b131dbbb2da22e4e97aed6a0a62666bbb6d39f24
# Parent  280328be274121c07262c941d5343cbac1019cd6
Added some documentation strings for the different functions and abstractions.

diff -r 280328be2741 -r b131dbbb2da2 modules/fburl.js
--- a/modules/fburl.js	Sun Apr 17 21:54:48 2016 +0200
+++ b/modules/fburl.js	Mon Apr 18 16:54:32 2016 +0200
@@ -25,6 +25,8 @@
 const calIFreeBusyInterval = Ci.calIFreeBusyInterval;
 const calIDateTime = Ci.calIDateTime;
 
+/* Initialise the provider.
+ */
 fburl.fbUrlProvider = function(cal) {
     this.cal = cal;
     this._query = null;
@@ -38,9 +40,16 @@
     this._periods = null;
 };
 
+/* The free/busy provider for FBURL-specified resources.
+ * This implements the calIFreeBusyProvider interface, returning free/busy
+ * intervals when getFreeBusyIntervals is called.
+ */
 fburl.fbUrlProvider.prototype = {
     classID: Components.ID("{11291d94-b457-4322-bfba-ae9df4b6a3c1}"),
 
+    /* Called by the calFreeBusyService, this function performs a search in
+     * LDAP address books and returns any intervals found.
+     */
     getFreeBusyIntervals: function (aCalId, aRangeStart, aRangeEnd, aBusyTypes, aListener) {
 
         this._listener = aListener;
@@ -49,6 +58,9 @@
         this.startSearch(aCalId);
     },
 
+    /* Access the address book manager and obtain all LDAP directory address
+     * books.
+     */
     getLDAPAddressBooks: function () {
 
         var abManager = Cc["@mozilla.org/abmanager;1"].getService(Ci.nsIAbManager);
@@ -65,6 +77,9 @@
         return books;
     },
 
+    /* Initiate a search, obtaining LDAP address books and querying each one for
+     * an identity having the given primary e-mail address.
+     */
     startSearch: function (aCalId) {
 
         var service = Cc["@mozilla.org/network/ldap-service;1"].getService(Ci.nsILDAPService);
@@ -94,6 +109,8 @@
         }
     },
 
+    /* Stop any currently-initiated search.
+     */
     stopSearch: function stopSearch() {
         if (this._context) {
             this._query.stopQuery(this._context);
@@ -102,11 +119,22 @@
         }
     },
 
+    /* Search finished callback.
+     */
     onSearchFinished: function (aResult, aErrorMsg) {
         this._context = null;
         this._error = aErrorMsg;
     },
 
+    /* Search success callback, indicating any found address book card. The
+     * supplied card should provide the FBURL property which is then used to
+     * retrieve the referenced free/busy resource.
+     *
+     * Upon retrieval, the resource is parsed using the calICSService and the
+     * free/busy periods obtained. Finally, each period is encapsulated in an
+     * interval object and the collection of such objects presented to the
+     * originally-specified result callback.
+     */
     onSearchFoundCard: function (aCard) {
 
         this._result = aCard;
@@ -181,6 +209,8 @@
     QueryInterface: XPCOMUtils.generateQI([Ci.nsIObserver, Ci.nsIAbDirSearchListener])
 };
 
+/* Provide a way of adding the provider to the free/busy service.
+ */
 fburl.initProvider = function() {
     cal.getFreeBusyService().addProvider(new fburl.fbUrlProvider(cal));
 }