add docblocks to all files, classes, methods and variables

3 files changed, 163 insertions, 7 deletions

diff --git a/src/bdrem/Source/Bdf.php b/src/bdrem/Source/Bdf.php
index f38e30f..651360a 100644
--- a/src/bdrem/Source/Bdf.php
+++ b/src/bdrem/Source/Bdf.php
@@ -1,13 +1,41 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
 /**
  * Reads birthday reminder 2's birthday files (.bdf).
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
  */
 class Source_Bdf
 {
+    /**
+     * Full path of bdf birthday file
+     * @var string
+     */
     protected $filename;
 
+    /**
+     * Set the birthday file name
+     *
+     * @param string $filename Path to bdf file
+     */
     public function __construct($filename)
     {
         $this->filename = $filename;
@@ -19,9 +47,16 @@ class Source_Bdf
     }
 
     /**
-     * @param string $strDate Date the events shall be found for, YYYY-MM-DD
+     * Return all events for the given date range
+     *
+     * @param string  $strDate       Date the events shall be found for,
+     *                               YYYY-MM-DD
+     * @param integer $nDaysPrevious Include number of days before $strDate
+     * @param integer $nDaysNext     Include number of days after $strDate
+     *
+     * @return Event[] Array of matching event objects
      */
-    public function getEvents($strDate, $nDaysPrev, $nDaysNext)
+    public function getEvents($strDate, $nDaysPrevious, $nDaysNext)
     {
         $x = simplexml_load_file($this->filename);
 
@@ -38,7 +73,7 @@ class Source_Bdf
                 (string) $xPerson->event,
                 $date
             );
-            if ($event->isWithin($strDate, $nDaysPrev, $nDaysNext)) {
+            if ($event->isWithin($strDate, $nDaysPrevious, $nDaysNext)) {
                 $arEvents[] = $event;
             }
         }
diff --git a/src/bdrem/Source/Ldap.php b/src/bdrem/Source/Ldap.php
index 335be07..aa45b0a 100644
--- a/src/bdrem/Source/Ldap.php
+++ b/src/bdrem/Source/Ldap.php
@@ -1,12 +1,42 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
 /**
  * Fetch data from an LDAP server.
  * Works fine with evolutionPerson schema.
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
  */
 class Source_Ldap
 {
+    /**
+     * LDAP server configuration
+     *
+     * Keys:
+     * - host   - LDAP server host name
+     * - basedn - root DN that gets searched
+     * - binddn - Username to authenticate with
+     * - bindpw - Password for username
+     *
+     * @var array
+     */
     protected $config;
 
     /**
@@ -25,7 +55,14 @@ class Source_Ldap
     }
 
     /**
-     * @param string $strDate Date the events shall be found for, YYYY-MM-DD
+     * Return all events for the given date range
+     *
+     * @param string  $strDate       Date the events shall be found for,
+     *                               YYYY-MM-DD
+     * @param integer $nDaysPrevious Include number of days before $strDate
+     * @param integer $nDaysNext     Include number of days after $strDate
+     *
+     * @return Event[] Array of matching event objects
      */
     public function getEvents($strDate, $nDaysPrevious, $nDaysNext)
     {
@@ -89,6 +126,14 @@ class Source_Ldap
         return $arEvents;
     }
 
+    /**
+     * Extract the name from the given LDAP entry object.
+     * Uses displayName or givenName + sn
+     *
+     * @param object $entry LDAP entry
+     *
+     * @return string Name or NULL
+     */
     protected function getNameFromEntry(\Net_LDAP2_Entry $entry)
     {
         $arEntry = $entry->getValues();
@@ -103,6 +148,13 @@ class Source_Ldap
     }
 
     /**
+     * Create an array of dates that are included in the given range.
+     *
+     * @param string  $strDate       Date the events shall be found for,
+     *                               YYYY-MM-DD
+     * @param integer $nDaysPrevious Include number of days before $strDate
+     * @param integer $nDaysNext     Include number of days after $strDate
+     *
      * @return array Values like "-01-24" ("-$month-$day")
      */
     protected function getDates($strDate, $nDaysPrevious, $nDaysNext)
@@ -117,6 +169,5 @@ class Source_Ldap
         } while (--$numDays >= 0);
         return $arDays;
     }
-
 }
 ?>
diff --git a/src/bdrem/Source/Sql.php b/src/bdrem/Source/Sql.php
index 57f9a80..81ce5be 100644
--- a/src/bdrem/Source/Sql.php
+++ b/src/bdrem/Source/Sql.php
@@ -1,17 +1,73 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
 /**
  * Fetch data from an SQL database
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
  */
 class Source_Sql
 {
+    /**
+     * PDO data source description
+     * @var string
+     */
     protected $dsn;
+
+    /**
+     * Database user name
+     * @var string
+     */
     protected $user;
+
+    /**
+     * Database password
+     * @var string
+     */
     protected $password;
+
+    /**
+     * Database table with event data
+     * @var string
+     */
     protected $table;
-    protected $fields ;
 
+    /**
+     * Field configuration
+     * Keys:
+     * - date - array of columns with dates and their event title,
+     *          e.g. 'c_birthday' => 'Birthday'
+     * - name - array of name columns
+     * - nameFormat - sprintf-compatible name formatting instruction,
+     *                uses name columns
+     *
+     * @var array
+     */
+    protected $fields;
+
+    /**
+     * Set SQL server configuration
+     *
+     * @param array $config SQL server configuration with keys:
+     *                      dsn, user, password, table and fields
+     */
     public function __construct($config)
     {
         $this->dsn      = $config['dsn'];
@@ -22,7 +78,14 @@ class Source_Sql
     }
 
     /**
-     * @param string $strDate Date the events shall be found for, YYYY-MM-DD
+     * Return all events for the given date range
+     *
+     * @param string  $strDate       Date the events shall be found for,
+     *                               YYYY-MM-DD
+     * @param integer $nDaysPrevious Include number of days before $strDate
+     * @param integer $nDaysNext     Include number of days after $strDate
+     *
+     * @return Event[] Array of matching event objects
      */
     public function getEvents($strDate, $nDaysPrevious, $nDaysNext)
     {
@@ -85,6 +148,13 @@ class Source_Sql
     }
 
     /**
+     * Create an array of dates that are included in the given range.
+     *
+     * @param string  $strDate       Date the events shall be found for,
+     *                               YYYY-MM-DD
+     * @param integer $nDaysPrevious Include number of days before $strDate
+     * @param integer $nDaysNext     Include number of days after $strDate
+     *
      * @return array Key is the month, value an array of days
      */
     protected function getDates($strDate, $nDaysPrevious, $nDaysNext)