[TASK] Update Doxyfile and fix Doxygen errors.

Updated Doxyfile to include new folders.
Add a list for @hooks tags.
Fixed some parsing problems for Doxygen.

1 files changed, 46 insertions, 38 deletions

diff --git a/include/security.php b/include/security.php
index 5ffa48d9e..2f5de54c7 100644
--- a/include/security.php
+++ b/include/security.php
@@ -2,11 +2,12 @@
 /**
  * @file include/security.php
  *
- * Some security related functions.
+ * @brief Some security related functions.
  */
 
 /**
  * @param int $user_record The account_id
+ * @param array $channel
  * @param bool $login_initial default false
  * @param bool $interactive default false
  * @param bool $return
@@ -27,8 +28,8 @@ function authenticate_success($user_record, $channel = null, $login_initial = fa
 			$uid_to_load = $channel['channel_id'];
 
 		if(! $uid_to_load) {
-			$uid_to_load = (((x($_SESSION,'uid')) && (intval($_SESSION['uid']))) 
-				? intval($_SESSION['uid']) 
+			$uid_to_load = (((x($_SESSION,'uid')) && (intval($_SESSION['uid'])))
+				? intval($_SESSION['uid'])
 				: intval(App::$account['account_default_channel'])
 			);
 		}
@@ -89,21 +90,28 @@ function authenticate_success($user_record, $channel = null, $login_initial = fa
 function atoken_login($atoken) {
 	if(! $atoken)
 		return false;
+
 	$_SESSION['authenticated'] = 1;
 	$_SESSION['visitor_id'] = $atoken['xchan_hash'];
 	$_SESSION['atoken'] = $atoken['atoken_id'];
 
 	\App::set_observer($atoken);
+
 	return true;
 }
 
-
+/**
+ * @brief
+ *
+ * @param array $atoken
+ * @return array|null
+ */
 function atoken_xchan($atoken) {
 
 	$c = channelx_by_n($atoken['atoken_uid']);
 	if($c) {
 		return [
-			'atoken_id' => $atoken['atoken_id'], 
+			'atoken_id' => $atoken['atoken_id'],
 			'xchan_hash' =>  substr($c['channel_hash'],0,16) . '.' . $atoken['atoken_name'],
 			'xchan_name' => $atoken['atoken_name'],
 			'xchan_addr' => t('guest:') . $atoken['atoken_name'] . '@' . \App::get_hostname(),
@@ -114,9 +122,9 @@ function atoken_xchan($atoken) {
 			'xchan_photo_l' => get_default_profile_photo(300),
 			'xchan_photo_m' => get_default_profile_photo(80),
 			'xchan_photo_s' => get_default_profile_photo(48)
-	
 		];
 	}
+
 	return null;
 }
 
@@ -133,7 +141,7 @@ function atoken_delete($atoken_id) {
 	);
 	if(! $c)
 		return;
-	
+
 	$atoken_xchan = substr($c[0]['channel_hash'],0,16) . '.' . $r[0]['atoken_name'];
 
 	q("delete from atoken where atoken_id = %d",
@@ -145,12 +153,16 @@ function atoken_delete($atoken_id) {
 	);
 }
 
-
-
-// in order for atoken logins to create content (such as posts) they need a stored xchan.
-// we'll create one on the first atoken_login; it can't really ever go away but perhaps
-// @fixme we should set xchan_deleted if it's expired or removed 
-
+/**
+ * @brief
+ *
+ * In order for atoken logins to create content (such as posts) they need a stored xchan.
+ * we'll create one on the first atoken_login; it can't really ever go away but perhaps
+ * @fixme we should set xchan_deleted if it's expired or removed
+ *
+ * @param array $xchan
+ * @return void|boolean
+ */
 function atoken_create_xchan($xchan) {
 
 	$r = q("select xchan_hash from xchan where xchan_hash = '%s'",
@@ -159,7 +171,7 @@ function atoken_create_xchan($xchan) {
 	if($r)
 		return;
 
-   $r = q("insert into xchan ( xchan_hash, xchan_guid, xchan_addr, xchan_url, xchan_name, xchan_network, xchan_photo_mimetype, xchan_photo_l, xchan_photo_m, xchan_photo_s ) 
+	$r = q("insert into xchan ( xchan_hash, xchan_guid, xchan_addr, xchan_url, xchan_name, xchan_network, xchan_photo_mimetype, xchan_photo_l, xchan_photo_m, xchan_photo_s )
 		values ('%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s') ",
 		dbesc($xchan['xchan_hash']),
 		dbesc($xchan['xchan_hash']),
@@ -202,12 +214,11 @@ function atoken_abook($uid,$xchan_hash) {
 	}
 
 	return false;
-
 }
 
 
 function pseudo_abook($xchan) {
-	if(! $xchan) 
+	if(! $xchan)
 		return false;
 
 	// set abook_pseudo to flag that we aren't really connected.
@@ -216,8 +227,8 @@ function pseudo_abook($xchan) {
 	$xchan['abook_blocked'] = 0;
 	$xchan['abook_ignored'] = 0;
 	$xchan['abook_pending'] = 0;
+
 	return $xchan;
-	
 }
 
 
@@ -228,7 +239,6 @@ function pseudo_abook($xchan) {
  *
  * @return bool|array false or channel record of the new channel
  */
-
 function change_channel($change_channel) {
 
 	$ret = false;
@@ -260,7 +270,7 @@ function change_channel($change_channel) {
 			date_default_timezone_set($r[0]['channel_timezone']);
 			$ret = $r[0];
 		}
-		$x = q("select * from xchan where xchan_hash = '%s' limit 1", 
+		$x = q("select * from xchan where xchan_hash = '%s' limit 1",
 			dbesc($hash)
 		);
 		if($x) {
@@ -275,7 +285,6 @@ function change_channel($change_channel) {
 
 		$arr = [ 'channel_id' => $change_channel, 'chanx' => $ret ];
 		call_hooks('change_channel', $arr);
-
 	}
 
 	return $ret;
@@ -285,11 +294,11 @@ function change_channel($change_channel) {
  * @brief Creates an additional SQL where statement to check permissions.
  *
  * @param int $owner_id
- * @param bool $remote_observer - if unset use current observer
+ * @param bool $remote_observer (optional) use current observer if unset
+ * @param $table (optional)
  *
  * @return string additional SQL where statement
  */
-
 function permissions_sql($owner_id, $remote_observer = null, $table = '') {
 
 	$local_channel = local_channel();
@@ -303,11 +312,10 @@ function permissions_sql($owner_id, $remote_observer = null, $table = '') {
 	if($table)
 		$table .= '.';
 
-
-	$sql = " AND {$table}allow_cid = '' 
-			 AND {$table}allow_gid = '' 
-			 AND {$table}deny_cid  = '' 
-			 AND {$table}deny_gid  = '' 
+	$sql = " AND {$table}allow_cid = ''
+			 AND {$table}allow_gid = ''
+			 AND {$table}deny_cid  = ''
+			 AND {$table}deny_gid  = ''
 	";
 
 	/**
@@ -319,7 +327,7 @@ function permissions_sql($owner_id, $remote_observer = null, $table = '') {
 	}
 
 	/**
-	 * Authenticated visitor. Unless pre-verified, 
+	 * Authenticated visitor. Unless pre-verified,
 	 * check that the contact belongs to this $owner_id
 	 * and load the groups the visitor belongs to.
 	 * If pre-verified, the caller is expected to have already
@@ -358,7 +366,7 @@ function permissions_sql($owner_id, $remote_observer = null, $table = '') {
  * @brief Creates an addiontal SQL where statement to check permissions for an item.
  *
  * @param int $owner_id
- * @param bool $remote_observer, use current observer if unset
+ * @param bool $remote_observer (optional) use current observer if unset
  *
  * @return string additional SQL where statement
  */
@@ -379,7 +387,7 @@ function item_permissions_sql($owner_id, $remote_observer = null) {
 	 */
 
 	if(($local_channel) && ($local_channel == $owner_id)) {
-		$sql = ''; 
+		$sql = '';
 	}
 
 	/**
@@ -425,7 +433,7 @@ function item_permissions_sql($owner_id, $remote_observer = null) {
 /**
  * Remote visitors also need to be checked against the public_scope parameter if item_private is set.
  * This function checks the various permutations of that field for any which apply to this observer.
- * 
+ *
  */
 
 
@@ -448,9 +456,9 @@ function scopes_sql($uid,$observer) {
 	$str .= " or public_policy = 'contacts' ) ";
 	return $str;
 }
- 
-	
-	
+
+
+
 
 
 
@@ -500,7 +508,7 @@ function public_permissions_sql($observer_hash) {
  *    If the new page contains by any chance external elements, then the used security token is exposed by the referrer.
  *    Actually, important actions should not be triggered by Links / GET-Requests at all, but somethimes they still are,
  *    so this mechanism brings in some damage control (the attacker would be able to forge a request to a form of this type, but not to forms of other types).
- */ 
+ */
 function get_form_security_token($typename = '') {
 
 	$timestamp = time();
@@ -561,13 +569,13 @@ function init_groups_visitor($contact_id) {
 
 
 
-// This is used to determine which uid have posts which are visible to the logged in user (from the API) for the 
+// This is used to determine which uid have posts which are visible to the logged in user (from the API) for the
 // public_timeline, and we can use this in a community page by making
-// $perms = (PERMS_NETWORK|PERMS_PUBLIC) unless logged in. 
+// $perms = (PERMS_NETWORK|PERMS_PUBLIC) unless logged in.
 // Collect uids of everybody on this site who has opened their posts to everybody on this site (or greater visibility)
 // We always include yourself if logged in because you can always see your own posts
 // resolving granular permissions for the observer against every person and every post on the site
-// will likely be too expensive. 
+// will likely be too expensive.
 // Returns a string list of comma separated channel_ids suitable for direct inclusion in a SQL query
 
 function stream_perms_api_uids($perms = NULL, $limit = 0, $rand = 0 ) {