From 356b2582f3e6a43ecf2607acad4a7fe0b37f659a Mon Sep 17 00:00:00 2001
From: Bot <bot@myigel.name>
Date: Tue, 3 Jan 2017 03:22:48 +0100
Subject: PPHDoc, formatting, fixes, cleanup

---
 includes/model/AngelType_model.php          |  38 ++++----
 includes/model/EventConfig_model.php        |   4 +
 includes/model/LogEntries_model.php         |  13 ++-
 includes/model/Message_model.php            |  13 +--
 includes/model/NeededAngelTypes_model.php   |  13 +--
 includes/model/Room_model.php               |  13 ++-
 includes/model/ShiftEntry_model.php         |  31 ++++++-
 includes/model/ShiftSignupState.php         |  21 ++++-
 includes/model/ShiftTypes_model.php         |   7 +-
 includes/model/ShiftsFilter.php             |  51 ++++++++++-
 includes/model/Shifts_model.php             | 131 ++++++++++++++++++++--------
 includes/model/UserAngelTypes_model.php     |  43 +++++----
 includes/model/UserDriverLicenses_model.php |  27 +++---
 includes/model/UserGroups_model.php         |   3 +-
 includes/model/User_model.php               |  59 ++++++++++---
 includes/model/ValidationResult.php         |  14 +--
 16 files changed, 353 insertions(+), 128 deletions(-)

(limited to 'includes/model')

diff --git a/includes/model/AngelType_model.php b/includes/model/AngelType_model.php
index d52b1357..eedcdfbc 100644
--- a/includes/model/AngelType_model.php
+++ b/includes/model/AngelType_model.php
@@ -24,8 +24,7 @@ function AngelType_new()
 /**
  * Validates the contact user
  *
- * @param Angeltype $angeltype
- *          The angeltype
+ * @param array $angeltype The angeltype
  * @return ValidationResult
  */
 function AngelType_validate_contact_user_id($angeltype)
@@ -45,8 +44,8 @@ function AngelType_validate_contact_user_id($angeltype)
 /**
  * Returns contact data (name, dect, email) for given angeltype or null
  *
- * @param Angeltype $angeltype
- *          The angeltype
+ * @param array $angeltype The angeltype
+ * @return array|null
  */
 function AngelType_contact_info($angeltype)
 {
@@ -68,13 +67,15 @@ function AngelType_contact_info($angeltype)
             'contact_email' => $angeltype['contact_email']
         ];
     }
