:bulb: Improving Doxygen documentation.

Fix some Doxygen parsing errors.
Improve hooks documentation.

1 files changed, 119 insertions, 60 deletions

diff --git a/Zotlabs/Render/Comanche.php b/Zotlabs/Render/Comanche.php
index 78ca870a7..cd06e11a8 100644
--- a/Zotlabs/Render/Comanche.php
+++ b/Zotlabs/Render/Comanche.php
@@ -5,10 +5,20 @@ namespace Zotlabs\Render;
 require_once('include/security.php');
 require_once('include/menu.php');
 
-
+/**
+ * @brief Comanche Page Description Language.
+ *
+ * Comanche is a markup language similar to bbcode with which to create elaborate
+ * and complex web pages by assembling them from a series of components - some of
+ * which are pre-built and others which can be defined on the fly. Comanche uses
+ * a Page Decription Language to create these pages.
+ *
+ * Comanche primarily chooses what content will appear in various regions of the
+ * page. The various regions have names and these names can change depending on
+ * what layout template you choose.
+ */
 class Comanche {
 
-
 	function parse($s, $pass = 0) {
 		$matches = array();
 
@@ -18,13 +28,13 @@ class Comanche {
 				$s = str_replace($mtch[0], '', $s);
 			}
 		}
-		
+
 		/*
-		 * This section supports the "switch" statement of the form given by the following 
-		 * example. The [default][/default] block must be the last in the arbitrary 
+		 * This section supports the "switch" statement of the form given by the following
+		 * example. The [default][/default] block must be the last in the arbitrary
 		 * list of cases. The first case that matches the switch variable is used
 		 * and the rest are not evaluated.
-		 * 
+		 *
 		 * [switch observer.language]
 		 * [case de]
 		 *   [block]german-content[/block]
@@ -37,7 +47,7 @@ class Comanche {
 		 * [/default]
 		 * [/switch]
 		 */
-		
+
 		$cnt = preg_match_all("/\[switch (.*?)\](.*?)\[default\](.*?)\[\/default\]\s*\[\/switch\]/ism", $s, $matches, PREG_SET_ORDER);
 		if($cnt) {
 			foreach($matches as $mtch) {
@@ -60,7 +70,7 @@ class Comanche {
 				}
 			}
 		}
-		
+
 		$cnt = preg_match_all("/\[if (.*?)\](.*?)\[else\](.*?)\[\/if\]/ism", $s, $matches, PREG_SET_ORDER);
 		if($cnt) {
 			foreach($matches as $mtch) {
@@ -89,7 +99,6 @@ class Comanche {
 			$this->parse_pass0($s);
 		else
 			$this->parse_pass1($s);
-
 	}
 
 	function parse_pass0($s) {
@@ -103,7 +112,7 @@ class Comanche {
 		$cnt = preg_match("/\[template=(.*?)\](.*?)\[\/template\]/ism", $s, $matches);
 		if($cnt) {
 			\App::$page['template'] = trim($matches[2]);
-			\App::$page['template_style'] = trim($matches[2]) . '_' . $matches[1]; 
+			\App::$page['template_style'] = trim($matches[2]) . '_' . $matches[1];
 		}
 
 		$cnt = preg_match("/\[template\](.*?)\[\/template\]/ism", $s, $matches);
@@ -145,20 +154,23 @@ class Comanche {
 	}
 
 	/**
+	 * @brief Replace conditional variables with real values.
+	 *
 	 * Currently supported condition variables:
+	 *   * $config.xxx.yyy - get_config with cat = xxx and k = yyy
+	 *   * $request - request uri for this page
+	 *   * $observer.language - viewer's preferred language (closest match)
+	 *   * $observer.address - xchan_addr or false
+	 *   * $observer.name - xchan_name or false
+	 *   * $observer - xchan_hash of observer or empty string
+	 *   * $local_channel - logged in channel_id or false
 	 *
-	 * $config.xxx.yyy - get_config with cat = xxx and k = yyy
-	 * $request - request uri for this page
-	 * $observer.language - viewer's preferred language (closest match)
-	 * $observer.address - xchan_addr or false
-	 * $observer.name - xchan_name or false
-	 * $observer - xchan_hash of observer or empty string
-	 * $local_channel - logged in channel_id or false
+	 * @param string $v The conditional variable name
+	 * @return string|boolean
 	 */
-
 	function get_condition_var($v) {
 		if($v) {
-			$x = explode('.',$v);
+			$x = explode('.', $v);
 			if($x[0] == 'config')
 				return get_config($x[1],$x[2]);
 			elseif($x[0] === 'request')
@@ -179,6 +191,7 @@ class Comanche {
 						return $y['xchan_name'];
 					elseif($x[1] == 'webname')
 						return substr($y['xchan_addr'],0,strpos($y['xchan_addr'],'@'));
+
 					return false;
 				}
 				return get_observer_hash();
@@ -186,30 +199,39 @@ class Comanche {
 			else
 				return false;
 		}
+
 		return false;
 	}
 
+	/**
+	 * @brief Test for Conditional Execution conditions.
+	 *
+	 * This is extensible. The first version of variable testing supports tests of the forms:
+	 *
+	 * - [if $config.system.foo ~= baz] which will check if get_config('system','foo') contains the string 'baz';
+	 * - [if $config.system.foo == baz] which will check if get_config('system','foo') is the string 'baz';
+	 * - [if $config.system.foo != baz] which will check if get_config('system','foo') is not the string 'baz';
+	 * - [if $config.system.foo >= 3] which will check if get_config('system','foo') is greater than or equal to 3;
+	 * - [if $config.system.foo > 3] which will check if get_config('system','foo') is greater than 3;
+	 * - [if $config.system.foo <= 3] which will check if get_config('system','foo') is less than or equal to 3;
+	 * - [if $config.system.foo < 3] which will check if get_config('system','foo') is less than 3;
+	 *
+	 * - [if $config.system.foo {} baz] which will check if 'baz' is an array element in get_config('system','foo')
+	 * - [if $config.system.foo {*} baz] which will check if 'baz' is an array key in get_config('system','foo')
+	 * - [if $config.system.foo] which will check for a return of a true condition for get_config('system','foo');
+	 *
+	 * The values 0, '', an empty array, and an unset value will all evaluate to false.
+	 *
+	 * @param int|string $s
+	 * @return boolean
+	 */
 	function test_condition($s) {
-		// This is extensible. The first version of variable testing supports tests of the forms:
-
-		// [if $config.system.foo ~= baz] which will check if get_config('system','foo') contains the string 'baz';
-		// [if $config.system.foo == baz] which will check if get_config('system','foo') is the string 'baz';
-		// [if $config.system.foo != baz] which will check if get_config('system','foo') is not the string 'baz';
-		// [if $config.system.foo >= 3] which will check if get_config('system','foo') is greater than or equal to 3;
-		// [if $config.system.foo > 3] which will check if get_config('system','foo') is greater than 3;
-
-		// [if $config.system.foo <= 3] which will check if get_config('system','foo') is less than or equal to 3;
-		// [if $config.system.foo < 3] which will check if get_config('system','foo') is less than 3;
-
-		// [if $config.system.foo {} baz] which will check if 'baz' is an array element in get_config('system','foo')
-		// [if $config.system.foo {*} baz] which will check if 'baz' is an array key in get_config('system','foo')
-		// [if $config.system.foo] which will check for a return of a true condition for get_config('system','foo');
-		// The values 0, '', an empty array, and an unset value will all evaluate to false.
 
 		if(preg_match('/[\$](.*?)\s\~\=\s(.*?)$/',$s,$matches)) {
 			$x = $this->get_condition_var($matches[1]);
 			if(stripos($x,trim($matches[2])) !== false)
 				return true;
+
 			return false;
 		}
 
@@ -217,6 +239,7 @@ class Comanche {
 			$x = $this->get_condition_var($matches[1]);
 			if($x == trim($matches[2]))
 				return true;
+
 			return false;
 		}
 
@@ -224,6 +247,7 @@ class Comanche {
 			$x = $this->get_condition_var($matches[1]);
 			if($x != trim($matches[2]))
 				return true;
+
 			return false;
 		}
 
@@ -231,24 +255,31 @@ class Comanche {
 			$x = $this->get_condition_var($matches[1]);
 			if($x >= trim($matches[2]))
 				return true;
+
 			return false;
 		}
+
 		if(preg_match('/[\$](.*?)\s\<\=\s(.*?)$/',$s,$matches)) {
 			$x = $this->get_condition_var($matches[1]);
 			if($x <= trim($matches[2]))
 				return true;
+
 			return false;
 		}
+
 		if(preg_match('/[\$](.*?)\s\>\s(.*?)$/',$s,$matches)) {
 			$x = $this->get_condition_var($matches[1]);
 			if($x > trim($matches[2]))
 				return true;
+
 			return false;
 		}
+
 		if(preg_match('/[\$](.*?)\s\>\s(.*?)$/',$s,$matches)) {
 			$x = $this->get_condition_var($matches[1]);
 			if($x < trim($matches[2]))
 				return true;
+
 			return false;
 		}
 
@@ -256,6 +287,7 @@ class Comanche {
 			$x = $this->get_condition_var($matches[1]);
 			if(is_array($x) && in_array(trim($matches[2]),$x))
 				return true;
+
 			return false;
 		}
 
@@ -263,6 +295,7 @@ class Comanche {
 			$x = $this->get_condition_var($matches[1]);
 			if(is_array($x) && array_key_exists(trim($matches[2]),$x))
 				return true;
+
 			return false;
 		}
 
@@ -270,13 +303,21 @@ class Comanche {
 			$x = $this->get_condition_var($matches[1]);
 			if($x)
 				return true;
+
 			return false;
 		}
-		return false;
 
+		return false;
 	}
 
-
+	/**
+	 * @brief Return rendered menu for current channel_id.
+	 *
+	 * @see menu_render()
+	 * @param string $s
+	 * @param string $class (optional) default empty
+	 * @return string
+	 */
 	function menu($s, $class = '') {
 
 		$channel_id = $this->get_channel_id();
@@ -291,7 +332,7 @@ class Comanche {
 		}
 
 		if($channel_id) {
-			$m = menu_fetch($name,$channel_id, get_observer_hash());
+			$m = menu_fetch($name, $channel_id, get_observer_hash());
 			return menu_render($m, $class, $edit = false, $var);
 		}
 	}
@@ -309,9 +350,8 @@ class Comanche {
 	 * Returns the channel_id of the profile owner of the page, or the local_channel
 	 * if there is no profile owner. Otherwise returns 0.
 	 *
-	 * @return channel_id
+	 * @return int channel_id
 	 */
-
 	function get_channel_id() {
 		$channel_id = ((is_array(\App::$profile)) ? \App::$profile['profile_uid'] : 0);
 
@@ -321,6 +361,13 @@ class Comanche {
 		return $channel_id;
 	}
 
+	/**
+	 * @brief Returns a parsed block.
+	 *
+	 * @param string $s
+	 * @param string $class (optional) default empty
+	 * @return string parsed HTML of block
+	 */
 	function block($s, $class = '') {
 		$var = array();
 		$matches = array();
@@ -339,7 +386,7 @@ class Comanche {
 		$channel_id = $this->get_channel_id();
 
 		if($channel_id) {
-			$r = q("select * from item inner join iconfig on iconfig.iid = item.id and item.uid = %d 
+			$r = q("select * from item inner join iconfig on iconfig.iid = item.id and item.uid = %d
 				and iconfig.cat = 'system' and iconfig.k = 'BUILDBLOCK' and iconfig.v = '%s' limit 1",
 				intval($channel_id),
 				dbesc($name)
@@ -381,6 +428,12 @@ class Comanche {
 		return $o;
 	}
 
+	/**
+	 * @brief Include JS depending on framework.
+	 *
+	 * @param string $s
+	 * @return string
+	 */
 	function js($s) {
 
 		switch($s) {
@@ -401,9 +454,14 @@ class Comanche {
 			$ret .= $init;
 
 		return $ret;
-
 	}
 
+	/**
+	 * @brief Include CSS depending on framework.
+	 *
+	 * @param string $s
+	 * @return string
+	 */
 	function css($s) {
 
 		switch($s) {
@@ -418,17 +476,22 @@ class Comanche {
 		$ret = '<link rel="stylesheet" href="' . z_root() . '/' . $path . '" type="text/css" media="screen">';
 
 		return $ret;
-
 	}
 
-	// This doesn't really belong in Comanche, but it could also be argued that it is the perfect place.
-	// We need to be able to select what kind of template and decoration to use for the webpage at the heart of our content.
-	// For now we'll allow an '[authored]' element which defaults to name and date, or 'none' to remove these, and perhaps
-	// 'full' to provide a social network style profile photo.
-	// But leave it open to have richer templating options and perhaps ultimately discard this one, once we have a better idea
-	// of what template and webpage options we might desire. 
-
-	function webpage(&$a,$s) {
+	/**
+	 * This doesn't really belong in Comanche, but it could also be argued that it is the perfect place.
+	 * We need to be able to select what kind of template and decoration to use for the webpage at the heart of our content.
+	 * For now we'll allow an '[authored]' element which defaults to name and date, or 'none' to remove these, and perhaps
+	 * 'full' to provide a social network style profile photo.
+	 *
+	 * But leave it open to have richer templating options and perhaps ultimately discard this one, once we have a better idea
+	 * of what template and webpage options we might desire.
+	 *
+	 * @param[in,out] array $a
+	 * @param string $s
+	 * @return array
+	 */
+	function webpage(&$a, $s) {
 		$ret = array();
 		$matches = array();
 
@@ -438,22 +501,20 @@ class Comanche {
 				$ret['authored'] = $mtch[1];
 			}
 		}
+
 		return $ret;
 	}
 
-
 	/**
-	 * Render a widget
+	 * @brief Render a widget.
 	 *
 	 * @param string $name
 	 * @param string $text
 	 */
-
 	function widget($name, $text) {
 		$vars = array();
 		$matches = array();
 
-
 		$cnt = preg_match_all("/\[var=(.*?)\](.*?)\[\/var\]/ism", $text, $matches, PREG_SET_ORDER);
 		if ($cnt) {
 			foreach ($matches as $mtch) {
@@ -480,7 +541,7 @@ class Comanche {
 			if(method_exists($x,$f)) {
 				return $x->$f($vars);
 			}
-		} 
+		}
 
 		$func = 'widget_' . trim($name);
 
@@ -563,9 +624,9 @@ class Comanche {
 	}
 
 
-	/*
-	 * @function register_page_template($arr)
-	 *   Registers a page template/variant for use by Comanche selectors
+	/**
+	 * @brief Registers a page template/variant for use by Comanche selectors.
+	 *
 	 * @param array $arr
 	 *    'template' => template name
 	 *    'variant' => array(
@@ -577,8 +638,6 @@ class Comanche {
 	 *           )
 	 *    )
 	 */
-
-
 	function register_page_template($arr) {
 		\App::$page_layouts[$arr['template']] = array($arr['variant']);
 		return;