Added more phpdoc comments

14 files changed, 318 insertions, 20 deletions

diff --git a/lib/api/kolab_api_service_domains.php b/lib/api/kolab_api_service_domains.php
index e32aeb7..e964936 100644
--- a/lib/api/kolab_api_service_domains.php
+++ b/lib/api/kolab_api_service_domains.php
@@ -24,19 +24,35 @@
 */
 
 /**
- *
+ * Service providing domains listing
  */
 class kolab_api_service_domains extends kolab_api_service
 {
+
+    /**
+     * Returns service capabilities.
+     *
+     * @param string $domain Domain name
+     *
+     * @return array Capabilities list
+     */
     public function capabilities($domain)
     {
         return array(
             'list' => 'r',
-//             'search' => 'r',
         );
     }
 
-    public function domains_list($get, $post) {
+    /**
+     * Users listing (with searching).
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return array List result with 'list' and 'count' items
+     */
+    public function domains_list($get, $post)
+    {
         $auth = Auth::get_instance();
 
         $domains = $auth->list_domains();
diff --git a/lib/api/kolab_api_service_form_value.php b/lib/api/kolab_api_service_form_value.php
index ff63c3d..fa8d19d 100644
--- a/lib/api/kolab_api_service_form_value.php
+++ b/lib/api/kolab_api_service_form_value.php
@@ -29,6 +29,13 @@
 class kolab_api_service_form_value extends kolab_api_service
 {
 
+    /**
+     * Returns service capabilities.
+     *
+     * @param string $domain Domain name
+     *
+     * @return array Capabilities list
+     */
     public function capabilities($domain)
     {
         return array(
diff --git a/lib/api/kolab_api_service_group.php b/lib/api/kolab_api_service_group.php
index 9020d01..f382d79 100644
--- a/lib/api/kolab_api_service_group.php
+++ b/lib/api/kolab_api_service_group.php
@@ -28,6 +28,13 @@
  */
 class kolab_api_service_group extends kolab_api_service
 {
+    /**
+     * Returns service capabilities.
+     *
+     * @param string $domain Domain name
+     *
+     * @return array Capabilities list
+     */
     public function capabilities($domain)
     {
         return array(
@@ -38,6 +45,14 @@ class kolab_api_service_group extends kolab_api_service
         );
     }
 
+    /**
+     * Group create.
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return array|bool Group attributes or False on failure
+     */
     public function group_add($getdata, $postdata)
     {
         $gta = $this->group_type_attributes($postdata['group_type_id']);
@@ -87,6 +102,14 @@ class kolab_api_service_group extends kolab_api_service
         return FALSE;
     }
 
+    /**
+     * Group delete.
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return bool True on success, False on failure
+     */
     public function group_delete($getdata, $postdata)
     {
         if (empty($postdata['group'])) {
@@ -104,6 +127,14 @@ class kolab_api_service_group extends kolab_api_service
         return FALSE;
     }
 
+    /**
+     * Group information.
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return array|bool Group attributes or False on failure
+     */
     public function group_info($getdata, $postdata)
     {
         if (empty($getdata['group'])) {
@@ -125,6 +156,14 @@ class kolab_api_service_group extends kolab_api_service
         return FALSE;
     }
 
+    /**
+     * Group members listing.
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return array List of group members ('list' and 'count' items)
+     */
     public function group_members_list($getdata, $postdata)
     {
         $auth = Auth::get_instance();
diff --git a/lib/api/kolab_api_service_group_types.php b/lib/api/kolab_api_service_group_types.php
index 3ee0b83..7145654 100644
--- a/lib/api/kolab_api_service_group_types.php
+++ b/lib/api/kolab_api_service_group_types.php
@@ -24,10 +24,17 @@
 */
 
 /**
- *
+ * Service providing group types listing
  */
 class kolab_api_service_group_types extends kolab_api_service
 {
+    /**
+     * Returns service capabilities.
+     *
+     * @param string $domain Domain name
+     *
+     * @return array Capabilities list
+     */
     public function capabilities($domain)
     {
         return array(
@@ -35,6 +42,14 @@ class kolab_api_service_group_types extends kolab_api_service
         );
     }
 
+    /**
+     * Group types listing.
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return array List result with 'list' and 'count' items
+     */
     public function group_types_list($get, $post)
     {
         $group_types = $this->group_types();
diff --git a/lib/api/kolab_api_service_groups.php b/lib/api/kolab_api_service_groups.php
index d85de12..ff8781b 100644
--- a/lib/api/kolab_api_service_groups.php
+++ b/lib/api/kolab_api_service_groups.php
@@ -24,7 +24,7 @@
 */
 
 /**
- *
+ * Service providing groups listing
  */
 class kolab_api_service_groups extends kolab_api_service
 {
@@ -35,6 +35,13 @@ class kolab_api_service_groups extends kolab_api_service
         'mail',
     );
 
+    /**
+     * Returns service capabilities.
+     *
+     * @param string $domain Domain name
+     *
+     * @return array Capabilities list
+     */
     public function capabilities($domain)
     {
         return array(
@@ -42,6 +49,14 @@ class kolab_api_service_groups extends kolab_api_service
         );
     }
 
+    /**
+     * Groups listing (with searching).
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return array List result with 'list' and 'count' items
+     */
     public function groups_list($get, $post)
     {
         $auth = Auth::get_instance();
diff --git a/lib/api/kolab_api_service_roles.php b/lib/api/kolab_api_service_roles.php
index 2be1d7a..1c9b8aa 100644
--- a/lib/api/kolab_api_service_roles.php
+++ b/lib/api/kolab_api_service_roles.php
@@ -24,7 +24,7 @@
 */
 
 /**
- *
+ * Service providing roles listing
  */
 class kolab_api_service_roles extends kolab_api_service
 {
@@ -35,7 +35,13 @@ class kolab_api_service_roles extends kolab_api_service
         'description',
     );
 
-
+    /**
+     * Returns service capabilities.
+     *
+     * @param string $domain Domain name
+     *
+     * @return array Capabilities list
+     */
     public function capabilities($domain)
     {
         return array(
@@ -43,6 +49,14 @@ class kolab_api_service_roles extends kolab_api_service
         );
     }
 
+    /**
+     * Roles listing (with searching).
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return array List result with 'list' and 'count' items
+     */
     public function roles_list($get, $post)
     {
         $auth = Auth::get_instance();
diff --git a/lib/api/kolab_api_service_user.php b/lib/api/kolab_api_service_user.php
index a355ac4..b13f40f 100644
--- a/lib/api/kolab_api_service_user.php
+++ b/lib/api/kolab_api_service_user.php
@@ -24,10 +24,17 @@
 */
 
 /**
- *
+ * Service providing user data management
  */
 class kolab_api_service_user extends kolab_api_service
 {
+    /**
+     * Returns service capabilities.
+     *
+     * @param string $domain Domain name
+     *
+     * @return array Capabilities list
+     */
     public function capabilities($domain)
     {
         return array(
@@ -42,6 +49,14 @@ class kolab_api_service_user extends kolab_api_service
         );
     }
 
+    /**
+     * Create user.
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return array|bool User attributes or False on error.
+     */
     public function user_add($getdata, $postdata)
     {
         $uta             = $this->user_type_attributes($postdata['user_type_id']);
@@ -87,13 +102,21 @@ class kolab_api_service_user extends kolab_api_service
             return $user_attributes;
         }
 
-        return FALSE;
+        return false;
     }
 
+    /**
+     * Detete user.
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return bool True on success, False on failure
+     */
     public function user_delete($getdata, $postdata)
     {
         if (!isset($postdata['user'])) {
-            return FALSE;
+            return false;
         }
 
         // TODO: Input validation
@@ -104,13 +127,21 @@ class kolab_api_service_user extends kolab_api_service
             return $result;
         }
 
-        return FALSE;
+        return false;
     }
 
+    /**
+     * User information.
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return array|bool User attributes, False on error
+     */
     public function user_info($getdata, $postdata)
     {
         if (!isset($getdata['user'])) {
-            return FALSE;
+            return false;
         }
 
         $auth   = Auth::get_instance();
@@ -146,6 +177,6 @@ class kolab_api_service_user extends kolab_api_service
             return $result;
         }
 
-        return FALSE;
+        return false;
     }
 }
diff --git a/lib/api/kolab_api_service_user_types.php b/lib/api/kolab_api_service_user_types.php
index 164e872..b2adcf2 100644
--- a/lib/api/kolab_api_service_user_types.php
+++ b/lib/api/kolab_api_service_user_types.php
@@ -28,6 +28,13 @@
  */
 class kolab_api_service_user_types extends kolab_api_service
 {
+    /**
+     * Returns service capabilities.
+     *
+     * @param string $domain Domain name
+     *
+     * @return array Capabilities list
+     */
     public function capabilities($domain)
     {
         return array(
@@ -35,6 +42,14 @@ class kolab_api_service_user_types extends kolab_api_service
         );
     }
 
+    /**
+     * User types listing.
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return array List result with 'list' and 'count' items
+     */
     public function user_types_list($get, $post)
     {
         $user_types = $this->user_types();
diff --git a/lib/api/kolab_api_service_users.php b/lib/api/kolab_api_service_users.php
index a950a09..f5a04f9 100644
--- a/lib/api/kolab_api_service_users.php
+++ b/lib/api/kolab_api_service_users.php
@@ -24,7 +24,7 @@
 */
 
 /**
- *
+ * Service providing users listing
  */
 class kolab_api_service_users extends kolab_api_service
 {
@@ -43,6 +43,13 @@ class kolab_api_service_users extends kolab_api_service
     );
 
 
+    /**
+     * Returns service capabilities.
+     *
+     * @param string $domain Domain name
+     *
+     * @return array Capabilities list
+     */
     public function capabilities($domain)
     {
         return array(
@@ -50,6 +57,14 @@ class kolab_api_service_users extends kolab_api_service
         );
     }
 
+    /**
+     * Users listing (with searching).
+     *
+     * @param array $get   GET parameters
+     * @param array $post  POST parameters
+     *
+     * @return array List result with 'list' and 'count' items
+     */
     public function users_list($get, $post)
     {
         $auth = Auth::get_instance();
diff --git a/lib/kolab_api_service.php b/lib/kolab_api_service.php
index 60e9ced..03c273e 100644
--- a/lib/kolab_api_service.php
+++ b/lib/kolab_api_service.php
@@ -115,7 +115,7 @@ abstract class kolab_api_service
             return null;
         }
 
-        $object_class = array_map('strtolower', $object_class);                                                                                         
+        $object_class = array_map('strtolower', $object_class);
         $user_types   = $this->user_types();
         $type_score   = -1;
         $type_id      = null;
@@ -158,7 +158,7 @@ abstract class kolab_api_service
         if (!empty($this->cache['user_types'])) {
             return $this->cache['user_types'];
         }
-    
+
         $sql_result = $this->db->query("SELECT * FROM user_types");
         $user_types = array();
 
@@ -190,7 +190,7 @@ abstract class kolab_api_service
         if (!empty($this->cache['group_types'])) {
             return $this->cache['group_types'];
         }
-    
+
         $sql_result = $this->db->query("SELECT * FROM group_types");
         $group_types = array();
 
diff --git a/lib/kolab_form.php b/lib/kolab_form.php
index f5533af..b387b65 100644
--- a/lib/kolab_form.php
+++ b/lib/kolab_form.php
@@ -22,7 +22,9 @@
  +--------------------------------------------------------------------------+
 */
 
-
+/**
+ * HTML Form generator
+ */
 class kolab_form
 {
     const INPUT_TEXT = 1;
@@ -207,6 +209,9 @@ class kolab_form
         return $content;
     }
 
+    /**
+     * Builds a row of the form table.
+     */
     private function form_row($element)
     {
         $cells = array(
@@ -229,6 +234,9 @@ class kolab_form
         return $attrib;
     }
 
+    /**
+     * Builds an element of the form.
+     */
     private function get_element($attribs)
     {
         $type = isset($attribs['type']) ? $attribs['type'] : 0;
diff --git a/lib/kolab_html.php b/lib/kolab_html.php
index 9680ef5..385b0ad 100644
--- a/lib/kolab_html.php
+++ b/lib/kolab_html.php
@@ -22,7 +22,9 @@
  +--------------------------------------------------------------------------+
 */
 
-
+/**
+ * HTML output generation
+ */
 class kolab_html
 {
     public static $common_attribs = array('id', 'class', 'style', 'title', 'align', 'dir');
@@ -43,6 +45,15 @@ class kolab_html
     public static $label_attribs  = array('for');
 
 
+    /**
+     * Table element (TABLE).
+     *
+     * @param array  $attribs  Table attributes
+     * @param string $content  Optional table content. If empty
+     *                         head, body, foot attributes will be used.
+     *
+     * @return string HTML output of the table
+     */
     public static function table($attribs = array(), $content = null)
     {
         $table_attribs = array_merge(self::$table_attribs, self::$common_attribs, self::$event_attribs);
@@ -80,6 +91,14 @@ class kolab_html
         return $table;
     }
 
+    /**
+     * Table row (TR).
+     *
+     * @param array  $attribs  Row attributes
+     * @param string $is_head  Set to true if it is a part of table head.
+     *
+     * @return string HTML output of the row
+     */
     public static function tr($attribs = array(), $is_head = false)
     {
         $row_attribs = array_merge(self::$tr_attribs, self::$common_attribs, self::$event_attribs);
@@ -96,6 +115,14 @@ class kolab_html
         return $row;
     }
 
+    /**
+     * Table cell (TD or TH).
+     *
+     * @param array  $attribs  Cell attributes
+     * @param string $is_head  Set to true if it is a part of table head.
+     *
+     * @return string HTML output of the cell
+     */
     public static function td($attribs = array(), $is_head = false)
     {
         $cell_attribs = array_merge(self::$td_attribs, self::$common_attribs, self::$event_attribs);
@@ -111,6 +138,13 @@ class kolab_html
         return $cell;
     }
 
+    /**
+     * Input element.
+     *
+     * @param array  $attribs  Element attributes
+     *
+     * @return string HTML output of the input
+     */
     public static function input($attribs = array())
     {
         $elem_attribs = array_merge(self::$input_attribs, self::$input_event_attribs,
@@ -119,6 +153,14 @@ class kolab_html
         return sprintf('<input%s />', self::attrib_string($attribs, $elem_attribs));
     }
 
+    /**
+     * Textarea element.
+     *
+     * @param array $attribs  Element attributes
+     * @param bool  $escape   Enables escaping of the content
+     *
+     * @return string HTML output of the textarea
+     */
     public static function textarea($attribs = array(), $escape = false)
     {
         $elem_attribs = array_merge(self::$textarea_attribs, self::$input_event_attribs,
@@ -134,6 +176,14 @@ class kolab_html
             self::attrib_string($attribs, $elem_attribs), $content);
     }
 
+    /**
+     * Select element.
+     *
+     * @param array $attribs  Element attributes
+     * @param bool  $escape   Enables escaping of the content
+     *
+     * @return string HTML output of the select tag
+     */
     public static function select($attribs = array(), $escape = false)
     {
         $elem_attribs = array_merge(self::$select_attribs, self::$input_event_attribs,
@@ -159,6 +209,14 @@ class kolab_html
             self::attrib_string($attribs, $elem_attribs), implode("\n", $content));
     }
 
+    /**
+     * Option element.
+     *
+     * @param array $attribs  Element attributes
+     * @param bool  $escape   Enables escaping of the content
+     *
+     * @return string HTML output of the option tag
+     */
     public static function option($attribs = array(), $escape = false)
     {
         $elem_attribs = array_merge(self::$option_attribs, self::$common_attribs);
@@ -173,6 +231,14 @@ class kolab_html
             self::attrib_string($attribs, $elem_attribs), $content);
     }
 
+    /**
+     * Fieldset element.
+     *
+     * @param array $attribs  Element attributes
+     * @param bool  $escape   Enables escaping of the content
+     *
+     * @return string HTML output of the fieldset tag
+     */
     public static function fieldset($attribs = array(), $escape = false)
     {
         $elem_attribs = array_merge(self::$common_attribs);
@@ -188,6 +254,14 @@ class kolab_html
             self::attrib_string($attribs, $elem_attribs), $legend, $content);
     }
 
+    /**
+     * Link element (A).
+     *
+     * @param array $attribs  Element attributes
+     * @param bool  $escape   Enables escaping of the content
+     *
+     * @return string HTML output of the link
+     */
     public static function a($attribs = array(), $escape = false)
     {
         $elem_attribs = array_merge(self::$a_attribs, self::$common_attribs, self::$event_attribs);
@@ -202,6 +276,14 @@ class kolab_html
             self::attrib_string($attribs, $elem_attribs), $content);
     }
 
+    /**
+     * Label element.
+     *
+     * @param array $attribs  Element attributes
+     * @param bool  $escape   Enables escaping of the content
+     *
+     * @return string HTML output of the label tag
+     */
     public static function label($attribs = array(), $escape = false)
     {
         $elem_attribs = array_merge(self::$label_attribs, self::$common_attribs);
@@ -216,6 +298,14 @@ class kolab_html
             self::attrib_string($attribs, $elem_attribs), $content);
     }
 
+    /**
+     * Division element.
+     *
+     * @param array $attribs  Element attributes
+     * @param bool  $escape   Enables escaping of the content
+     *
+     * @return string HTML output of the div tag
+     */
     public static function div($attribs = array(), $escape = false)
     {
         $elem_attribs = array_merge(self::$common_attribs, self::$event_attribs);
@@ -230,6 +320,14 @@ class kolab_html
             self::attrib_string($attribs, $elem_attribs), $content);
     }
 
+    /**
+     * Span element.
+     *
+     * @param array $attribs  Element attributes
+     * @param bool  $escape   Enables escaping of the content
+     *
+     * @return string HTML output of the span tag
+     */
     public static function span($attribs = array(), $escape = false)
     {
         $elem_attribs = array_merge(self::$common_attribs, self::$event_attribs);
@@ -244,6 +342,14 @@ class kolab_html
             self::attrib_string($attribs, $elem_attribs), $content);
     }
 
+    /**
+     * Form element.
+     *
+     * @param array  $attribs  Element attributes
+     * @param string $escape   Content of the form
+     *
+     * @return string HTML output of the form tag
+     */
     public static function form($attribs = array(), $content = null)
     {
         $elem_attribs = array_merge(self::$form_attribs, self::$common_attribs, self::$event_attribs);
@@ -252,6 +358,14 @@ class kolab_html
             self::attrib_string($attribs, $elem_attribs), $content);
     }
 
+    /**
+     * Script element.
+     *
+     * @param array $attribs  Element attributes
+     * @param bool  $escape   Enables escaping of the content
+     *
+     * @return string HTML output of the script tag
+     */
     public static function script($content = null, $escape = false)
     {
         if ($escape) {
@@ -314,6 +428,13 @@ class kolab_html
         return count($attrib_arr) ? ' '.implode(' ', $attrib_arr) : '';
     }
 
+    /**
+     * Escape special characters into HTML entities.
+     *
+     * @param string|array $value  Value to escape
+     *
+     * @return string|array Escaped value
+     */
     public static function escape($value)
     {
         if (is_array($value)) {
diff --git a/lib/kolab_recipient_policy.php b/lib/kolab_recipient_policy.php
index f7b9558..94dc008 100644
--- a/lib/kolab_recipient_policy.php
+++ b/lib/kolab_recipient_policy.php
@@ -211,4 +211,3 @@ class kolab_recipient_policy {
 
     }
 }
-?>
diff --git a/lib/kolab_utils.php b/lib/kolab_utils.php
index b80bc6a..9c6c35e 100644
--- a/lib/kolab_utils.php
+++ b/lib/kolab_utils.php
@@ -23,6 +23,9 @@
  +--------------------------------------------------------------------------+
 */
 
+/**
+ * Utilities class
+ */
 class kolab_utils
 {
     const REQUEST_ANY  = 0;