Merge pull request #883 from dawnbreak/docu

:bulb: Improving Doxygen documentation.

1 files changed, 25 insertions, 8 deletions

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),