Some Doxygen comments and small cleanups.

1 files changed, 138 insertions, 50 deletions

diff --git a/boot.php b/boot.php
index 3fdaa55f0..8a212a11d 100755
--- a/boot.php
+++ b/boot.php
@@ -27,7 +27,6 @@
  * documented.
  */
 
-
 require_once('include/config.php');
 require_once('include/network.php');
 require_once('include/plugin.php');
@@ -570,7 +569,7 @@ define ( 'ITEM_RSS',             0x8000);  // Item comes from a feed. Use this t
 
 define ( 'DBTYPE_MYSQL',    0 );
 define ( 'DBTYPE_POSTGRES', 1 );
-										   
+
 /**
  *
  * Reverse the effect of magic_quotes_gpc if it is enabled.
@@ -614,10 +613,10 @@ function startup() {
 }
 
 /**
- *
  * class: App
  *
- * Our main application structure for the life of this page
+ * @brief Our main application structure for the life of this page.
+ *
  * Primarily deals with the URL that got us here
  * and tries to make some sense of it, and
  * stores our page contents and config storage
@@ -683,11 +682,15 @@ class App {
 	public  $force_max_items = 0;
 	public  $theme_thread_allow = true;
 
-	// An array for all theme-controllable parameters
-	// Mostly unimplemented yet. Only options 'template_engine' and
-	// beyond are used.
-
-	private	$theme = array(
+	/**
+	 * @brief An array for all theme-controllable parameters
+	 *
+	 * Mostly unimplemented yet. Only options 'template_engine' and
+	 * beyond are used.
+	 *
+	 * @var array
+	 */
+	private $theme = array(
 		'sourcename' => '',
 		'videowidth' => 425,
 		'videoheight' => 350,
@@ -697,9 +700,17 @@ class App {
 		'template_engine' => 'smarty3',
 	);
 
-	// array of registered template engines ('name'=>'class name')
+	/**
+	 * array of registered template engines ('name'=>'class name')
+	 *
+	 * @var array
+	 */
 	public $template_engines = array();
-	// array of instanced template engines ('name'=>'instance')
+	/**
+	 * array of instanced template engines ('name'=>'instance')
+	 *
+	 * @var array
+	 */
 	public $template_engine_instance = array();
 
 	private $ldelim = array(
@@ -716,7 +727,9 @@ class App {
 	private $baseurl;
 	private $path;
 
-
+	/**
+	 * App constructor.
+	 */
 	function __construct() {
 		// we'll reset this after we read our config file
 		date_default_timezone_set('UTC');
@@ -759,8 +772,8 @@ class App {
 
 		set_include_path("include/$this->hostname" . PATH_SEPARATOR . get_include_path());
 
-		if((x($_SERVER,'QUERY_STRING')) && substr($_SERVER['QUERY_STRING'],0,2) === "q=") {
-			$this->query_string = substr($_SERVER['QUERY_STRING'],2);
+		if((x($_SERVER,'QUERY_STRING')) && substr($_SERVER['QUERY_STRING'], 0, 2) === "q=") {
+			$this->query_string = substr($_SERVER['QUERY_STRING'], 2);
 			// removing trailing / - maybe a nginx problem
 			if (substr($this->query_string, 0, 1) == "/")
 				$this->query_string = substr($this->query_string, 1);
@@ -770,8 +783,8 @@ class App {
 
 		// unix style "homedir"
 
-		if(substr($this->cmd,0,1) === '~')
-			$this->cmd = 'channel/' . substr($this->cmd,1);
+		if(substr($this->cmd, 0, 1) === '~')
+			$this->cmd = 'channel/' . substr($this->cmd, 1);
 
 
 		/**
@@ -855,7 +868,6 @@ class App {
 	}
 
 	function set_baseurl($url) {
-
 		if(is_array($this->config)
 			&& array_key_exists('system',$this->config)
 			&& is_array($this->config['system'])
@@ -888,7 +900,7 @@ class App {
 	}
 
 	function set_path($p) {
-		$this->path = trim(trim($p),'/');
+		$this->path = trim(trim($p), '/');
 	}
 
 	function get_path() {
@@ -1030,6 +1042,7 @@ class App {
 	* return engine defined by theme, or default
 	*
 	* @param string $name Template engine name
+	*
 	* @return object Template Engine instance
 	*/
 	function template_engine($name = ''){
@@ -1056,6 +1069,11 @@ class App {
 		echo "template engine <tt>$template_engine</tt> is not registered!\n"; killme();
 	}
 
+	/**
+	 * @brief Returns the active template engine.
+	 *
+	 * @return string
+	 */
 	function get_template_engine() {
 		return $this->theme['template_engine'];
 	}
@@ -1097,9 +1115,13 @@ class App {
 } // End App class
 
 
-// retrieve the App structure
-// useful in functions which require it but don't get it passed to them
-
+/**
+ * @brief Retrieve the App structure.
+ *
+ * Useful in functions which require it but don't get it passed to them
+ *
+ * @return App
+ */
 function get_app() {
 	global $a;
 	return $a;
@@ -1117,7 +1139,8 @@ function get_app() {
  *
  * @param string|array $s variable to check
  * @param string $k key inside the array to check
- * @return bool
+ *
+ * @return bool|int
  */
 function x($s, $k = null) {
 	if($k != null) {
@@ -1167,24 +1190,43 @@ function z_path() {
 	return $base;
 }
 
+/**
+ * @brief Returns the baseurl.
+ *
+ * @see App::get_baseurl()
+ *
+ * @return string
+ */
 function z_root() {
 	global $a;
 	return $a->get_baseurl();
 }
 
+/**
+ * @brief Return absolut URL for given $path.
+ *
+ * @param string $path
+ *
+ * @return string
+ */
 function absurl($path) {
-	if(strpos($path,'/') === 0)
+	if(strpos($path, '/') === 0)
 		return z_path() . $path;
 
 	return $path;
 }
 
-function os_mkdir($path,$mode = 0777,$recursive = false) {
+function os_mkdir($path, $mode = 0777, $recursive = false) {
 	$oldumask = @umask(0);
 	@mkdir($path, $mode, $recursive);
 	@umask($oldumask); 
 }
 
+/**
+ * @brief Function to check if request was an AJAX (xmlhttprequest) request.
+ *
+ * @return boolean
+ */
 function is_ajax() {
 	return (!empty($_SERVER['HTTP_X_REQUESTED_WITH']) && strtolower($_SERVER['HTTP_X_REQUESTED_WITH']) == 'xmlhttprequest');
 }
@@ -1332,11 +1374,11 @@ function check_config(&$a) {
 	else
 		$installed = array();
 
-	$plugins = get_config('system','addon');
+	$plugins = get_config('system', 'addon');
 	$plugins_arr = array();
 
 	if($plugins)
-		$plugins_arr = explode(',',str_replace(' ', '',$plugins));
+		$plugins_arr = explode(',', str_replace(' ', '', $plugins));
 
 	$a->plugins = $plugins_arr;
 
@@ -1344,7 +1386,7 @@ function check_config(&$a) {
 
 	if(count($installed)) {
 		foreach($installed as $i) {
-			if(! in_array($i['name'],$plugins_arr)) {
+			if(! in_array($i['name'], $plugins_arr)) {
 				unload_plugin($i['name']);
 			}
 			else {
@@ -1355,7 +1397,7 @@ function check_config(&$a) {
 
 	if(count($plugins_arr)) {
 		foreach($plugins_arr as $p) {
-			if(! in_array($p,$installed_arr)) {
+			if(! in_array($p, $installed_arr)) {
 				load_plugin($p);
 			}
 		}
@@ -1365,7 +1407,7 @@ function check_config(&$a) {
 }
 
 
-function fix_system_urls($oldurl,$newurl) {
+function fix_system_urls($oldurl, $newurl) {
 
 	require_once('include/crypto.php');
 
@@ -1456,7 +1498,7 @@ function login($register = false, $form_id = 'main-login', $hiddens=false) {
 	$a = get_app();
 	$o = '';
 	$reg = false;
-	$reglink = get_config('system','register_link');
+	$reglink = get_config('system', 'register_link');
 	if(! strlen($reglink))
 		$reglink = 'register';
 
@@ -1472,7 +1514,7 @@ function login($register = false, $form_id = 'main-login', $hiddens=false) {
 		$tpl = get_markup_template("logout.tpl");
 	}
 	else {
-		$a->page['htmlhead'] .= replace_macros(get_markup_template("login_head.tpl"),array(
+		$a->page['htmlhead'] .= replace_macros(get_markup_template("login_head.tpl"), array(
 			'$baseurl' => $a->get_baseurl(true)
 		));
 
@@ -1501,16 +1543,17 @@ function login($register = false, $form_id = 'main-login', $hiddens=false) {
 }
 
 
-// Used to end the current process, after saving session state.
-
+/**
+ * @brief Used to end the current process, after saving session state.
+ */
 function killme() {
 	session_write_close();
 	exit;
 }
 
-
-// redirect to another URL and terminate this process.
-
+/**
+ * @brief Redirect to another URL and terminate this process.
+ */
 function goaway($s) {
 	header("Location: $s");
 	killme();
@@ -1532,7 +1575,7 @@ function get_account_id() {
 }
 
 /**
- * @brief Returns the entity id of locally logged in user or false.
+ * @brief Returns the entity id (channel_id) of locally logged in user or false.
  *
  * Returns authenticated numeric channel_id if authenticated and connected to
  * a channel or 0. Sometimes referred to as $uid in the code.
@@ -1546,22 +1589,28 @@ function local_user() {
 	return false;
 }
 
-
-// Returns contact id of authenticated site visitor or false
-
+/**
+ * @brief Returns contact id (visitor_id) of authenticated site visitor or false.
+ *
+ * @return int|bool visitor_id or false
+ */
 function remote_user() {
-	if((x($_SESSION,'authenticated')) && (x($_SESSION,'visitor_id')))
+	if((x($_SESSION, 'authenticated')) && (x($_SESSION, 'visitor_id')))
 		return $_SESSION['visitor_id'];
+
 	return false;
 }
 
-
-// contents of $s are displayed prominently on the page the next time
-// a page is loaded. Usually used for errors or alerts.
-
+/**
+ * Contents of $s are displayed prominently on the page the next time
+ * a page is loaded. Usually used for errors or alerts.
+ *
+ * @param string $s Text to display
+ */
 function notice($s) {
 	$a = get_app();
 	if(! x($_SESSION, 'sysmsg')) $_SESSION['sysmsg'] = array();
+
 	if($a->interactive) {
 		// shameless plug, permission is denied and they have no identity.
 		// There's a fairly good chance that they've not got zot.
@@ -1572,7 +1621,13 @@ function notice($s) {
 	}
 }
 
-
+/**
+ * Contents of $s are displayed prominently on the page the next time a page is
+ * loaded. Usually used for information.
+ * For error and alerts use notice().
+ *
+ * @param string $s Text to display
+ */
 function info($s) {
 	$a = get_app();
 	if(! x($_SESSION, 'sysmsg_info')) $_SESSION['sysmsg_info'] = array();
@@ -1736,13 +1791,19 @@ function current_theme(){
 
 
 /**
- * Return full URL to theme which is currently in effect.
+ * @brief Return full URL to theme which is currently in effect.
+ *
  * Provide a sane default if nothing is chosen or the specified theme does not exist.
+ *
+ * @param bool $installing default false
+ *
+ * @return string
  */
-
 function current_theme_url($installing = false) {
 	global $a;
+
 	$t = current_theme();
+
 	$opts = '';
 	$opts = (($a->profile_uid) ? '?f=&puid=' . $a->profile_uid : '');
 	$opts .= ((x($a->layout,'schema')) ? '&schema=' . $a->layout['schema'] : '');
@@ -1761,10 +1822,12 @@ function current_theme_url($installing = false) {
  */
 function is_site_admin() {
 	$a = get_app();
+
 	if((intval($_SESSION['authenticated']))
 		&& (is_array($a->account))
 		&& ($a->account['account_roles'] & ACCOUNT_ROLE_ADMIN))
 		return true;
+
 	return false;
 }
 
@@ -1816,6 +1879,7 @@ function load_contact_links($uid) {
  *
  * @param array $params mapped array with query parameters
  * @param string $name of parameter, default null
+ *
  * @return string
  */
 function build_querystring($params, $name = null) {
@@ -1857,6 +1921,11 @@ function dba_timer() {
 	return microtime(true);
 }
 
+/**
+ * @brief Returns xchan_hash from the observer.
+ *
+ * @return string Empty if no observer, otherwise xchan_hash from observer
+ */
 function get_observer_hash() {
 	$observer = get_app()->get_observer();
 	if(is_array($observer))
@@ -1892,6 +1961,7 @@ function curPageURL() {
  *
  * @param App $a global application object
  * @param string $navname
+ *
  * @return mixed
  */
 function get_custom_nav(&$a, $navname) {
@@ -2043,12 +2113,20 @@ function construct_page(&$a) {
 	);
 }
 
-
+/**
+ * @brief Returns RedMatrix's root directory.
+ *
+ * @return string
+ */
 function appdirpath() {
 	return dirname(__FILE__);
 }
 
-
+/**
+ * @brief Set a pageicon.
+ *
+ * @param string $icon
+ */
 function head_set_icon($icon) {
 	global $a;
 
@@ -2056,6 +2134,11 @@ function head_set_icon($icon) {
 //	logger('head_set_icon: ' . $icon);
 }
 
+/**
+ * @brief Get the pageicon.
+ *
+ * @return string absolut path to pageicon
+ */
 function head_get_icon() {
 	global $a;
 
@@ -2066,6 +2149,11 @@ function head_get_icon() {
 	return $icon;
 }
 
+/**
+ * @brief Return the Realm of the directory.
+ *
+ * @return string
+ */
 function get_directory_realm() {
 	if($x = get_config('system', 'directory_realm'))
 		return $x;