From 070aa016e0915c6bba9326a94f7394acd2b21e7f Mon Sep 17 00:00:00 2001
From: Hypolite Petovan <hypolite@mrpetovan.com>
Date: Mon, 7 Jan 2019 10:24:06 -0500
Subject: [PATCH] Update more PHPDoc, including in include/

---
 include/conversation.php          | 41 +++++++++++++++++++++++++------
 include/dba.php                   |  3 ++-
 include/enotify.php               | 17 ++++++++-----
 include/items.php                 |  9 +++++++
 include/text.php                  |  1 +
 mod/item.php                      |  1 +
 mod/network.php                   |  5 ++++
 mod/uexport.php                   |  3 +++
 src/Content/ForumManager.php      |  7 +++---
 src/Content/Text/BBCode.php       |  2 +-
 src/Core/NotificationsManager.php |  2 ++
 src/Model/Contact.php             |  1 +
 src/Model/Event.php               | 26 +++++++++++---------
 src/Model/GContact.php            |  7 ++++++
 src/Model/Queue.php               |  1 +
 src/Model/User.php                |  2 ++
 src/Protocol/PortableContact.php  |  1 +
 17 files changed, 99 insertions(+), 30 deletions(-)

diff --git a/include/conversation.php b/include/conversation.php
index e15ac3f71a..9dd7d53c86 100644
--- a/include/conversation.php
+++ b/include/conversation.php
@@ -117,6 +117,10 @@ function item_redir_and_replace_images($body, $images, $cid) {
 
 /**
  * Render actions localized
+ *
+ * @param $item
+ * @throws ImagickException
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function localize_item(&$item)
 {
@@ -367,6 +371,8 @@ function localize_item(&$item)
 /**
  * Count the total of comments on this item and its desendants
  * @TODO proper type-hint + doc-tag
+ * @param $item
+ * @return int
  */
 function count_descendants($item) {
 	$total = count($item['children']);
@@ -436,7 +442,17 @@ function conv_get_blocklist()
  * The $mode parameter decides between the various renderings and also
  * figures out how to determine page owner and other contextual items
  * that are based on unique features of the calling module.
- *
+ * @param App    $a
+ * @param array  $items
+ * @param Pager  $pager
+ * @param        $mode
+ * @param        $update
+ * @param bool   $preview
+ * @param string $order
+ * @param int    $uid
+ * @return string
+ * @throws ImagickException
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function conversation(App $a, array $items, Pager $pager, $mode, $update, $preview = false, $order = 'commented', $uid = 0)
 {
@@ -783,7 +799,11 @@ function conversation(App $a, array $items, Pager $pager, $mode, $update, $previ
  *
  * @param array $parents Parent items
  *
+ * @param       $block_authors
+ * @param       $order
+ * @param       $uid
  * @return array items with parents and comments
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function conversation_add_children(array $parents, $block_authors, $order, $uid) {
 	$max_comments = Config::get('system', 'max_comments', 100);
@@ -912,9 +932,11 @@ function item_photo_menu($item) {
  * @brief Checks item to see if it is one of the builtin activities (like/dislike, event attendance, consensus items, etc.)
  * Increments the count of each matching activity and adds a link to the author as needed.
  *
- * @param array $item
+ * @param array  $item
  * @param array &$conv_responses (already created with builtin activity structure)
  * @return void
+ * @throws ImagickException
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function builtin_activity_puller($item, &$conv_responses) {
 	foreach ($conv_responses as $mode => $v) {
@@ -985,11 +1007,13 @@ function builtin_activity_puller($item, &$conv_responses) {
 
 /**
  * Format the vote text for a profile item
- * @param int $cnt = number of people who vote the item
- * @param array $arr = array of pre-linked names of likers/dislikers
+ *
+ * @param int    $cnt  = number of people who vote the item
+ * @param array  $arr  = array of pre-linked names of likers/dislikers
  * @param string $type = one of 'like, 'dislike', 'attendyes', 'attendno', 'attendmaybe'
- * @param int $id  = item id
+ * @param int    $id   = item id
  * @return string formatted text
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function format_like($cnt, array $arr, $type, $id) {
 	$o = '';
@@ -1199,8 +1223,8 @@ function status_editor(App $a, $x, $notes_cid = 0, $popup = false)
  *
  * @param array $item_list
  * @param array $parent
- * @param bool $recursive
- * @return type
+ * @param bool  $recursive
+ * @return array
  */
 function get_item_children(array &$item_list, array $parent, $recursive = true)
 {
@@ -1330,6 +1354,7 @@ function smart_flatten_conversation(array $parent)
  * @param array  $item_list A list of items belonging to one or more conversations
  * @param string $order     Either on "created" or "commented"
  * @return array
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function conv_sort(array $item_list, $order)
 {
@@ -1425,7 +1450,7 @@ function sort_thr_created_rev(array $a, array $b)
  *
  * @param array $a
  * @param array $b
- * @return type
+ * @return int|lt
  */
 function sort_thr_commented(array $a, array $b)
 {
diff --git a/include/dba.php b/include/dba.php
index 9e168eac79..2d26a94720 100644
--- a/include/dba.php
+++ b/include/dba.php
@@ -9,8 +9,9 @@ use Friendica\Database\DBA;
  * DBA::select, DBA::exists, DBA::insert
  * DBA::delete, DBA::update, DBA::p, DBA::e
  *
- * @param $args Query parameters (1 to N parameters of different types)
+ * @param $sql
  * @return array|bool Query array
+ * @throws Exception
  * @deprecated
  */
 function q($sql) {
diff --git a/include/enotify.php b/include/enotify.php
index f0b3dd7c0e..be8552ed6e 100644
--- a/include/enotify.php
+++ b/include/enotify.php
@@ -21,10 +21,12 @@ use Friendica\Util\Strings;
  * @brief Creates a notification entry and possibly sends a mail
  *
  * @param array $params Array with the elements:
- *			uid, item, parent, type, otype, verb, event,
- *			link, subject, body, to_name, to_email, source_name,
- *			source_link, activity, preamble, notify_flags,
- *			language, show_in_notification_page
+ *                      uid, item, parent, type, otype, verb, event,
+ *                      link, subject, body, to_name, to_email, source_name,
+ *                      source_link, activity, preamble, notify_flags,
+ *                      language, show_in_notification_page
+ * @return bool|object
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function notification($params)
 {
@@ -687,6 +689,7 @@ function notification($params)
  * @brief Checks for users who should be notified
  *
  * @param int $itemid ID of the item for which the check should be done
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function check_user_notification($itemid) {
 	// fetch all users in the thread
@@ -702,9 +705,11 @@ function check_user_notification($itemid) {
 /**
  * @brief Checks for item related notifications and sends them
  *
- * @param int $itemid ID of the item for which the check should be done
- * @param int $uid User ID
+ * @param int    $itemid      ID of the item for which the check should be done
+ * @param int    $uid         User ID
  * @param string $defaulttype (Optional) Forces a notification with this type.
+ * @return bool
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function check_item_notification($itemid, $uid, $defaulttype = "") {
 	$notification_data = ["uid" => $uid, "profiles" => []];
diff --git a/include/items.php b/include/items.php
index 3dd405e786..2f98122b7b 100644
--- a/include/items.php
+++ b/include/items.php
@@ -242,6 +242,15 @@ function add_page_info_to_body($body, $texturl = false, $no_photos = false)
  * model where comments can have sub-threads. That would require some massive sorting
  * to get all the feed items into a mostly linear ordering, and might still require
  * recursion.
+ *
+ * @param       $xml
+ * @param array $importer
+ * @param array $contact
+ * @param       $hub
+ * @param int   $datedir
+ * @param int   $pass
+ * @throws ImagickException
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function consume_feed($xml, array $importer, array $contact, &$hub, $datedir = 0, $pass = 0)
 {
diff --git a/include/text.php b/include/text.php
index ff9fa5511a..40265eae3b 100644
--- a/include/text.php
+++ b/include/text.php
@@ -160,6 +160,7 @@ function redir_private_images($a, &$item)
  *
  * @param string $text String with bbcode.
  * @return string Formattet HTML.
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function prepare_text($text) {
 	if (stristr($text, '[nosmile]')) {
diff --git a/mod/item.php b/mod/item.php
index 5210f4ae8c..576ad09d6d 100644
--- a/mod/item.php
+++ b/mod/item.php
@@ -912,6 +912,7 @@ function item_content(App $a)
  * This function removes the tag $tag from the text $body and replaces it with
  * the appropriate link.
  *
+ * @param App     $a
  * @param string  $body     the text to replace the tag in
  * @param string  $inform   a comma-seperated string containing everybody to inform
  * @param string  $str_tags string to add the tag to
diff --git a/mod/network.php b/mod/network.php
index 626fb1149b..a71447e5e5 100644
--- a/mod/network.php
+++ b/mod/network.php
@@ -328,6 +328,7 @@ function networkSetSeen($condition)
  * @param integer $update Used for the automatic reloading
  * @param string  $ordering
  * @return string HTML of the conversation
+ * @throws ImagickException
  * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function networkConversation(App $a, $items, Pager $pager, $mode, $update, $ordering = '')
@@ -396,6 +397,7 @@ function network_content(App $a, $update = 0, $parent = 0)
  * @param App     $a      The global App
  * @param integer $update Used for the automatic reloading
  * @return string HTML of the network content in flat view
+ * @throws ImagickException
  * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  * @global Pager  $pager
  */
@@ -489,6 +491,7 @@ function networkFlatView(App $a, $update = 0)
  * @param  integer $update Used for the automatic reloading
  * @param  integer $parent
  * @return string HTML of the network content in flat view
+ * @throws ImagickException
  * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  * @global Pager   $pager
  */
@@ -949,6 +952,7 @@ function networkThreadedView(App $a, $update, $parent)
  *
  * @param App $a The global App
  * @return string Html of the networktab
+ * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  */
 function network_tabs(App $a)
 {
@@ -1048,6 +1052,7 @@ function network_tabs(App $a)
  * of the page to make the correct asynchronous call. This is obtained through the Pager that was instantiated in
  * networkThreadedView or networkFlatView.
  *
+ * @param App     $a
  * @param  string $htmlhead The head tag HTML string
  * @throws \Friendica\Network\HTTPException\InternalServerErrorException
  * @global Pager  $pager
diff --git a/mod/uexport.php b/mod/uexport.php
index 523e2fef85..17715ac35f 100644
--- a/mod/uexport.php
+++ b/mod/uexport.php
@@ -135,6 +135,9 @@ function uexport_account($a) {
 
 /**
  * echoes account data and items as separated json, one per line
+ *
+ * @param App $a
+ * @throws Exception
  */
 function uexport_all(App $a) {
 
diff --git a/src/Content/ForumManager.php b/src/Content/ForumManager.php
index 88c22c5676..11847383fe 100644
--- a/src/Content/ForumManager.php
+++ b/src/Content/ForumManager.php
@@ -188,9 +188,10 @@ class ForumManager
 	 * Count unread items of connected forums and private groups
 	 *
 	 * @return array
-	 *	'id' => contact id
-	 *	'name' => contact/forum name
-	 *	'count' => counted unseen forum items
+	 *    'id' => contact id
+	 *    'name' => contact/forum name
+	 *    'count' => counted unseen forum items
+	 * @throws \Exception
 	 */
 	public static function countUnseenItems()
 	{
diff --git a/src/Content/Text/BBCode.php b/src/Content/Text/BBCode.php
index b77923013b..357dc89d9a 100644
--- a/src/Content/Text/BBCode.php
+++ b/src/Content/Text/BBCode.php
@@ -1150,7 +1150,7 @@ class BBCode extends BaseObject
 	 * @return string
 	 * @throws \Friendica\Network\HTTPException\InternalServerErrorException
 	 */
-	public static function convert($text, $try_oembed = true, $simple_html = false, $for_plaintext = false)
+	public static function convert($text, $try_oembed = true, $simple_html = 0, $for_plaintext = false)
 	{
 		$a = self::getApp();
 
diff --git a/src/Core/NotificationsManager.php b/src/Core/NotificationsManager.php
index 2687719472..756a5ceb4b 100644
--- a/src/Core/NotificationsManager.php
+++ b/src/Core/NotificationsManager.php
@@ -132,6 +132,7 @@ class NotificationsManager extends BaseObject
 	 * @param array $note note array
 	 * @param bool  $seen optional true or false, default true
 	 * @return bool true on success, false on errors
+	 * @throws \Exception
 	 */
 	public function setSeen($note, $seen = true)
 	{
@@ -150,6 +151,7 @@ class NotificationsManager extends BaseObject
 	 *
 	 * @param bool $seen optional true or false. default true
 	 * @return bool true on success, false on error
+	 * @throws \Exception
 	 */
 	public function setAllSeen($seen = true)
 	{
diff --git a/src/Model/Contact.php b/src/Model/Contact.php
index ea4a006ef9..4a8a8cdaba 100644
--- a/src/Model/Contact.php
+++ b/src/Model/Contact.php
@@ -1054,6 +1054,7 @@ class Contact extends BaseObject
 	 *
 	 * @param int $uid uid
 	 * @return array
+	 * @throws \Exception
 	 */
 	public static function getUngroupedList($uid)
 	{
diff --git a/src/Model/Event.php b/src/Model/Event.php
index e7509c48e1..8b7c7e706c 100644
--- a/src/Model/Event.php
+++ b/src/Model/Event.php
@@ -471,6 +471,7 @@ class Event extends BaseObject
 	 * @param int    $event_id  The ID of the event in the event table
 	 * @param string $sql_extra
 	 * @return array Query result
+	 * @throws \Exception
 	 */
 	public static function getListById($owner_uid, $event_id, $sql_extra = '')
 	{
@@ -499,17 +500,18 @@ class Event extends BaseObject
 	/**
 	 * @brief Get all events in a specific time frame.
 	 *
-	 * @param int $owner_uid The User ID of the owner of the events.
-	 * @param array $event_params An associative array with
-	 *	int 'ignore' =>
-	 *	string 'start' => Start time of the timeframe.
-	 *	string 'finish' => Finish time of the timeframe.
-	 *	string 'adjust_start' =>
-	 *	string 'adjust_finish' =>
+	 * @param int    $owner_uid    The User ID of the owner of the events.
+	 * @param array  $event_params An associative array with
+	 *                             int 'ignore' =>
+	 *                             string 'start' => Start time of the timeframe.
+	 *                             string 'finish' => Finish time of the timeframe.
+	 *                             string 'adjust_start' =>
+	 *                             string 'adjust_finish' =>
 	 *
-	 * @param string $sql_extra Additional sql conditions (e.g. permission request).
+	 * @param string $sql_extra    Additional sql conditions (e.g. permission request).
 	 *
 	 * @return array Query results.
+	 * @throws \Exception
 	 */
 	public static function getListByDate($owner_uid, $event_params, $sql_extra = '')
 	{
@@ -633,12 +635,13 @@ class Event extends BaseObject
 	/**
 	 * @brief Format event to export format (ical/csv).
 	 *
-	 * @param array  $events   Query result for events.
-	 * @param string $format   The output format (ical/csv).
+	 * @param array  $events Query result for events.
+	 * @param string $format The output format (ical/csv).
 	 *
+	 * @param        $timezone
 	 * @return string Content according to selected export format.
 	 *
-	 * @todo Implement timezone support
+	 * @todo  Implement timezone support
 	 */
 	private static function formatListForExport(array $events, $format, $timezone)
 	{
@@ -954,6 +957,7 @@ class Event extends BaseObject
 	 *  'name' => The name of the location,<br>
 	 * 'address' => The address of the location,<br>
 	 * 'coordinates' => Latitude‎ and longitude‎ (e.g. '48.864716,2.349014').<br>
+	 * @throws \Friendica\Network\HTTPException\InternalServerErrorException
 	 */
 	private static function locationToArray($s = '') {
 		if ($s == '') {
diff --git a/src/Model/GContact.php b/src/Model/GContact.php
index 57259651c7..c077aa6b4a 100644
--- a/src/Model/GContact.php
+++ b/src/Model/GContact.php
@@ -242,6 +242,7 @@ class GContact
 	 * @param integer $uid id
 	 * @param integer $cid id
 	 * @return integer
+	 * @throws Exception
 	 */
 	public static function countCommonFriends($uid, $cid)
 	{
@@ -269,6 +270,7 @@ class GContact
 	 * @param integer $uid  id
 	 * @param integer $zcid zcid
 	 * @return integer
+	 * @throws Exception
 	 */
 	public static function countCommonFriendsZcid($uid, $zcid)
 	{
@@ -295,6 +297,7 @@ class GContact
 	 * @param integer $limit   optional, default 9999
 	 * @param boolean $shuffle optional, default false
 	 * @return object
+	 * @throws Exception
 	 */
 	public static function commonFriends($uid, $cid, $start = 0, $limit = 9999, $shuffle = false)
 	{
@@ -333,6 +336,7 @@ class GContact
 	 * @param integer $limit   optional, default 9999
 	 * @param boolean $shuffle optional, default false
 	 * @return object
+	 * @throws Exception
 	 */
 	public static function commonFriendsZcid($uid, $zcid, $start = 0, $limit = 9999, $shuffle = false)
 	{
@@ -362,6 +366,7 @@ class GContact
 	 * @param integer $uid user
 	 * @param integer $cid cid
 	 * @return integer
+	 * @throws Exception
 	 */
 	public static function countAllFriends($uid, $cid)
 	{
@@ -387,6 +392,7 @@ class GContact
 	 * @param integer $start optional, default 0
 	 * @param integer $limit optional, default 80
 	 * @return array
+	 * @throws Exception
 	 */
 	public static function allFriends($uid, $cid, $start = 0, $limit = 80)
 	{
@@ -1053,6 +1059,7 @@ class GContact
 
 	/**
 	 * @return string
+	 * @throws Exception
 	 */
 	public static function getRandomUrl()
 	{
diff --git a/src/Model/Queue.php b/src/Model/Queue.php
index ecbc0ed3b6..355433492c 100644
--- a/src/Model/Queue.php
+++ b/src/Model/Queue.php
@@ -52,6 +52,7 @@ class Queue
 	 * @param int $cid Contact id
 	 *
 	 * @return bool The communication with this contact has currently problems
+	 * @throws \Exception
 	 */
 	public static function wasDelayed($cid)
 	{
diff --git a/src/Model/User.php b/src/Model/User.php
index 23ba7e64d8..77cdcd6c26 100644
--- a/src/Model/User.php
+++ b/src/Model/User.php
@@ -729,6 +729,7 @@ class User
 	 * @param string $siteurl
 	 * @param string $password Plaintext password
 	 * @return NULL|boolean from notification() and email() inherited
+	 * @throws \Friendica\Network\HTTPException\InternalServerErrorException
 	 */
 	public static function sendRegisterPendingEmail($user, $sitename, $siteurl, $password)
 	{
@@ -764,6 +765,7 @@ class User
 	 * @param string $siteurl
 	 * @param string $password Plaintext password
 	 * @return NULL|boolean from notification() and email() inherited
+	 * @throws \Friendica\Network\HTTPException\InternalServerErrorException
 	 */
 	public static function sendRegisterOpenEmail($user, $sitename, $siteurl, $password)
 	{
diff --git a/src/Protocol/PortableContact.php b/src/Protocol/PortableContact.php
index fcbd26ecfa..da42a057ed 100644
--- a/src/Protocol/PortableContact.php
+++ b/src/Protocol/PortableContact.php
@@ -1522,6 +1522,7 @@ class PortableContact
 	/**
 	 * @brief Returns a list of all known servers
 	 * @return array List of server urls
+	 * @throws Exception
 	 */
 	public static function serverlist()
 	{