+
     return null;
 }
 
 /**
  * Delete an Angeltype.
  *
- * @param Angeltype $angeltype
+ * @param array $angeltype
+ * @return mysqli_result
  */
 function AngelType_delete($angeltype)
 {
@@ -92,8 +93,8 @@ function AngelType_delete($angeltype)
 /**
  * Update Angeltype.
  *
- * @param Angeltype $angeltype
- *          The angeltype
+ * @param array $angeltype The angeltype
+ * @return mysqli_result
  */
 function AngelType_update($angeltype)
 {
@@ -119,9 +120,8 @@ function AngelType_update($angeltype)
 /**
  * Create an Angeltype.
  *
- * @param Angeltype $angeltype
- *          The angeltype
- * @return the created angeltype
+ * @param array $angeltype The angeltype
+ * @return array the created angeltype
  */
 function AngelType_create($angeltype)
 {
@@ -148,10 +148,9 @@ function AngelType_create($angeltype)
  * Validates a name for angeltypes.
  * Returns ValidationResult containing validation success and validated name.
  *
- * @param string    $name
- *          Wanted name for the angeltype
- * @param AngelType $angeltype
- *          The angeltype the name is for
+ * @param string $name      Wanted name for the angeltype
+ * @param array  $angeltype The angeltype the name is for
+ *
  * @return ValidationResult result and validated name
  */
 function AngelType_validate_name($name, $angeltype)
@@ -180,7 +179,8 @@ function AngelType_validate_name($name, $angeltype)
 /**
  * Returns all angeltypes and subscription state to each of them for given user.
  *
- * @param User $user
+ * @param array $user
+ * @return array
  */
 function AngelTypes_with_user($user)
 {
@@ -201,6 +201,8 @@ function AngelTypes_with_user($user)
 
 /**
  * Returns all angeltypes.
+ *
+ * @return array
  */
 function AngelTypes()
 {
@@ -216,6 +218,8 @@ function AngelTypes()
 
 /**
  * Returns AngelType id array
+ *
+ * @return array
  */
 function AngelType_ids()
 {
@@ -229,8 +233,8 @@ function AngelType_ids()
 /**
  * Returns angelType by id.
  *
- * @param $angeltype_id angelType
- *                      ID
+ * @param int $angeltype_id angelType ID
+ * @return array
  */
 function AngelType($angeltype_id)
 {
diff --git a/includes/model/EventConfig_model.php b/includes/model/EventConfig_model.php
index 584c1515..93ba1e72 100644
--- a/includes/model/EventConfig_model.php
+++ b/includes/model/EventConfig_model.php
@@ -2,6 +2,8 @@
 
 /**
  * Get event config.
+ *
+ * łreturn array|false|null
  */
 function EventConfig()
 {
@@ -25,6 +27,7 @@ function EventConfig()
  * @param int    $event_end_date
  * @param int    $teardown_end_date
  * @param string $event_welcome_msg
+ * @return mysqli_result|false
  */
 function EventConfig_update(
     $event_name,
@@ -43,6 +46,7 @@ function EventConfig_update(
       `teardown_end_date`=" . sql_null($teardown_end_date) . ",
       `event_welcome_msg`=" . sql_null($event_welcome_msg));
     }
+
     return sql_query("UPDATE `EventConfig` SET
       `event_name`=" . sql_null($event_name) . ", 
       `buildup_start_date`=" . sql_null($buildup_start_date) . ",
diff --git a/includes/model/LogEntries_model.php b/includes/model/LogEntries_model.php
index 47e48f6f..7bcb868e 100644
--- a/includes/model/LogEntries_model.php
+++ b/includes/model/LogEntries_model.php
@@ -3,9 +3,9 @@
 /**
  * Creates a log entry.
  *
- * @param $nick    Username
- * @param $message Log
- *                 Message
+ * @param string $nick    Username
+ * @param string $message Log  Message
+ * @return mysqli_result|false
  */
 function LogEntry_create($nick, $message)
 {
@@ -14,6 +14,8 @@ function LogEntry_create($nick, $message)
 
 /**
  * Returns log entries with maximum count of 10000.
+ *
+ * @return array|false
  */
 function LogEntries()
 {
@@ -22,6 +24,9 @@ function LogEntries()
 
 /**
  * Returns log entries filtered by a keyword
+ *
+ * @param string $keyword
+ * @return array|false
  */
 function LogEntries_filter($keyword)
 {
@@ -33,6 +38,8 @@ function LogEntries_filter($keyword)
 
 /**
  * Delete all log entries.
+ *
+ * @return mysqli_result|false
  */
 function LogEntries_clear_all()
 {
diff --git a/includes/model/Message_model.php b/includes/model/Message_model.php
index 39eada71..57277fbe 100644
--- a/includes/model/Message_model.php
+++ b/includes/model/Message_model.php
@@ -2,6 +2,8 @@
 
 /**
  * Returns Message id array
+ *
+ * @return array|false
  */
 function Message_ids()
 {
@@ -11,8 +13,8 @@ function Message_ids()
 /**
  * Returns message by id.
  *
- * @param $message_id message
- *                    ID
+ * @param int $message_id message ID
+ * @return array|false|null
  */
 function Message($message_id)
 {
@@ -31,10 +33,9 @@ function Message($message_id)
  * TODO: global $user con not be used in model!
  * send message
  *
- * @param $receiver_user_id User
- *                          ID of Reciever
- * @param $text             Text
- *                          of Message
+ * @param int    $receiver_user_id User ID of Reciever
+ * @param string $text             Text of Message
+ * @return bool
  */
 function Message_send($receiver_user_id, $text)
 {
diff --git a/includes/model/NeededAngelTypes_model.php b/includes/model/NeededAngelTypes_model.php
index 6a929f2f..ef4698de 100644
--- a/includes/model/NeededAngelTypes_model.php
+++ b/includes/model/NeededAngelTypes_model.php
@@ -15,6 +15,7 @@
  *          The room. Can be null, but then a shift_id must be given.
  * @param int $count
  *          How many angels are needed?
+ * @return false|int
  */
 function NeededAngelType_add($shift_id, $angeltype_id, $room_id, $count)
 {
@@ -33,8 +34,8 @@ function NeededAngelType_add($shift_id, $angeltype_id, $room_id, $count)
 /**
  * Deletes all needed angel types from given shift.
  *
- * @param int $shift_id
- *          id of the shift
+ * @param int $shift_id id of the shift
+ * @return mysqli_result|false
  */
 function NeededAngelTypes_delete_by_shift($shift_id)
 {
@@ -44,8 +45,8 @@ function NeededAngelTypes_delete_by_shift($shift_id)
 /**
  * Deletes all needed angel types from given room.
  *
- * @param int $room_id
- *          id of the room
+ * @param int $room_id id of the room
+ * @return mysqli_result|false
  */
 function NeededAngelTypes_delete_by_room($room_id)
 {
@@ -55,8 +56,8 @@ function NeededAngelTypes_delete_by_room($room_id)
 /**
  * Returns all needed angeltypes and already taken needs.
  *
- * @param int $shiftID
- *          id of shift
+ * @param int $shiftId id of shift
+ * @return array
  */
 function NeededAngelTypes_by_shift($shiftId)
 {
diff --git a/includes/model/Room_model.php b/includes/model/Room_model.php
index 4c097f23..9c202c1e 100644
--- a/includes/model/Room_model.php
+++ b/includes/model/Room_model.php
@@ -4,6 +4,7 @@
  * returns a list of rooms.
  *
  * @param boolean $show_all returns also hidden rooms when true
+ * @return array|false
  */
 function Rooms($show_all = false)
 {
@@ -14,6 +15,7 @@ function Rooms($show_all = false)
  * Delete a room
  *
  * @param int $room_id
+ * @return mysqli_result|false
  */
 function Room_delete($room_id)
 {
@@ -29,15 +31,19 @@ function Room_delete($room_id)
  *          Is this a frab imported room?
  * @param boolean $public
  *          Is the room visible for angels?
+ * @param int     $number
+ *          Room number
+ * @return false|int
  */
-function Room_create($name, $from_frab, $public)
+function Room_create($name, $from_frab, $public, $number = null)
 {
     $result = sql_query("
       INSERT INTO `Room` SET 
       `Name`='" . sql_escape($name) . "', 
       `FromPentabarf`='" . sql_escape($from_frab ? 'Y' : '') . "', 
       `show`='" . sql_escape($public ? 'Y' : '') . "', 
-      `Number`=0");
+      `Number`=" . (int)$number
+    );
     if ($result === false) {
         return false;
     }
@@ -47,7 +53,8 @@ function Room_create($name, $from_frab, $public)
 /**
  * Returns room by id.
  *
- * @param $room_id RID
+ * @param int $room_id RID
+ * @return array|false
  */
 function Room($room_id)
 {
diff --git a/includes/model/ShiftEntry_model.php b/includes/model/ShiftEntry_model.php
index a0755e3c..84cdb6d8 100644
--- a/includes/model/ShiftEntry_model.php
+++ b/includes/model/ShiftEntry_model.php
@@ -3,6 +3,8 @@
 /**
  * Returns an array with the attributes of shift entries.
  * FIXME! Needs entity object.
+ *
+ * @return array
  */
 function ShiftEntry_new()
 {
@@ -19,14 +21,19 @@ function ShiftEntry_new()
 
 /**
  * Counts all freeloaded shifts.
+ *
+ * @return int
  */
 function ShiftEntries_freeleaded_count()
 {
-    return sql_select_single_cell("SELECT COUNT(*) FROM `ShiftEntry` WHERE `freeloaded` = 1");
+    return (int)sql_select_single_cell("SELECT COUNT(*) FROM `ShiftEntry` WHERE `freeloaded` = 1");
 }
 
 /**
  * List users subsribed to a given shift.
+ *
+ * @param int $shift_id
+ * @return array|false
  */
 function ShiftEntries_by_shift($shift_id)
 {
@@ -52,7 +59,8 @@ function ShiftEntries_by_shift($shift_id)
 /**
  * Create a new shift entry.
  *
- * @param ShiftEntry $shift_entry
+ * @param array $shift_entry
+ * @return mysqli_result|false
  */
 function ShiftEntry_create($shift_entry)
 {
@@ -68,6 +76,9 @@ function ShiftEntry_create($shift_entry)
 
 /**
  * Update a shift entry.
+ *
+ * @param array $shift_entry
+ * @return false|mysqli_result
  */
 function ShiftEntry_update($shift_entry)
 {
@@ -80,6 +91,9 @@ function ShiftEntry_update($shift_entry)
 
 /**
  * Get a shift entry.
+ *
+ * @param int $shift_entry_id
+ * @return array|false|null
  */
 function ShiftEntry($shift_entry_id)
 {
@@ -95,6 +109,9 @@ function ShiftEntry($shift_entry_id)
 
 /**
  * Delete a shift entry.
+ *
+ * @param int $shift_entry_id
+ * @return mysqli_result|false
  */
 function ShiftEntry_delete($shift_entry_id)
 {
@@ -106,7 +123,8 @@ function ShiftEntry_delete($shift_entry_id)
 /**
  * Returns next (or current) shifts of given user.
  *
- * @param User $user
+ * @param array $user
+ * @return array|false
  */
 function ShiftEntries_upcoming_for_user($user)
 {
@@ -124,7 +142,8 @@ function ShiftEntries_upcoming_for_user($user)
 /**
  * Returns shifts completed by the given user.
  *
- * @param User $user
+ * @param array $user
+ * @return array|false
  */
 function ShiftEntries_finished_by_user($user)
 {
@@ -145,6 +164,7 @@ function ShiftEntries_finished_by_user($user)
  *
  * @param int $shift_id
  * @param int $angeltype_id
+ * @return array|false
  */
 function ShiftEntries_by_shift_and_angeltype($shift_id, $angeltype_id)
 {
@@ -162,6 +182,9 @@ function ShiftEntries_by_shift_and_angeltype($shift_id, $angeltype_id)
 
 /**
  * Returns all freeloaded shifts for given user.
+ *
+ * @param array $user
+ * @return array|false
  */
 function ShiftEntries_freeloaded_by_user($user)
 {
diff --git a/includes/model/ShiftSignupState.php b/includes/model/ShiftSignupState.php
index d5c7f457..9b3de496 100644
--- a/includes/model/ShiftSignupState.php
+++ b/includes/model/ShiftSignupState.php
@@ -8,7 +8,6 @@ namespace Engelsystem;
  */
 class ShiftSignupState
 {
-
     /**
      * Shift has free places
      */
@@ -44,10 +43,18 @@ class ShiftSignupState
      */
     const SIGNED_UP = 'SIGNED_UP';
 
+    /** @var string */
     private $state;
 
+    /** @var int */
     private $freeEntries;
 
+    /**
+     * ShiftSignupState constructor.
+     *
+     * @param string $state
+     * @param int    $free_entries
+     */
     public function __construct($state, $free_entries)
     {
         $this->state = $state;
@@ -69,6 +76,10 @@ class ShiftSignupState
         }
     }
 
+    /**
+     * @param string $state
+     * @return int
+     */
     private function valueForState($state)
     {
         switch ($state) {
@@ -88,11 +99,15 @@ class ShiftSignupState
             case ShiftSignupState::OCCUPIED:
             case ShiftSignupState::ADMIN:
                 return 60;
+            default:
+                return 0;
         }
     }
 
     /**
      * Returns true, if signup is allowed
+     *
+     * @return bool
      */
     public function isSignupAllowed()
     {
@@ -106,6 +121,8 @@ class ShiftSignupState
 
     /**
      * Return the shift signup state
+     *
+     * @return string
      */
     public function getState()
     {
@@ -114,6 +131,8 @@ class ShiftSignupState
 
     /**
      * How many places are free in this shift for the angeltype?
+     *
+     * @return int
      */
     public function getFreeEntries()
     {
diff --git a/includes/model/ShiftTypes_model.php b/includes/model/ShiftTypes_model.php
index 8b1d56b8..ba8fa2c1 100644
--- a/includes/model/ShiftTypes_model.php
+++ b/includes/model/ShiftTypes_model.php
@@ -4,6 +4,7 @@
  * Delete a shift type.
  *
  * @param int $shifttype_id
+ * @return mysqli_result|false
  */
 function ShiftType_delete($shifttype_id)
 {
@@ -17,6 +18,7 @@ function ShiftType_delete($shifttype_id)
  * @param string $name
  * @param int    $angeltype_id
  * @param string $description
+ * @return mysqli_result|false
  */
 function ShiftType_update($shifttype_id, $name, $angeltype_id, $description)
 {
@@ -35,7 +37,7 @@ function ShiftType_update($shifttype_id, $name, $angeltype_id, $description)
  * @param string $name
  * @param int    $angeltype_id
  * @param string $description
- * @return new shifttype id
+ * @return int|false new shifttype id
  */
 function ShiftType_create($name, $angeltype_id, $description)
 {
@@ -55,6 +57,7 @@ function ShiftType_create($name, $angeltype_id, $description)
  * Get a shift type by id.
  *
  * @param int $shifttype_id
+ * @return array|null
  */
 function ShiftType($shifttype_id)
 {
@@ -70,6 +73,8 @@ function ShiftType($shifttype_id)
 
 /**
  * Get all shift types.
+ *
+ * @return array|false
  */
 function ShiftTypes()
 {
diff --git a/includes/model/ShiftsFilter.php b/includes/model/ShiftsFilter.php
index 1e8d49cf..47ef50d7 100644
--- a/includes/model/ShiftsFilter.php
+++ b/includes/model/ShiftsFilter.php
@@ -9,12 +9,11 @@ namespace Engelsystem;
  */
 class ShiftsFilter
 {
-
     /**
      * How long can the time interval be?
+     * 86400 = one day
      */
     const MAX_DURATION = 86400;
-    // one day
 
     /**
      * Shift is completely full.
@@ -33,16 +32,28 @@ class ShiftsFilter
      */
     private $userShiftsAdmin;
 
+    /** @var int[] */
     private $filled = [];
 
+    /** @var int[] */
     private $rooms = [];
 
+    /** @var int[] */
     private $types = [];
 
+    /** @var int unix timestamp */
     private $startTime = null;
 
+    /** @var int unix timestamp */
     private $endTime = null;
 
+    /**
+     * ShiftsFilter constructor.
+     *
+     * @param bool  $user_shifts_admin
+     * @param int[] $rooms
+     * @param int[] $types
+     */
     public function __construct($user_shifts_admin, $rooms, $types)
     {
         $this->user_shifts_admin = $user_shifts_admin;
@@ -58,21 +69,33 @@ class ShiftsFilter
         }
     }
 
+    /**
+     * @return int unix timestamp
+     */
     public function getStartTime()
     {
         return $this->startTime;
     }
 
+    /**
+     * @param int $startTime unix timestamp
+     */
     public function setStartTime($startTime)
     {
         $this->startTime = $startTime;
     }
 
+    /**
+     * @return int unix timestamp
+     */
     public function getEndTime()
     {
         return $this->endTime;
     }
 
+    /**
+     * @param int $endTime unix timestamp
+     */
     public function setEndTime($endTime)
     {
         if ($endTime - $this->startTime > ShiftsFilter::MAX_DURATION) {
@@ -81,6 +104,9 @@ class ShiftsFilter
         $this->endTime = $endTime;
     }
 
+    /**
+     * @return int[]
+     */
     public function getTypes()
     {
         if (count($this->types) == 0) {
@@ -89,11 +115,17 @@ class ShiftsFilter
         return $this->types;
     }
 
+    /**
+     * @param int[] $types
+     */
     public function setTypes($types)
     {
         $this->types = $types;
     }
 
+    /**
+     * @return int[]
+     */
     public function getRooms()
     {
         if (count($this->rooms) == 0) {
@@ -102,26 +134,41 @@ class ShiftsFilter
         return $this->rooms;
     }
 
+    /**
+     * @param int[] $rooms
+     */
     public function setRooms($rooms)
     {
         $this->rooms = $rooms;
     }
 
+    /**
+     * @return bool
+     */
     public function isUserShiftsAdmin()
     {
         return $this->userShiftsAdmin;
     }
 
+    /**
+     * @param bool $userShiftsAdmin
+     */
     public function setUserShiftsAdmin($userShiftsAdmin)
     {
         $this->userShiftsAdmin = $userShiftsAdmin;
     }
 
+    /**
+     * @return int[]
+     */
     public function getFilled()
     {
         return $this->filled;
     }
 
+    /**
+     * @param int[] $filled
+     */
     public function setFilled($filled)
     {
         $this->filled = $filled;
diff --git a/includes/model/Shifts_model.php b/includes/model/Shifts_model.php
index c489c63e..7c52d305 100644
--- a/includes/model/Shifts_model.php
+++ b/includes/model/Shifts_model.php
@@ -2,6 +2,10 @@
 use Engelsystem\ShiftsFilter;
 use Engelsystem\ShiftSignupState;
 
+/**
+ * @param array $room
+ * @return array
+ */
 function Shifts_by_room($room)
 {
     $result = sql_select("SELECT * FROM `Shifts` WHERE `RID`=" . sql_escape($room['RID']) . " ORDER BY `start`");
@@ -11,6 +15,10 @@ function Shifts_by_room($room)
     return $result;
 }
 
+/**
+ * @param ShiftsFilter $shiftsFilter
+ * @return array[]
+ */
 function Shifts_by_ShiftsFilter(ShiftsFilter $shiftsFilter)
 {
     $SQL = "SELECT * FROM (
@@ -46,6 +54,10 @@ function Shifts_by_ShiftsFilter(ShiftsFilter $shiftsFilter)
     return $result;
 }
 
+/**
+ * @param ShiftsFilter $shiftsFilter
+ * @return array
+ */
 function NeededAngeltypes_by_ShiftsFilter(ShiftsFilter $shiftsFilter)
 {
     $SQL = "
@@ -85,6 +97,11 @@ function NeededAngeltypes_by_ShiftsFilter(ShiftsFilter $shiftsFilter)
     return $result;
 }
 
+/**
+ * @param array $shift
+ * @param array $angeltype
+ * @return array|null
+ */
 function NeededAngeltype_by_Shift_and_Angeltype($shift, $angeltype)
 {
     $result = sql_select("
@@ -126,6 +143,10 @@ function NeededAngeltype_by_Shift_and_Angeltype($shift, $angeltype)
     return $result[0];
 }
 
+/**
+ * @param ShiftsFilter $shiftsFilter
+ * @return array
+ */
 function ShiftEntries_by_ShiftsFilter(ShiftsFilter $shiftsFilter)
 {
     $SQL = "
@@ -156,8 +177,9 @@ function ShiftEntries_by_ShiftsFilter(ShiftsFilter $shiftsFilter)
 /**
  * Check if a shift collides with other shifts (in time).
  *
- * @param Shift $shift
- * @param       array <Shift> $shifts
+ * @param array $shift
+ * @param array $shifts
+ * @return bool
  */
 function Shift_collides($shift, $shifts)
 {
@@ -173,6 +195,10 @@ function Shift_collides($shift, $shifts)
 
 /**
  * Returns the number of needed angels/free shift entries for an angeltype.
+ *
+ * @param array   $needed_angeltype
+ * @param array[] $shift_entries
+ * @return int
  */
 function Shift_free_entries($needed_angeltype, $shift_entries)
 {
@@ -188,15 +214,14 @@ function Shift_free_entries($needed_angeltype, $shift_entries)
 /**
  * Check if shift signup is allowed from the end users point of view (no admin like privileges)
  *
- * @param Shift     $shift
- *                        The shift
- * @param AngelType $angeltype
- *                        The angeltype to which the user wants to sign up
- * @param           array <Shift> $user_shifts
- *                        List of the users shifts
- * @param boolean   $angeltype_supporter
- *                        True, if the user has angeltype supporter rights for the angeltype, which enables him to sign
- *                        somebody up for the shift.
+ * @param array      $user
+ * @param array      $shift       The shift
+ * @param array      $angeltype   The angeltype to which the user wants to sign up
+ * @param array|null $user_angeltype
+ * @param array|null $user_shifts List of the users shifts
+ * @param array      $needed_angeltype
+ * @param array[]    $shift_entries
+ * @return ShiftSignupState
  */
 function Shift_signup_allowed_angel(
     $user,
@@ -266,6 +291,13 @@ function Shift_signup_allowed_angel(
 
 /**
  * Check if an angeltype supporter can sign up a user to a shift.
+ *
+ * @TODO: remove $angeltype
+ *
+ * @param array|null $angeltype
+ * @param array      $needed_angeltype
+ * @param array[]    $shift_entries
+ * @return ShiftSignupState
  */
 function Shift_signup_allowed_angeltype_supporter($angeltype, $needed_angeltype, $shift_entries)
 {
@@ -280,10 +312,12 @@ function Shift_signup_allowed_angeltype_supporter($angeltype, $needed_angeltype,
 /**
  * Check if an admin can sign up a user to a shift.
  *
- * @param Shift     $shift
- *          The shift
- * @param AngelType $angeltype
- *          The angeltype to which the user wants to sign up
+ * @TODO: remove $angeltype
+ *
+ * @param array|null $angeltype The angeltype to which the user wants to sign up
+ * @param array      $needed_angeltype
+ * @param array[]    $shift_entries
+ * @return ShiftSignupState
  */
 function Shift_signup_allowed_admin($angeltype, $needed_angeltype, $shift_entries)
 {
@@ -300,12 +334,14 @@ function Shift_signup_allowed_admin($angeltype, $needed_angeltype, $shift_entrie
 /**
  * Check if an angel can sign up for given shift.
  *
- * @param Shift     $shift
- *                        The shift
- * @param AngelType $angeltype
- *                        The angeltype to which the user wants to sign up
- * @param           array <Shift> $user_shifts
- *                        List of the users shifts
+ * @param array      $signup_user
+ * @param array      $shift       The shift
+ * @param array      $angeltype   The angeltype to which the user wants to sign up
+ * @param array|null $user_angeltype
+ * @param array|null $user_shifts List of the users shifts
+ * @param array      $needed_angeltype
+ * @param array[]    $shift_entries
+ * @return ShiftSignupState
  */
 function Shift_signup_allowed(
     $signup_user,
@@ -342,6 +378,9 @@ function Shift_signup_allowed(
 
 /**
  * Delete a shift by its external id.
+ *
+ * @param int $shift_psid
+ * @return mysqli_result|false
  */
 function Shift_delete_by_psid($shift_psid)
 {
@@ -350,6 +389,9 @@ function Shift_delete_by_psid($shift_psid)
 
 /**
  * Delete a shift.
+ *
+ * @param int $shift_id
+ * @return mysqli_result
  */
 function Shift_delete($shift_id)
 {
@@ -364,6 +406,9 @@ function Shift_delete($shift_id)
 
 /**
  * Update a shift.
+ *
+ * @param array $shift
+ * @return mysqli_result|false
  */
 function Shift_update($shift)
 {
@@ -388,6 +433,9 @@ function Shift_update($shift)
 
 /**
  * Update a shift by its external id.
+ *
+ * @param array $shift
+ * @return mysqli_result|false|null
  */
 function Shift_update_by_psid($shift)
 {
@@ -405,7 +453,8 @@ function Shift_update_by_psid($shift)
 /**
  * Create a new shift.
  *
- * @return new shift id or false
+ * @param array $shift
+ * @return int|false shift id or false
  */
 function Shift_create($shift)
 {
@@ -430,20 +479,24 @@ function Shift_create($shift)
 
 /**
  * Return users shifts.
+ *
+ * @param array $user
+ * @param bool  $include_freeload_comments
+ * @return array
  */
 function Shifts_by_user($user, $include_freeload_comments = false)
 {
     $result = sql_select("
-      SELECT `ShiftTypes`.`id` as `shifttype_id`, `ShiftTypes`.`name`,
-      `ShiftEntry`.`id`, `ShiftEntry`.`SID`, `ShiftEntry`.`TID`, `ShiftEntry`.`UID`, `ShiftEntry`.`freeloaded`, `ShiftEntry`.`Comment`,
-      " . ($include_freeload_comments ? "`ShiftEntry`.`freeload_comment`, " : "") . "
-      `Shifts`.*, `Room`.* 
-      FROM `ShiftEntry` 
-      JOIN `Shifts` ON (`ShiftEntry`.`SID` = `Shifts`.`SID`) 
-      JOIN `ShiftTypes` ON (`ShiftTypes`.`id` = `Shifts`.`shifttype_id`)
-      JOIN `Room` ON (`Shifts`.`RID` = `Room`.`RID`) 
-      WHERE `UID`='" . sql_escape($user['UID']) . "' 
-      ORDER BY `start`
+          SELECT `ShiftTypes`.`id` AS `shifttype_id`, `ShiftTypes`.`name`,
+          `ShiftEntry`.`id`, `ShiftEntry`.`SID`, `ShiftEntry`.`TID`, `ShiftEntry`.`UID`, `ShiftEntry`.`freeloaded`, `ShiftEntry`.`Comment`,
+          " . ($include_freeload_comments ? "`ShiftEntry`.`freeload_comment`, " : "") . "
+          `Shifts`.*, `Room`.* 
+          FROM `ShiftEntry` 
+          JOIN `Shifts` ON (`ShiftEntry`.`SID` = `Shifts`.`SID`) 
+          JOIN `ShiftTypes` ON (`ShiftTypes`.`id` = `Shifts`.`shifttype_id`)
+          JOIN `Room` ON (`Shifts`.`RID` = `Room`.`RID`) 
+          WHERE `UID`='" . sql_escape($user['UID']) . "' 
+          ORDER BY `start`
       ");
     if ($result === false) {
         engelsystem_error('Unable to load users shifts.');
@@ -454,8 +507,8 @@ function Shifts_by_user($user, $include_freeload_comments = false)
 /**
  * Returns Shift by id.
  *
- * @param $shift_id Shift
- *                  ID
+ * @param int $shift_id Shift  ID
+ * @return array|null
  */
 function Shift($shift_id)
 {
@@ -494,14 +547,16 @@ function Shift($shift_id)
 
 /**
  * Returns all shifts with needed angeltypes and count of subscribed jobs.
+ *
+ * @return array|false
  */
 function Shifts()
 {
     $shifts_source = sql_select("
-    SELECT `ShiftTypes`.`name`, `Shifts`.*, `Room`.`RID`, `Room`.`Name` AS `room_name` 
-    FROM `Shifts`
-    JOIN `ShiftTypes` ON (`ShiftTypes`.`id` = `Shifts`.`shifttype_id`)
-    JOIN `Room` ON `Room`.`RID` = `Shifts`.`RID`
+        SELECT `ShiftTypes`.`name`, `Shifts`.*, `Room`.`RID`, `Room`.`Name` AS `room_name` 
+        FROM `Shifts`
+        JOIN `ShiftTypes` ON (`ShiftTypes`.`id` = `Shifts`.`shifttype_id`)
+        JOIN `Room` ON `Room`.`RID` = `Shifts`.`RID`
     ");
     if ($shifts_source === false) {
         return false;
diff --git a/includes/model/UserAngelTypes_model.php b/includes/model/UserAngelTypes_model.php
index fae2b996..4b071847 100644
--- a/includes/model/UserAngelTypes_model.php
+++ b/includes/model/UserAngelTypes_model.php
@@ -7,10 +7,8 @@
 /**
  * Checks if a user joined an angeltype.
  *
- * @param User      $user
- *          The user to be checked
- * @param Angeltype $angeltype
- *          The angeltype to be checked
+ * @param array $user      The user to be checked
+ * @param array $angeltype The angeltype to be checked
  * @return boolean
  */
 function UserAngelType_exists($user, $angeltype)
@@ -26,7 +24,8 @@ function UserAngelType_exists($user, $angeltype)
 /**
  * List users angeltypes.
  *
- * @param User $user
+ * @param array $user
+ * @return array|false
  */
 function User_angeltypes($user)
 {
@@ -46,7 +45,8 @@ function User_angeltypes($user)
 /**
  * Gets unconfirmed user angeltypes for angeltypes of which the given user is a supporter.
  *
- * @param User $user
+ * @param array $user
+ * @return array
  */
 function User_unconfirmed_AngelTypes($user)
 {
@@ -74,8 +74,9 @@ function User_unconfirmed_AngelTypes($user)
 /**
  * Returns true if user is angeltype supporter or has privilege admin_user_angeltypes.
  *
- * @param User      $user
- * @param AngelType $angeltype
+ * @param array $user
+ * @param array $angeltype
+ * @return bool
  */
 function User_is_AngelType_supporter(&$user, $angeltype)
 {
@@ -97,6 +98,7 @@ function User_is_AngelType_supporter(&$user, $angeltype)
  *
  * @param int  $user_angeltype_id
  * @param bool $supporter
+ * @return mysqli_result
  */
 function UserAngelType_update($user_angeltype_id, $supporter)
 {
@@ -116,6 +118,7 @@ function UserAngelType_update($user_angeltype_id, $supporter)
  * Delete all unconfirmed UserAngelTypes for given Angeltype.
  *
  * @param int $angeltype_id
+ * @return mysqli_result
  */
 function UserAngelTypes_delete_all($angeltype_id)
 {
@@ -133,8 +136,9 @@ function UserAngelTypes_delete_all($angeltype_id)
 /**
  * Confirm all unconfirmed UserAngelTypes for given Angeltype.
  *
- * @param int  $angeltype_id
- * @param User $confirm_user
+ * @param int   $angeltype_id
+ * @param array $confirm_user
+ * @return mysqli_result
  */
 function UserAngelTypes_confirm_all($angeltype_id, $confirm_user)
 {
@@ -153,8 +157,9 @@ function UserAngelTypes_confirm_all($angeltype_id, $confirm_user)
 /**
  * Confirm an UserAngelType with confirming user.
  *
- * @param int  $user_angeltype_id
- * @param User $confirm_user
+ * @param int   $user_angeltype_id
+ * @param array $confirm_user
+ * @return mysqli_result
  */
 function UserAngelType_confirm($user_angeltype_id, $confirm_user)
 {
@@ -172,7 +177,8 @@ function UserAngelType_confirm($user_angeltype_id, $confirm_user)
 /**
  * Delete an UserAngelType.
  *
- * @param UserAngelType $user_angeltype
+ * @param array $user_angeltype
+ * @return mysqli_result|false
  */
 function UserAngelType_delete($user_angeltype)
 {
@@ -185,8 +191,9 @@ function UserAngelType_delete($user_angeltype)
 /**
  * Create an UserAngelType.
  *
- * @param User      $user
- * @param Angeltype $angeltype
+ * @param array $user
+ * @param array $angeltype
+ * @return int
  */
 function UserAngelType_create($user, $angeltype)
 {
@@ -204,6 +211,7 @@ function UserAngelType_create($user, $angeltype)
  * Get an UserAngelType by its id.
  *
  * @param int $user_angeltype_id
+ * @return array|null
  */
 function UserAngelType($user_angeltype_id)
 {
@@ -224,8 +232,9 @@ function UserAngelType($user_angeltype_id)
 /**
  * Get an UserAngelType by user and angeltype.
  *
- * @param User      $user
- * @param Angeltype $angeltype
+ * @param array $user
+ * @param array $angeltype
+ * @return array|null
  */
 function UserAngelType_by_User_and_AngelType($user, $angeltype)
 {
diff --git a/includes/model/UserDriverLicenses_model.php b/includes/model/UserDriverLicenses_model.php
index a36b79c1..c1cd081b 100644
--- a/includes/model/UserDriverLicenses_model.php
+++ b/includes/model/UserDriverLicenses_model.php
@@ -3,6 +3,8 @@
 /**
  * Returns a new empty UserDriverLicense
  * FIXME entity object needed
+ *
+ * @return array
  */
 function UserDriverLicense_new()
 {
@@ -20,8 +22,7 @@ function UserDriverLicense_new()
 /**
  * Is it valid?
  *
- * @param UserDriverLicense $user_driver_license
- *          The UserDriverLicense to check
+ * @param array $user_driver_license The UserDriverLicense to check
  * @return boolean
  */
 function UserDriverLicense_valid($user_driver_license)
@@ -37,8 +38,8 @@ function UserDriverLicense_valid($user_driver_license)
 /**
  * Get a users driver license information
  *
- * @param int $user_id
- *          The users id
+ * @param int $user_id The users id
+ * @return array|false|null
  */
 function UserDriverLicense($user_id)
 {
@@ -47,17 +48,20 @@ function UserDriverLicense($user_id)
         engelsystem_error('Unable to load user driver license.');
         return false;
     }
-    if (count($user_driver_license) > 0) {
-        return $user_driver_license[0];
+
+    if (count($user_driver_license) == 0) {
+        return null;
     }
-    return null;
+
+    return $user_driver_license[0];
 }
 
 /**
  * Create a user's driver license entry
  *
- * @param UserDriverLicense $user_driver_license
- *          The UserDriverLicense to create
+ * @param array $user_driver_license The UserDriverLicense to create
+ * @param array $user
+ * @return array
  */
 function UserDriverLicenses_create($user_driver_license, $user)
 {
@@ -80,8 +84,8 @@ function UserDriverLicenses_create($user_driver_license, $user)
 /**
  * Update a user's driver license entry
  *
- * @param UserDriverLicense $user_driver_license
- *          The UserDriverLicense to update
+ * @param array $user_driver_license The UserDriverLicense to update
+ * @return mysqli_result
  */
 function UserDriverLicenses_update($user_driver_license)
 {
@@ -103,6 +107,7 @@ function UserDriverLicenses_update($user_driver_license)
  * Delete a user's driver license entry
  *
  * @param int $user_id
+ * @return mysqli_result
  */
 function UserDriverLicenses_delete($user_id)
 {
diff --git a/includes/model/UserGroups_model.php b/includes/model/UserGroups_model.php
index bbef85b6..8716114d 100644
--- a/includes/model/UserGroups_model.php
+++ b/includes/model/UserGroups_model.php
@@ -3,7 +3,8 @@
 /**
  * Returns users groups
  *
- * @param User $user
+ * @param array $user
+ * @return array|false
  */
 function User_groups($user)
 {
diff --git a/includes/model/User_model.php b/includes/model/User_model.php
index 1a09c160..c9987d4e 100644
--- a/includes/model/User_model.php
+++ b/includes/model/User_model.php
@@ -9,6 +9,7 @@ use Engelsystem\ValidationResult;
  * Delete a user
  *
  * @param int $user_id
+ * @return mysqli_result|false
  */
 function User_delete($user_id)
 {
@@ -18,7 +19,8 @@ function User_delete($user_id)
 /**
  * Update user.
  *
- * @param User $user
+ * @param array $user
+ * @return mysqli_result|false
  */
 function User_update($user)
 {
@@ -53,27 +55,41 @@ function User_update($user)
 
 /**
  * Counts all forced active users.
+ *
+ * @return string|null
  */
 function User_force_active_count()
 {
     return sql_select_single_cell("SELECT COUNT(*) FROM `User` WHERE `force_active` = 1");
 }
 
+/**
+ * @return string|null
+ */
 function User_active_count()
 {
     return sql_select_single_cell("SELECT COUNT(*) FROM `User` WHERE `Aktiv` = 1");
 }
 
+/**
+ * @return string|null
+ */
 function User_got_voucher_count()
 {
     return sql_select_single_cell("SELECT SUM(`got_voucher`) FROM `User`");
 }
 
+/**
+ * @return string|null
+ */
 function User_arrived_count()
 {
     return sql_select_single_cell("SELECT COUNT(*) FROM `User` WHERE `Gekommen` = 1");
 }
 
+/**
+ * @return string|null
+ */
 function User_tshirts_count()
 {
     return sql_select_single_cell("SELECT COUNT(*) FROM `User` WHERE `Tshirt` = 1");
@@ -81,6 +97,8 @@ function User_tshirts_count()
 
 /**
  * Returns all column names for sorting in an array.
+ *
+ * @return array
  */
 function User_sortable_columns()
 {
@@ -104,6 +122,7 @@ function User_sortable_columns()
  * Get all users, ordered by Nick by default or by given param.
  *
  * @param string $order_by
+ * @return array|false
  */
 function Users($order_by = 'Nick')
 {
@@ -113,7 +132,8 @@ function Users($order_by = 'Nick')
 /**
  * Returns true if user is freeloader
  *
- * @param User $user
+ * @param array $user
+ * @return bool
  */
 function User_is_freeloader($user)
 {
@@ -125,7 +145,8 @@ function User_is_freeloader($user)
 /**
  * Returns all users that are not member of given angeltype.
  *
- * @param Angeltype $angeltype
+ * @param array $angeltype Angeltype
+ * @return array
  */
 function Users_by_angeltype_inverted($angeltype)
 {
@@ -145,7 +166,8 @@ function Users_by_angeltype_inverted($angeltype)
 /**
  * Returns all members of given angeltype.
  *
- * @param Angeltype $angeltype
+ * @param array $angeltype
+ * @return array
  */
 function Users_by_angeltype($angeltype)
 {
@@ -169,6 +191,8 @@ function Users_by_angeltype($angeltype)
 
 /**
  * Returns User id array
+ *
+ * @return array|false
  */
 function User_ids()
 {
@@ -179,6 +203,7 @@ function User_ids()
  * Strip unwanted characters from a users nick.
  *
  * @param string $nick
+ * @return string
  */
 function User_validate_Nick($nick)
 {
@@ -218,8 +243,7 @@ function User_validate_jabber($jabber)
 /**
  * Validate the planned arrival date
  *
- * @param int $planned_arrival_date
- *          Unix timestamp
+ * @param int $planned_arrival_date Unix timestamp
  * @return ValidationResult
  */
 function User_validate_planned_arrival_date($planned_arrival_date)
@@ -282,7 +306,8 @@ function User_validate_planned_departure_date($planned_arrival_date, $planned_de
 /**
  * Returns user by id.
  *
- * @param $user_id UID
+ * @param int $user_id UID
+ * @return array|null
  */
 function User($user_id)
 {
@@ -301,7 +326,7 @@ function User($user_id)
  *
  * @param string $api_key
  *          User api key
- * @return Matching user, null or false on error
+ * @return array|null Matching user, null on error
  */
 function User_by_api_key($api_key)
 {
@@ -319,7 +344,7 @@ function User_by_api_key($api_key)
  * Returns User by email.
  *
  * @param string $email
- * @return Matching user, null or false on error
+ * @return array|null Matching user, null or false on error
  */
 function User_by_email($email)
 {
@@ -337,7 +362,7 @@ function User_by_email($email)
  * Returns User by password token.
  *
  * @param string $token
- * @return Matching user, null or false on error
+ * @return array|null Matching user, null or false on error
  */
 function User_by_password_recovery_token($token)
 {
@@ -354,7 +379,9 @@ function User_by_password_recovery_token($token)
 /**
  * Generates a new api key for given user.
  *
- * @param User $user
+ * @param array $user
+ * @param bool  $log
+ * @return bool
  */
 function User_reset_api_key(&$user, $log = true)
 {
@@ -363,15 +390,19 @@ function User_reset_api_key(&$user, $log = true)
     if ($result === false) {
         return false;
     }
+
     if ($log) {
         engelsystem_log(sprintf("API key resetted (%s).", User_Nick_render($user)));
     }
+
+    return true;
 }
 
 /**
  * Generates a new password recovery token for given user.
  *
- * @param User $user
+ * @param array $user
+ * @return string
  */
 function User_generate_password_recovery_token(&$user)
 {
@@ -384,6 +415,10 @@ function User_generate_password_recovery_token(&$user)
     return $user['password_recovery_token'];
 }
 
+/**
+ * @param array $user
+ * @return float
+ */
 function User_get_eligable_voucher_count(&$user)
 {
     global $voucher_settings;
diff --git a/includes/model/ValidationResult.php b/includes/model/ValidationResult.php
index b08e9d31..7f88b432 100644
--- a/includes/model/ValidationResult.php
+++ b/includes/model/ValidationResult.php
@@ -8,17 +8,15 @@ namespace Engelsystem;
  */
 class ValidationResult
 {
+    /** @var bool */
     private $valid;
 
+    /** @var mixed */
     private $value;
 
     /**
-     * Constructor.
-     *
-     * @param boolean $valid
-     *          Is the value valid?
-     * @param * $value
-     *          The validated value
+     * @param boolean $valid Is the value valid?
+     * @param mixed   $value The validated value
      */
     public function __construct($valid, $value)
     {
@@ -28,6 +26,8 @@ class ValidationResult
 
     /**
      * Is the value valid?
+     *
+     * @return bool
      */
     public function isValid()
     {
@@ -36,6 +36,8 @@ class ValidationResult
 
     /**
      * The parsed/validated value.
+     *
+     * @return mixed
      */
     public function getValue()
     {
-- 
cgit v1.2.3-54-g00ecf