:bulb: Improving Doxygen documentation.

Fix some Doxygen parsing errors.
Improve hooks documentation.

6 files changed, 193 insertions, 86 deletions

diff --git a/Zotlabs/Lib/ActivityStreams.php b/Zotlabs/Lib/ActivityStreams.php
index 379e78a59..2e9bb0703 100644
--- a/Zotlabs/Lib/ActivityStreams.php
+++ b/Zotlabs/Lib/ActivityStreams.php
@@ -2,6 +2,11 @@
 
 namespace Zotlabs\Lib;
 
+/**
+ * @brief ActivityStreams class.
+ *
+ * Parses an ActivityStream JSON string.
+ */
 class ActivityStreams {
 
 	public $data;
@@ -19,9 +24,16 @@ class ActivityStreams {
 	public $recips = null;
 	public $raw_recips = null;
 
+	/**
+	 * @brief Constructor for ActivityStreams.
+	 *
+	 * Takes a JSON string as parameter, decodes it and sets up this object.
+	 *
+	 * @param string $string
+	 */
 	function __construct($string) {
 
-		$this->data = json_decode($string,true);
+		$this->data = json_decode($string, true);
 		if($this->data) {
 			$this->valid = true;
 		}
@@ -50,6 +62,11 @@ class ActivityStreams {
 		}
 	}
 
+	/**
+	 * @brief Return if instantiated ActivityStream is valid.
+	 *
+	 * @return boolean Return true if the JSON string could be decoded.
+	 */
 	function is_valid() {
 		return $this->valid;
 	}
@@ -58,18 +75,26 @@ class ActivityStreams {
 		$this->saved_recips = $arr;
 	}
 
-	function collect_recips($base = '',$namespace = '') {
+	/**
+	 * @brief Collects all recipients.
+	 *
+	 * @param string $base
+	 * @param string $namespace (optional) default empty
+	 * @return array
+	 */
+	function collect_recips($base = '', $namespace = '') {
 		$x = [];
-		$fields = [ 'to','cc','bto','bcc','audience'];
+		$fields = [ 'to', 'cc', 'bto', 'bcc', 'audience'];
 		foreach($fields as $f) {
-			$y = $this->get_compound_property($f,$base,$namespace);
+			$y = $this->get_compound_property($f, $base, $namespace);
 			if($y) {
-				$x = array_merge($x,$y);
+				$x = array_merge($x, $y);
 				if(! is_array($this->raw_recips))
 					$this->raw_recips = [];
+
 				$this->raw_recips[$f] = $x;
 			}
-		}						
+		}
 // not yet ready for prime time
 //		$x = $this->expand($x,$base,$namespace);
 		return $x;
@@ -96,23 +121,30 @@ class ActivityStreams {
 			}
 		}
 
-		// @fixme de-duplicate
+		/// @fixme de-duplicate
 
 		return $ret;
 	}
 
-	function get_namespace($base,$namespace) {
+	/**
+	 * @brief
+	 *
+	 * @param array $base
+	 * @param string $namespace if not set return empty string
+	 * @return string|NULL
+	 */
+	function get_namespace($base, $namespace) {
 
 		if(! $namespace)
 			return '';
 
 		$key = null;
 
-
 		foreach( [ $this->data, $base ] as $b ) {
 			if(! $b)
 				continue;
-			if(array_key_exists('@context',$b)) {
+
+			if(array_key_exists('@context', $b)) {
 				if(is_array($b['@context'])) {
 					foreach($b['@context'] as $ns) {
 						if(is_array($ns)) {
@@ -135,19 +167,35 @@ class ActivityStreams {
 				}
 			}
 		}
+
 		return $key;
 	}
 
-
-	function get_property_obj($property,$base = '',$namespace = '' ) {
-		$prefix = $this->get_namespace($base,$namespace);
+	/**
+	 * @brief
+	 *
+	 * @param string $property
+	 * @param array $base (optional)
+	 * @param string $namespace (optional) default empty
+	 * @return NULL|mixed
+	 */
+	function get_property_obj($property, $base = '', $namespace = '') {
+		$prefix = $this->get_namespace($base, $namespace);
 		if($prefix === null)
-			return null;	
+			return null;
+
 		$base = (($base) ? $base : $this->data);
 		$propname = (($prefix) ? $prefix . ':' : '') . $property;
-		return ((array_key_exists($propname,$base)) ? $base[$propname] : null);
+
+		return ((array_key_exists($propname, $base)) ? $base[$propname] : null);
 	}
 
+	/**
+	 * @brief Fetches a property from an URL.
+	 *
+	 * @param string $url
+	 * @return NULL|mixed
+	 */
 	function fetch_property($url) {
 		$redirects = 0;
 		if(! check_siteallowed($url)) {
@@ -155,44 +203,70 @@ class ActivityStreams {
 			return null;
 		}
 
-		$x = z_fetch_url($url,true,$redirects,
+		$x = z_fetch_url($url, true, $redirects,
 			['headers' => [ 'Accept: application/ld+json; profile="https://www.w3.org/ns/activitystreams", application/activity+json' ]]);
 		if($x['success'])
-			return json_decode($x['body'],true);
+			return json_decode($x['body'], true);
+
 		return null;
 	}
 
-	function get_compound_property($property,$base = '',$namespace = '') {
-		$x = $this->get_property_obj($property,$base,$namespace);
+	/**
+	 * @brief
+	 *
+	 * @param string $property
+	 * @param array $base
+	 * @param string $namespace (optional) default empty
+	 * @return NULL|mixed
+	 */
+	function get_compound_property($property, $base = '', $namespace = '') {
+		$x = $this->get_property_obj($property, $base, $namespace);
 		if($this->is_url($x)) {
-			$x = $this->fetch_property($x); 	
+			$x = $this->fetch_property($x);
 		}
+
 		return $x;
 	}
 
+	/**
+	 * @brief Check if string starts with http.
+	 *
+	 * @param string $url
+	 * @return boolean
+	 */
 	function is_url($url) {
-		if(($url) && (! is_array($url)) && (strpos($url,'http') === 0)) {
+		if(($url) && (! is_array($url)) && (strpos($url, 'http') === 0)) {
 			return true;
 		}
+
 		return false;
 	}
 
-	function get_primary_type($base = '',$namespace = '') {
+	/**
+	 * @brief Gets the type property.
+	 *
+	 * @param array $base
+	 * @param string $namespace (optional) default empty
+	 * @return NULL|mixed
+	 */
+	function get_primary_type($base = '', $namespace = '') {
 		if(! $base)
 			$base = $this->data;
-		$x = $this->get_property_obj('type',$base,$namespace);
+
+		$x = $this->get_property_obj('type', $base, $namespace);
 		if(is_array($x)) {
 			foreach($x as $y) {
-				if(strpos($y,':') === false) {
+				if(strpos($y, ':') === false) {
 					return $y;
 				}
 			}
 		}
+
 		return $x;
 	}
 
 	function debug() {
-		$x = var_export($this,true);
+		$x = var_export($this, true);
 		return $x;
 	}
 
diff --git a/Zotlabs/Lib/Chatroom.php b/Zotlabs/Lib/Chatroom.php
index e1a9a10b3..e762620ae 100644
--- a/Zotlabs/Lib/Chatroom.php
+++ b/Zotlabs/Lib/Chatroom.php
@@ -2,22 +2,18 @@
 namespace Zotlabs\Lib;
 
 /**
- * @brief Chat related functions.
+ * @brief A class with chatroom related static methods.
  */
-
-
-
 class Chatroom {
 	/**
 	 * @brief Creates a chatroom.
 	 *
 	 * @param array $channel
 	 * @param array $arr
-	 * @return An associative array containing:
-	 *  - success: A boolean
-	 *  - message: (optional) A string
+	 * @return array An associative array containing:
+	 *   * \e boolean \b success - A boolean success status
+	 *   * \e string \b message - (optional) A string
 	 */
-
 	static public function create($channel, $arr) {
 
 		$ret = array('success' => false);
@@ -150,8 +146,8 @@ class Chatroom {
 		}
 
 		if(intval($x[0]['cr_expire'])) {
-			$r = q("delete from chat where created < %s - INTERVAL %s and chat_room = %d", 
-				db_utcnow(), 
+			$r = q("delete from chat where created < %s - INTERVAL %s and chat_room = %d",
+				db_utcnow(),
 				db_quoteinterval( intval($x[0]['cr_expire']) . ' MINUTE' ),
 				intval($x[0]['cr_id'])
 			);
@@ -225,10 +221,16 @@ class Chatroom {
 	}
 
 	/**
-	 * create a chat message via API.
+	 * @brief Create a chat message via API.
+	 *
 	 * It is the caller's responsibility to enter the room.
- 	*/
-
+	 *
+	 * @param int $uid
+	 * @param int $room_id
+	 * @param string $xchan
+	 * @param string $text
+	 * @return array
+	 */
 	static public function message($uid, $room_id, $xchan, $text) {
 
 		$ret = array('success' => false);
@@ -245,12 +247,18 @@ class Chatroom {
 		if(! $r)
 			return $ret;
 
-		$arr = array(
+		$arr = [
 			'chat_room' => $room_id,
 			'chat_xchan' => $xchan,
 			'chat_text' => $text
-		);
-
+		];
+		/**
+		 * @hooks chat_message
+		 *   Called to create a chat message.
+		 *   * \e int \b chat_room
+		 *   * \e string \b chat_xchan
+		 *   * \e string \b chat_text
+		 */
 		call_hooks('chat_message', $arr);
 
 		$x = q("insert into chat ( chat_room, chat_xchan, created, chat_text )
diff --git a/Zotlabs/Lib/Config.php b/Zotlabs/Lib/Config.php
index 6e042feba..f9f22ba3a 100644
--- a/Zotlabs/Lib/Config.php
+++ b/Zotlabs/Lib/Config.php
@@ -1,4 +1,4 @@
-<?php /** @file */
+<?php
 
 namespace Zotlabs\Lib;
 
@@ -14,7 +14,6 @@ class Config {
 	 * @param string $family
 	 *  The category of the configuration value
 	 */
-
 	static public function Load($family) {
 		if(! array_key_exists($family, \App::$config))
 			\App::$config[$family] = array();
@@ -30,7 +29,7 @@ class Config {
 				}
 				\App::$config[$family]['config_loaded'] = true;
 			}
-		} 
+		}
 	}
 
 	/**
@@ -47,8 +46,7 @@ class Config {
 	 * @return mixed
 	 *  Return the set value, or false if the database update failed
 	 */
-
-	static public function Set($family,$key,$value) {
+	static public function Set($family, $key, $value) {
 		// manage array value
 		$dbvalue = ((is_array($value))  ? serialize($value) : $value);
 		$dbvalue = ((is_bool($dbvalue)) ? intval($dbvalue)  : $dbvalue);
@@ -76,8 +74,8 @@ class Config {
 			\App::$config[$family][$key] = $value;
 			$ret = $value;
 		}
-		return $ret;
 
+		return $ret;
 	}
 
 	/**
@@ -88,25 +86,25 @@ class Config {
 	 * $key from a cached storage in App::$config[$family]. If a key is found in the
 	 * DB but does not exist in local config cache, pull it into the cache so we
 	 * do not have to hit the DB again for this item.
-	 * 
+	 *
 	 * Returns false if not set.
 	 *
 	 * @param string $family
 	 *  The category of the configuration value
 	 * @param string $key
 	 *  The configuration key to query
+	 * @param string $default (optional) default false
 	 * @return mixed Return value or false on error or if not set
 	 */
-
-	static public function Get($family,$key,$default = false) {
+	static public function Get($family, $key, $default = false) {
 		if((! array_key_exists($family, \App::$config)) || (! array_key_exists('config_loaded', \App::$config[$family])))
 			self::Load($family);
 
 		if(array_key_exists('config_loaded', \App::$config[$family])) {
 			if(! array_key_exists($key, \App::$config[$family])) {
-				return $default;		
+				return $default;
 			}
-			return ((! is_array(\App::$config[$family][$key])) && (preg_match('|^a:[0-9]+:{.*}$|s', \App::$config[$family][$key])) 
+			return ((! is_array(\App::$config[$family][$key])) && (preg_match('|^a:[0-9]+:{.*}$|s', \App::$config[$family][$key]))
 				? unserialize(\App::$config[$family][$key])
 				: \App::$config[$family][$key]
 			);
@@ -127,17 +125,18 @@ class Config {
 	 *  The configuration key to delete
 	 * @return mixed
 	 */
-
-	static public function Delete($family,$key) {
+	static public function Delete($family, $key) {
 
 		$ret = false;
 
 		if(array_key_exists($family, \App::$config) && array_key_exists($key, \App::$config[$family]))
 			unset(\App::$config[$family][$key]);
-			$ret = q("DELETE FROM config WHERE cat = '%s' AND k = '%s'",
+
+		$ret = q("DELETE FROM config WHERE cat = '%s' AND k = '%s'",
 			dbesc($family),
 			dbesc($key)
 		);
+
 		return $ret;
 	}
 
@@ -154,12 +153,12 @@ class Config {
 	 *  The configuration key to query
 	 * @return mixed
 	 */
-
 	static private function get_from_storage($family,$key) {
 		$ret = q("SELECT * FROM config WHERE cat = '%s' AND k = '%s' LIMIT 1",
 			dbesc($family),
 			dbesc($key)
 		);
+
 		return $ret;
 	}
 
diff --git a/Zotlabs/Lib/PConfig.php b/Zotlabs/Lib/PConfig.php
index 2a0b18aac..ec0792ce1 100644
--- a/Zotlabs/Lib/PConfig.php
+++ b/Zotlabs/Lib/PConfig.php
@@ -1,8 +1,21 @@
-<?php /** @file */
+<?php
 
 namespace Zotlabs\Lib;
 
-
+/**
+ * @brief Class for handling channel specific configurations.
+ *
+ * <b>PConfig</b> is used for channel specific configurations and takes a
+ * <i>channel_id</i> as identifier. It stores for example which features are
+ * enabled per channel. The storage is of size MEDIUMTEXT.
+ *
+ * @code{.php}$var = Zotlabs\Lib\PConfig::Get('uid', 'category', 'key');
+ * // with default value for non existent key
+ * $var = Zotlabs\Lib\PConfig::Get('uid', 'category', 'unsetkey', 'defaultvalue');@endcode
+ *
+ * The old (deprecated?) way to access a PConfig value is:
+ * @code{.php}$var = get_pconfig(local_channel(), 'category', 'key');@endcode
+ */
 class PConfig {
 
 	/**
@@ -13,9 +26,8 @@ class PConfig {
 	 *
 	 * @param string $uid
 	 *  The channel_id
-	 * @return void|false Nothing or false if $uid is false
+	 * @return void|false Nothing or false if $uid is null or false
 	 */
-
 	static public function Load($uid) {
 		if(is_null($uid) || $uid === false)
 			return false;
@@ -64,11 +76,11 @@ class PConfig {
 	 *  The category of the configuration value
 	 * @param string $key
 	 *  The configuration key to query
-	 * @param boolean $instore (deprecated, without function)
+	 * @param mixed $default (optional, default false)
+	 *  Default value to return if key does not exist
 	 * @return mixed Stored value or false if it does not exist
 	 */
-
-	static public function Get($uid,$family,$key,$default = false) {
+	static public function Get($uid, $family, $key, $default = false) {
 
 		if(is_null($uid) || $uid === false)
 			return $default;
@@ -79,11 +91,10 @@ class PConfig {
 		if((! array_key_exists($family, \App::$config[$uid])) || (! array_key_exists($key, \App::$config[$uid][$family])))
 			return $default;
 
-		return ((! is_array(\App::$config[$uid][$family][$key])) && (preg_match('|^a:[0-9]+:{.*}$|s', \App::$config[$uid][$family][$key])) 
+		return ((! is_array(\App::$config[$uid][$family][$key])) && (preg_match('|^a:[0-9]+:{.*}$|s', \App::$config[$uid][$family][$key]))
 			? unserialize(\App::$config[$uid][$family][$key])
 			: \App::$config[$uid][$family][$key]
 		);
-
 	}
 
 	/**
@@ -102,12 +113,11 @@ class PConfig {
 	 *  The value to store
 	 * @return mixed Stored $value or false
 	 */
-
 	static public function Set($uid, $family, $key, $value) {
 
-		// this catches subtle errors where this function has been called 
+		// this catches subtle errors where this function has been called
 		// with local_channel() when not logged in (which returns false)
-		// and throws an error in array_key_exists below. 
+		// and throws an error in array_key_exists below.
 		// we provide a function backtrace in the logs so that we can find
 		// and fix the calling function.
 
@@ -132,7 +142,6 @@ class PConfig {
 				dbesc($key),
 				dbesc($dbvalue)
 			);
-
 		}
 		else {
 
@@ -142,7 +151,6 @@ class PConfig {
 				dbesc($family),
 				dbesc($key)
 			);
-
 		}
 
 		// keep a separate copy for all variables which were
@@ -178,7 +186,6 @@ class PConfig {
 	 *  The configuration key to delete
 	 * @return mixed
 	 */
- 
 	static public function Delete($uid, $family, $key) {
 
 		if(is_null($uid) || $uid === false)
@@ -186,12 +193,12 @@ class PConfig {
 
 		$ret = false;
 
-		if(array_key_exists($uid,\App::$config) 
-			&& is_array(\App::$config['uid']) 
-			&& array_key_exists($family,\App::$config['uid']) 
+		if(array_key_exists($uid,\App::$config)
+			&& is_array(\App::$config['uid'])
+			&& array_key_exists($family,\App::$config['uid'])
 			&& array_key_exists($key, \App::$config[$uid][$family]))
 			unset(\App::$config[$uid][$family][$key]);
-			
+
 		$ret = q("DELETE FROM pconfig WHERE uid = %d AND cat = '%s' AND k = '%s'",
 			intval($uid),
 			dbesc($family),
@@ -202,4 +209,3 @@ class PConfig {
 	}
 
 }
-		
\ No newline at end of file
diff --git a/Zotlabs/Lib/SConfig.php b/Zotlabs/Lib/SConfig.php
index ca0d133b2..ab6f49025 100644
--- a/Zotlabs/Lib/SConfig.php
+++ b/Zotlabs/Lib/SConfig.php
@@ -2,8 +2,11 @@
 
 namespace Zotlabs\Lib;
 
-// account configuration storage is built on top of the under-utilised xconfig
-
+/**
+ * @brief Account configuration storage is built on top of the under-utilised xconfig.
+ *
+ * @see XConfig
+ */
 class SConfig {
 
 	static public function Load($server_id) {
diff --git a/Zotlabs/Lib/XConfig.php b/Zotlabs/Lib/XConfig.php
index bf78c360f..c5a108ac9 100644
--- a/Zotlabs/Lib/XConfig.php
+++ b/Zotlabs/Lib/XConfig.php
@@ -2,7 +2,26 @@
 
 namespace Zotlabs\Lib;
 
-
+/**
+ * @brief Class for handling observer's config.
+ *
+ * <b>XConfig</b> is comparable to <i>PConfig</i>, except that it uses <i>xchan</i>
+ * (an observer hash) as an identifier.
+ *
+ * <b>XConfig</b> is used for observer specific configurations and takes a
+ * <i>xchan</i> as identifier.
+ * The storage is of size MEDIUMTEXT.
+ *
+ * @code{.php}$var = Zotlabs\Lib\XConfig::Get('xchan', 'category', 'key');
+ * // with default value for non existent key
+ * $var = Zotlabs\Lib\XConfig::Get('xchan', 'category', 'unsetkey', 'defaultvalue');@endcode
+ *
+ * The old (deprecated?) way to access a XConfig value is:
+ * @code{.php}$observer = App::get_observer_hash();
+ * if ($observer) {
+ *     $var = get_xconfig($observer, 'category', 'key');
+ * }@endcode
+ */
 class XConfig {
 
 	/**
@@ -15,7 +34,6 @@ class XConfig {
 	 *  The observer's hash
 	 * @return void|false Returns false if xchan is not set
 	 */
-
 	static public function Load($xchan) {
 
 		if(! $xchan)
@@ -56,9 +74,9 @@ class XConfig {
 	 *  The category of the configuration value
 	 * @param string $key
 	 *  The configuration key to query
+	 * @param boolean $default (optional) default false
 	 * @return mixed Stored $value or false if it does not exist
 	 */
-
 	static public function Get($xchan, $family, $key, $default = false) {
 
 		if(! $xchan)
@@ -70,7 +88,7 @@ class XConfig {
 		if((! array_key_exists($family, \App::$config[$xchan])) || (! array_key_exists($key, \App::$config[$xchan][$family])))
 			return $default;
 
-		return ((! is_array(\App::$config[$xchan][$family][$key])) && (preg_match('|^a:[0-9]+:{.*}$|s', \App::$config[$xchan][$family][$key])) 
+		return ((! is_array(\App::$config[$xchan][$family][$key])) && (preg_match('|^a:[0-9]+:{.*}$|s', \App::$config[$xchan][$family][$key]))
 			? unserialize(\App::$config[$xchan][$family][$key])
 			: \App::$config[$xchan][$family][$key]
 		);
@@ -82,7 +100,6 @@ class XConfig {
 	 * Stores a config value ($value) in the category ($family) under the key ($key)
 	 * for the observer's $xchan hash.
 	 *
-	 *
 	 * @param string $xchan
 	 *  The observer's hash
 	 * @param string $family
@@ -93,7 +110,6 @@ class XConfig {
 	 *  The value to store
 	 * @return mixed Stored $value or false
 	 */
-
 	static public function Set($xchan, $family, $key, $value) {
 
 		// manage array value
@@ -106,7 +122,7 @@ class XConfig {
 			if(! array_key_exists($family, \App::$config[$xchan]))
 				\App::$config[$xchan][$family] = array();
 
-			$ret = q("INSERT INTO xconfig ( xchan, cat, k, v ) VALUES ( '%s', '%s', '%s', '%s' ) ",
+			$ret = q("INSERT INTO xconfig ( xchan, cat, k, v ) VALUES ( '%s', '%s', '%s', '%s' )",
 				dbesc($xchan),
 				dbesc($family),
 				dbesc($key),
@@ -126,6 +142,7 @@ class XConfig {
 
 		if($ret)
 			return $value;
+
 		return $ret;
 	}
 
@@ -143,11 +160,11 @@ class XConfig {
 	 *  The configuration key to delete
 	 * @return mixed
 	 */
-
 	static public function Delete($xchan, $family, $key) {
 
 		if(x(\App::$config[$xchan][$family], $key))
 			unset(\App::$config[$xchan][$family][$key]);
+
 		$ret = q("DELETE FROM xconfig WHERE xchan = '%s' AND cat = '%s' AND k = '%s'",
 			dbesc($xchan),
 			dbesc($family),