Add types doc to *Common* classes (#21981)

closes #21793

Author: trasher

src/CommonDropdown.php

@@ -597,6 +597,8 @@ public function isUsed()
     /**
      * Report if a dropdown have Child
      * Used to (dis)allow delete action
+     *
+     * @return bool
      **/
     public function haveChildren()
     {
@@ -609,6 +611,8 @@ public function haveChildren()
      * And propose a value to replace
      *
      * since 11.0.0 The `$target` parameter has been removed and its value is automatically computed.
+     *
+     * @return bool
      */
     public function showDeleteConfirmForm()
     {
@@ -679,6 +683,8 @@ public function showDeleteConfirmForm()
         echo "</td></tr></table>\n";
         Html::closeForm();
         echo "</div>";
+
+        return true;
     }
 
 
@@ -920,8 +926,10 @@ public static function processMassiveActionsForOneItemtype(
     /**
      * Get links to Faq
      *
-     * @param $withname  boolean  also display name ? (false by default)
-     **/
+     * @param bool $withname also display name ? (false by default)
+     *
+     * @return string
+     */
     public function getLinks($withname = false)
     {
         global $CFG_GLPI;

src/CommonITILActor.php

@@ -109,6 +109,7 @@ public function getActors(int $items_id): array
     /**
      * @param int $items_id
      * @param string $email
+     *
      * @return bool
      */
     public function isAlternateEmailForITILObject($items_id, $email)

src/CommonITILCost.php

@@ -57,6 +57,9 @@ public static function getIcon()
         return Infocom::getIcon();
     }
 
+    /**
+     * @return class-string<CommonDBTM>
+     */
     public function getItilObjectItemType()
     {
         return str_replace('Cost', '', static::class);
@@ -360,6 +363,8 @@ public function initBasedOnPrevious(): void
      * Get total action time used on costs for an item
      *
      * @param integer $items_id ID of the item
+     *
+     * @return int
      **/
     public function getTotalActionTimeForItem($items_id)
     {
@@ -371,13 +376,15 @@ public function getTotalActionTimeForItem($items_id)
             'WHERE'  => [static::$items_id => $items_id],
         ])->current();
 
-        return $result['sumtime'];
+        return (int) $result['sumtime'];
     }
 
     /**
      * Get last datas for an item
      *
      * @param integer $items_id ID of the item
+     *
+     * @return array
      **/
     public function getLastCostForItem($items_id)
     {

src/CommonITILObject_CommonITILObject.php

@@ -591,6 +591,13 @@ public static function countLinksByStatus(string $itemtype, int $items_id, array
         return ((int) $result['cpt']) + $count;
     }
 
+    /**
+     * @param class-string<CommonDBTM> $itemtype
+     * @param int $items_id
+     * @param array $changes
+     *
+     * @return void
+     */
     public static function manageLinksOnChange($itemtype, $items_id, $changes): void
     {
         if ($itemtype === Ticket::class) {

src/CommonITILRecurrent.php

@@ -63,16 +63,22 @@ abstract class CommonITILRecurrent extends CommonDropdown
 
     /**
      * Concrete items to be instanciated
+     *
+     * @return class-string<CommonDBTM>
      */
     abstract public static function getConcreteClass();
 
     /**
      * Template class to use to create the concrete items
+     *
+     * @return class-string<CommonDBTM>
      */
     abstract public static function getTemplateClass();
 
     /**
      * Predefined field class to use to set the concrete items's data
+     *
+     * @return class-string<CommonDBTM>
      */
     abstract public static function getPredefinedFieldsClass();
 
@@ -566,6 +572,8 @@ public function handlePredefinedFields(
 
     /**
      * Get all available types to which an ITIL object can be assigned
+     *
+     * @return class-string<CommonDBTM>[]
      **/
     public static function getAllTypesForHelpdesk()
     {

src/CommonITILSatisfaction.php

@@ -134,7 +134,10 @@ public function canUpdateItem(): bool
      * form for satisfaction
      *
      * @param CommonITILObject $item The item this satisfaction is for
-     **/
+     * @param bool $add_form_header
+     *
+     * @return void
+     */
     public function showSatisactionForm($item, bool $add_form_header = true)
     {
         $options             = [];
@@ -223,6 +226,11 @@ public function post_addItem()
         }
     }
 
+    /**
+     * @param bool $history
+     *
+     * @return void
+     */
     public function post_UpdateItem($history = true)
     {
         global $CFG_GLPI;
@@ -245,7 +253,10 @@ public function post_UpdateItem($history = true)
      * display satisfaction value
      *
      * @param int|float $value Between 0 and 10
-     **/
+     * @param int $entities_id
+     *
+     * @return string
+     */
     public static function displaySatisfaction($value, $entities_id)
     {
         if (!is_numeric($value)) {
@@ -286,7 +297,9 @@ public static function displaySatisfaction($value, $entities_id)
      * Get name of inquest type
      *
      * @param int $value Survey type ID
-     **/
+     *
+     * @return string
+     */
     public static function getTypeInquestName($value)
     {
 
@@ -299,7 +312,7 @@ public static function getTypeInquestName($value)
 
             default:
                 // Get value if not defined
-                return $value;
+                return (string) $value;
         }
     }
 
@@ -348,6 +361,9 @@ public static function getFormURLWithID($id = 0, $full = true)
         return $item::getFormURLWithID($satisfaction->fields[$item::getForeignKeyField()]) . '&forcetab=' . $item::class . '$3';
     }
 
+    /**
+     * @return array
+     */
     public static function rawSearchOptionsToAdd()
     {
         global $DB;

src/CommonITILTask.php

@@ -112,13 +112,18 @@ public static function canUpdate(): bool
         ));
     }
 
-
+    /**
+     * @return bool|int
+     */
     public function canViewPrivates()
     {
         return Session::haveRight(self::$rightname, self::SEEPRIVATE);
     }
 
 
+    /**
+     * @return bool
+     */
     public function canEditAll()
     {
         return Session::haveRightsOr(self::$rightname, [CREATE, DELETE, PURGE, self::UPDATEALL]);
@@ -998,12 +1003,12 @@ public function rawSearchOptions()
     }
 
     /**
-     * @since 0.85
-     **/
+     * @param ?class-string<CommonDBTM> $itemtype
+     *
+     * @return array
+     */
     public static function rawSearchOptionsToAdd($itemtype = null)
     {
-        global $DB;
-
         $task = new static();
         $tab = [];
         $name = _n('Task', 'Tasks', Session::getPluralNumber());
@@ -1271,12 +1276,12 @@ public static function rawSearchOptionsToAdd($itemtype = null)
     }
 
     /**
-     * Current dates are valid ? begin before end
+     * Current dates are valid? begin before end
      *
-     * @param $input
+     * @param array $input
      *
-     *@return boolean
-     **/
+     * @return bool
+     */
     public function test_valid_date($input)
     {
 
@@ -1669,10 +1674,11 @@ public static function genericDisplayPlanningItem($itemtype, array $val, $who, $
 
     /** form for Task
      *
-     * @param $ID        Integer : Id of the task
-     * @param $options   array
-     *     -  parent Object : the object
-     **/
+     * @param int   $ID      Id of the task
+     * @param array $options [parent Object : the object]
+     *
+     * @return true
+     */
     public function showForm($ID, array $options = [])
     {
         TemplateRenderer::getInstance()->display('components/itilobject/timeline/form_task.html.twig', [
@@ -1687,6 +1693,8 @@ public function showForm($ID, array $options = [])
 
     /**
      * Form for Ticket or Problem Task on Massive action
+     *
+     * @return void
      */
     public function showMassiveActionAddTaskForm()
     {
@@ -1714,6 +1722,11 @@ public function showMassiveActionAddTaskForm()
      *
      * @since 9.2
      *
+     * @param string $status
+     * @param bool $showgrouptickets
+     * @param ?int $start
+     * @param ?int $limit
+     *
      * @return DBmysqlIterator
      */
     public static function getTaskList($status, $showgrouptickets, $start = null, $limit = null)