Merge pull request #689 from dawnbreak/docu

Some Doxygen documentation.

2 files changed, 290 insertions, 206 deletions

diff --git a/boot.php b/boot.php
index fb059f8b0..d883dcc28 100755
--- a/boot.php
+++ b/boot.php
@@ -1,6 +1,8 @@
 <?php
-/** @file */
-
+/** @file boot.php
+ *
+ * This file defines some global constants and includes the central App class.
+ */
 
 /**
  * Red Matrix.
@@ -50,7 +52,7 @@ define ( 'ZOT_REVISION',            1     );
 
 define ( 'DB_UPDATE_VERSION',       1131  );
 
-define ( 'EOL',                    '<br />' . "\r\n"      );
+define ( 'EOL',                    '<br>' . "\r\n"        );
 define ( 'ATOM_TIME',              'Y-m-d\TH:i:s\Z'       );
 define ( 'NULL_DATE',              '0000-00-00 00:00:00'  );
 define ( 'TEMPLATE_BUILD_PATH',    'store/[data]/smarty3' );
@@ -196,7 +198,6 @@ define ( 'UPDATE_SUCCESS', 0);
 define ( 'UPDATE_FAILED',  1);
 
 
-
 define ( 'CLIENT_MODE_NORMAL', 0x0000);
 define ( 'CLIENT_MODE_LOAD',   0x0001);
 define ( 'CLIENT_MODE_UPDATE', 0x0002);
@@ -263,13 +264,11 @@ define ( 'NETWORK_PHANTOM',          'unkn');    // Place holder
  * Permissions
  */
 
-
 define ( 'PERMS_R_STREAM',         0x00001);
 define ( 'PERMS_R_PROFILE',        0x00002);
 define ( 'PERMS_R_PHOTOS',         0x00004);
 define ( 'PERMS_R_ABOOK',          0x00008);
 
-
 define ( 'PERMS_W_STREAM',         0x00010);
 define ( 'PERMS_W_WALL',           0x00020);
 define ( 'PERMS_W_TAGWALL',        0x00040);
@@ -321,7 +320,6 @@ define ( 'ATTACH_FLAG_DIR',    0x0001);
 define ( 'ATTACH_FLAG_OS',     0x0002);
 
 
-
 define ( 'MENU_ITEM_ZID',       0x0001);
 define ( 'MENU_ITEM_NEWWIN',    0x0002);
 define ( 'MENU_ITEM_CHATROOM',  0x0004);
@@ -336,13 +334,11 @@ define ( 'POLL_MULTIPLE_CHOICE', 0x0004);
 define ( 'POLL_OVERWRITE',       0x8000);  // If you vote twice remove the prior entry
 
 
-
 define ( 'UPDATE_FLAGS_UPDATED',  0x0001);
 define ( 'UPDATE_FLAGS_FORCED',   0x0002);
 define ( 'UPDATE_FLAGS_DELETED',  0x1000);
 
 
-
 define ( 'DROPITEM_NORMAL',      0);
 define ( 'DROPITEM_PHASE1',      1);
 define ( 'DROPITEM_PHASE2',      2);
@@ -448,7 +444,6 @@ define ( 'TERM_OBJ_OBJECT',  5 );
 define ( 'TERM_OBJ_THING',   6 );
 define ( 'TERM_OBJ_APP',     7 );
 
-
 /**
  * various namespaces we may need to parse
  */
@@ -513,7 +508,6 @@ define ( 'GRAVITY_PARENT',       0);
 define ( 'GRAVITY_LIKE',         3);
 define ( 'GRAVITY_COMMENT',      6);
 
-
 /**
  * Account Flags
  */
@@ -589,7 +583,6 @@ function startup() {
 	@set_time_limit(0);
 
 	if(function_exists ('ini_set')) {
-
 		// This has to be quite large to deal with embedded private photos
 		@ini_set('pcre.backtrack_limit', 500000);
 
@@ -615,7 +608,6 @@ function startup() {
 		}
 		unset($process);
 	}
-
 }
 
 /**
@@ -630,8 +622,6 @@ function startup() {
  * before we spit the page out.
  *
  */
-
-
 class App {
 
 	public  $install    = false;           // true if we are installing the software
@@ -643,7 +633,6 @@ class App {
 	public  $poi        = null;            // "person of interest", generally a referenced connection
 	public  $layout     = array();         // Comanche parsed template
 
-
 	private $perms      = null;            // observer permissions
 	private $widgets    = array();         // widgets for this page
 	private $widgetlist = null;            // widget ordering and inclusion directives
@@ -672,7 +661,7 @@ class App {
 	public  $timezone;
 	public  $interactive = true;
 	public  $plugins;
-	private  $apps = array();
+	private $apps = array();
 	public  $identities;
 	public  $css_sources = array();
 	public  $js_sources = array();
@@ -680,16 +669,16 @@ class App {
 	public  $is_sys = false;
 	public  $nav_sel;
 
-	public $category;
+	public  $category;
 
 	// Allow themes to control internal parameters
 	// by changing App values in theme.php
 
-	public	$sourcename = '';
-	public	$videowidth = 425;
-	public	$videoheight = 350;
-	public	$force_max_items = 0;
-	public	$theme_thread_allow = true;
+	public  $sourcename = '';
+	public  $videowidth = 425;
+	public  $videoheight = 350;
+	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
@@ -732,9 +721,7 @@ class App {
 	private $cached_profile_picdate;
 
 
-
 	function __construct() {
-
 		// we'll reset this after we read our config file
 		date_default_timezone_set('UTC');
 
@@ -753,7 +740,6 @@ class App {
 			. 'library/langdet' . PATH_SEPARATOR
 			. '.' );
 
-
 		$this->scheme = 'http';
 		if(x($_SERVER,'HTTPS') && $_SERVER['HTTPS'])
 			$this->scheme = 'https';
@@ -792,7 +778,6 @@ class App {
 			$this->cmd = 'channel/' . substr($this->cmd,1);
 
 
-
 		/**
 		 *
 		 * Break the URL path into C style argc/argv style arguments for our
@@ -820,7 +805,6 @@ class App {
 			$this->module = 'home';
 		}
 
-
 		/**
 		 * See if there is any page number information, and initialise
 		 * pagination
@@ -857,8 +841,6 @@ class App {
 	}
 
 	function get_baseurl($ssl = false) {
-
-
 		if(is_array($this->config)
 			&& array_key_exists('system',$this->config)
 			&& is_array($this->config['system'])
@@ -868,7 +850,6 @@ class App {
 			return $url;
 		}
 
-
 		$scheme = $this->scheme;
 
 		$this->baseurl = $scheme . "://" . $this->hostname . ((isset($this->path) && strlen($this->path)) ? '/' . $this->path : '' );
@@ -933,7 +914,6 @@ class App {
 		return $this->channel;
 	}
 
-
 	function set_observer($xchan) {
 		$this->observer = $xchan;
 	}
@@ -1097,6 +1077,7 @@ class App {
 				break;
 		}*/
 	}
+
 	function get_template_ldelim($engine = 'smarty3') {
 		return $this->ldelim[$engine];
 	}
@@ -1107,7 +1088,6 @@ class App {
 
 	function head_set_icon($icon) {
 		$this->data['pageicon'] = $icon;
-
 	}
 
 	function head_get_icon() {
@@ -1117,7 +1097,7 @@ class App {
 		return $icon;
 	}
 
-}
+} // End App class
 
 
 // retrieve the App structure
@@ -1129,21 +1109,26 @@ function get_app() {
 }
 
 
-
-// Multi-purpose function to check variable state.
-// Usage: x($var) or $x($array,'key')
-// returns false if variable/key is not set
-// if variable is set, returns 1 if has 'non-zero' value, otherwise returns 0.
-// e.g. x('') or x(0) returns 0;
-
-
-function x($s,$k = NULL) {
-	if($k != NULL) {
-		if((is_array($s)) && (array_key_exists($k,$s))) {
+/**
+ * @brief Multi-purpose function to check variable state.
+ *
+ * Usage: x($var) or $x($array, 'key')
+ *
+ * returns false if variable/key is not set
+ * if variable is set, returns 1 if has 'non-zero' value, otherwise returns 0.
+ * e.g. x('') or x(0) returns 0;
+ *
+ * @param string|array $s variable to check
+ * @param string $k key inside the array to check
+ * @return bool
+ */
+function x($s, $k = null) {
+	if($k != null) {
+		if((is_array($s)) && (array_key_exists($k, $s))) {
 			if($s[$k])
 				return (int) 1;
 			return (int) 0;
-	}
+		}
 		return false;
 	}
 	else {
@@ -1160,7 +1145,6 @@ function x($s,$k = NULL) {
 
 // called from db initialisation if db is dead.
 
-
 function system_unavailable() {
 	include('include/system_unavailable.php');
 	system_down();
@@ -1170,6 +1154,7 @@ function system_unavailable() {
 
 function clean_urls() {
 	global $a;
+
 	//	if($a->config['system']['clean_urls'])
 	return true;
 	//	return false;
@@ -1177,9 +1162,11 @@ function clean_urls() {
 
 function z_path() {
 	global $a;
+
 	$base = $a->get_baseurl();
 	if(! clean_urls())
 		$base .= '/?q=';
+
 	return $base;
 }
 
@@ -1191,6 +1178,7 @@ function z_root() {
 function absurl($path) {
 	if(strpos($path,'/') === 0)
 		return z_path() . $path;
+
 	return $path;
 }
 
@@ -1200,9 +1188,6 @@ function os_mkdir($path,$mode = 0777,$recursive = false) {
 	@umask($oldumask); 
 }
 
-
-
-
 function is_ajax() {
 	return (!empty($_SERVER['HTTP_X_REQUESTED_WITH']) && strtolower($_SERVER['HTTP_X_REQUESTED_WITH']) == 'xmlhttprequest');
 }
@@ -1212,7 +1197,6 @@ function is_ajax() {
 // base url for use in cmdline programs which don't have
 // $_SERVER variables, and synchronising the state of installed plugins.
 
-
 function check_config(&$a) {
 
 	$build = get_config('system','db_version');
@@ -1222,21 +1206,22 @@ function check_config(&$a) {
 	$saved = get_config('system','urlverify');
 	if(! $saved)
 		set_config('system','urlverify',bin2hex(z_root()));
+
 	if(($saved) && ($saved != bin2hex(z_root()))) {
 		// our URL changed. Do something.
 
 		$oldurl = hex2bin($saved);
 		logger('Baseurl changed!');
 
-		$oldhost = substr($oldurl,strpos($oldurl,'//')+2);
-		$host = substr(z_root(),strpos(z_root(),'//')+2);
+		$oldhost = substr($oldurl, strpos($oldurl, '//') + 2);
+		$host = substr(z_root(), strpos(z_root(), '//') + 2);
 
 		$is_ip_addr = ((preg_match("/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/",$host)) ? true : false);
 		$was_ip_addr = ((preg_match("/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/",$oldhost)) ? true : false);
 		// only change the url to an ip address if it was already an ip and not a dns name
 		if((! $is_ip_addr) || ($is_ip_addr && $was_ip_addr)) {
 			fix_system_urls($oldurl,z_root());
-			set_config('system','urlverify',bin2hex(z_root()));
+			set_config('system', 'urlverify', bin2hex(z_root()));
 		}
 		else
 			logger('Attempt to change baseurl from a DNS name to an IP address was refused.');
@@ -1251,8 +1236,8 @@ function check_config(&$a) {
 	// so we just need to keep this around a couple of weeks until the hubs that
 	// already exist have one
 	$syschan_exists = get_sys_channel();
-		if (! $syschan_exists)
-			create_sys_channel();
+	if (! $syschan_exists)
+		create_sys_channel();
 
 	if($build != DB_UPDATE_VERSION) {
 		$stored = intval($build);
@@ -1323,7 +1308,6 @@ function check_config(&$a) {
 						}
 						else
 							set_config('database','update_r' . $x, 'success');
-
 					}
 				}
 				set_config('system','db_version', DB_UPDATE_VERSION);
@@ -1380,13 +1364,10 @@ function check_config(&$a) {
 		}
 	}
 
-
 	load_hooks();
-	return;
 }
 
 
-
 function fix_system_urls($oldurl,$newurl) {
 
 	require_once('include/crypto.php');
@@ -1470,16 +1451,13 @@ function fix_system_urls($oldurl,$newurl) {
 }
 
 
-
-
 // wrapper for adding a login box. If $register == true provide a registration
 // link. This will most always depend on the value of $a->config['system']['register_policy'].
 // returns the complete html for inserting into the page
 
-
 function login($register = false, $form_id = 'main-login', $hiddens=false) {
 	$a = get_app();
-	$o = "";
+	$o = '';
 	$reg = false;
 	$reglink = get_config('system','register_link');
 	if(! strlen($reglink))
@@ -1498,17 +1476,15 @@ function login($register = false, $form_id = 'main-login', $hiddens=false) {
 	}
 	else {
 		$a->page['htmlhead'] .= replace_macros(get_markup_template("login_head.tpl"),array(
-			'$baseurl'		=> $a->get_baseurl(true)
+			'$baseurl' => $a->get_baseurl(true)
 		));
 
 		$tpl = get_markup_template("login.tpl");
 		if(strlen($a->query_string))
-				$_SESSION['login_return_url'] = $a->query_string;
+			$_SESSION['login_return_url'] = $a->query_string;
 	}
 
-
 	$o .= replace_macros($tpl,array(
-
 		'$dest_url'     => $dest_url,
 		'$logout'       => t('Logout'),
 		'$login'        => t('Login'),
@@ -1517,14 +1493,12 @@ function login($register = false, $form_id = 'main-login', $hiddens=false) {
 		'$lpassword'    => array('password', t('Password'), '', ''),
 		'$remember'     => array('remember', t('Remember me'), '', ''),
 		'$hiddens'      => $hiddens,
-
 		'$register'     => $reg,
-
 		'$lostpass'     => t('Forgot your password?'),
 		'$lostlink'     => t('Password Reset'),
 	));
 
-	call_hooks('login_hook',$o);
+	call_hooks('login_hook', $o);
 
 	return $o;
 }
@@ -1532,7 +1506,6 @@ function login($register = false, $form_id = 'main-login', $hiddens=false) {
 
 // Used to end the current process, after saving session state.
 
-
 function killme() {
 	session_write_close();
 	exit;
@@ -1541,33 +1514,44 @@ function killme() {
 
 // redirect to another URL and terminate this process.
 
-
 function goaway($s) {
 	header("Location: $s");
 	killme();
 }
 
-
+/**
+ * @brief Returns the entity id of locally logged in account or false.
+ *
+ * Returns numeric account_id if authenticated or 0. It is possible to be
+ * authenticated and not connected to a channel.
+ *
+ * @return int|bool account_id or false
+ */
 function get_account_id() {
 	if(get_app()->account)
 		return intval(get_app()->account['account_id']);
+
 	return false;
 }
 
-
-// Returns the entity id of locally logged in user or false.
-
-
+/**
+ * @brief Returns the entity 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.
+ *
+ * @return int|bool channel_id or false
+ */
 function local_user() {
-	if((x($_SESSION,'authenticated')) && (x($_SESSION,'uid')))
+	if((x($_SESSION, 'authenticated')) && (x($_SESSION, 'uid')))
 		return intval($_SESSION['uid']);
+
 	return false;
 }
 
 
 // Returns contact id of authenticated site visitor or false
 
-
 function remote_user() {
 	if((x($_SESSION,'authenticated')) && (x($_SESSION,'visitor_id')))
 		return $_SESSION['visitor_id'];
@@ -1578,15 +1562,14 @@ function remote_user() {
 // contents of $s are displayed prominently on the page the next time
 // a page is loaded. Usually used for errors or alerts.
 
-
 function notice($s) {
 	$a = get_app();
-	if(! x($_SESSION,'sysmsg'))	$_SESSION['sysmsg'] = array();
+	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.
-		if((stristr($s,t('permission denied'))) && (! get_observer_hash())) {
-			$s .= '<br /><a href="http://getzot.com">' . t('Got Zot?') . '</a>';
+		if((stristr($s, t('permission denied'))) && (! get_observer_hash())) {
+			$s .= '<br><a href="http://getzot.com">' . t('Got Zot?') . '</a>';
 		}
 		$_SESSION['sysmsg'][] = $s;
 	}
@@ -1595,24 +1578,21 @@ function notice($s) {
 
 function info($s) {
 	$a = get_app();
-	if(! x($_SESSION,'sysmsg_info')) $_SESSION['sysmsg_info'] = array();
+	if(! x($_SESSION, 'sysmsg_info')) $_SESSION['sysmsg_info'] = array();
 	if($a->interactive)
 		$_SESSION['sysmsg_info'][] = $s;
 }
 
-
-
-// wrapper around config to limit the text length of an incoming message
-
-
+/**
+ * @brief Wrapper around config to limit the text length of an incoming message
+ *
+ * @return int
+ */
 function get_max_import_size() {
-	return(intval(get_config('system','max_import_size')));
+	return(intval(get_config('system', 'max_import_size')));
 }
 
 
-
-
-
 /**
  *
  * Wrap calls to proc_close(proc_open()) and call hook
@@ -1626,8 +1606,6 @@ function get_max_import_size() {
  *
  * $cmd and string args are surrounded with ""
  */
-
-
 function proc_run($cmd){
 
 	$a = get_app();
@@ -1660,24 +1638,28 @@ function proc_run($cmd){
 
 	if(count($args) && $args[0] === 'php')
 		$args[0] = ((x($a->config,'system')) && (x($a->config['system'],'php_path')) && (strlen($a->config['system']['php_path'])) ? $a->config['system']['php_path'] : 'php');
-	for($x = 0; $x < count($args); $x ++)
+
+	for($x = 0; $x < count($args); $x++)
 		$args[$x] = escapeshellarg($args[$x]);
 
 	$cmdline = implode($args," ");
 
-
 	if(is_windows()) {
 		$cwd = getcwd();
 		$cmd = "cmd /c start \"title\" /D \"$cwd\" /b $cmdline";
 		proc_close(proc_open($cmd, array(), $foo));
 	}
 	else
-		proc_close(proc_open($cmdline." &",array(),$foo));
+		proc_close(proc_open($cmdline ." &", array(), $foo));
 }
 
-
+/**
+ * @brief Checks if we are running on M$ Windows.
+ *
+ * @return bool true if we run on M$ Windows
+ */
 function is_windows() {
-	return ((strtoupper(substr(PHP_OS,0,3)) === 'WIN') ? true : false);
+	return ((strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') ? true : false);
 }
 
 
@@ -1709,7 +1691,6 @@ function current_theme(){
 			$page_theme = null;
 	}
 
-
 	$is_mobile = $a->is_mobile || $a->is_tablet;
 
 	$standard_system_theme = ((isset($a->config['system']['theme'])) ? $a->config['system']['theme'] : '');
@@ -1724,7 +1705,7 @@ function current_theme(){
 			$system_theme = ((isset($a->config['system']['mobile_theme'])) ? $a->config['system']['mobile_theme'] : '');
 			$theme_name = ((isset($_SESSION) && x($_SESSION,'mobile_theme')) ? $_SESSION['mobile_theme'] : $system_theme);
 
-			if($theme_name === '' || $theme_name === '---'  ) {
+			if($theme_name === '' || $theme_name === '---' ) {
 				// user has selected to have the mobile theme be the same as the normal one
 				$system_theme = $standard_system_theme;
 				$theme_name = $standard_theme_name;
@@ -1732,21 +1713,20 @@ function current_theme(){
 		}
 	}
 	else {
-			$system_theme = $standard_system_theme;
-			$theme_name = $standard_theme_name;
+		$system_theme = $standard_system_theme;
+		$theme_name = $standard_theme_name;
 
 		if($page_theme)
 			$theme_name = $page_theme;
 	}
 
-
 	if($theme_name &&
 			(file_exists('view/theme/' . $theme_name . '/css/style.css') ||
 					file_exists('view/theme/' . $theme_name . '/php/style.php')))
 		return($theme_name);
 
 	foreach($app_base_themes as $t) {
-		if(file_exists('view/theme/' . $t . '/css/style.css')||
+		if(file_exists('view/theme/' . $t . '/css/style.css') ||
 			file_exists('view/theme/' . $t . '/php/style.php'))
 			return($t);
 	}
@@ -1771,9 +1751,17 @@ function current_theme_url($installing = false) {
 	$opts .= ((x($a->layout,'schema')) ? '&schema=' . $a->layout['schema'] : '');
 	if(file_exists('view/theme/' . $t . '/php/style.php'))
 		return('view/theme/' . $t . '/php/style.pcss' . $opts);
+
 	return('view/theme/' . $t . '/css/style.css');
 }
 
+/**
+ * @brief Check if current user has admin role.
+ *
+ * Check if the current user has ACCOUNT_ROLE_ADMIN.
+ *
+ * @return bool true if user is an admin
+ */
 function is_site_admin() {
 	$a = get_app();
 	if((intval($_SESSION['authenticated']))
@@ -1783,19 +1771,25 @@ function is_site_admin() {
 	return false;
 }
 
+/**
+ * @brief Check if current user has developer role.
+ *
+ * Check if the current user has ACCOUNT_ROLE_DEVELOPER.
+ *
+ * @return bool true if user is a developer
+ */
 function is_developer() {
 	$a = get_app();
 	if((intval($_SESSION['authenticated']))
 		&& (is_array($a->account))
 		&& ($a->account['account_roles'] & ACCOUNT_ROLE_DEVELOPER))
 		return true;
+
 	return false;
 }
 
 
-
 function load_contact_links($uid) {
-
 	$a = get_app();
 
 	$ret = array();
@@ -1815,30 +1809,30 @@ function load_contact_links($uid) {
 	}
 	else
 		$ret['empty'] = true;
+
 	$a->contacts = $ret;
-	return;
 }
 
 
 /**
- * returns querystring as string from a mapped array
+ * @brief Returns querystring as string from a mapped array.
  *
- * @param params Array
+ * @param array $params mapped array with query parameters
+ * @param string $name of parameter, default null
  * @return string
  */
-
-function build_querystring($params, $name=null) {
-	$ret = "";
-	foreach($params as $key=>$val) {
+function build_querystring($params, $name = null) {
+	$ret = '';
+	foreach($params as $key => $val) {
 		if(is_array($val)) {
-			if($name==null) {
+			if($name === null) {
 				$ret .= build_querystring($val, $key);
 			} else {
-				$ret .= build_querystring($val, $name."[$key]");
+				$ret .= build_querystring($val, $name . "[$key]");
 			}
 		} else {
 			$val = urlencode($val);
-			if($name!=null) {
+			if($name != null) {
 				$ret .= $name . "[$key]" . "=$val&";
 			} else {
 				$ret .= "$key=$val&";
@@ -1858,6 +1852,7 @@ function argc() {
 function argv($x) {
 	if(array_key_exists($x,get_app()->argv))
 		return get_app()->argv[$x];
+
 	return '';
 }
 
@@ -1869,15 +1864,16 @@ function get_observer_hash() {
 	$observer = get_app()->get_observer();
 	if(is_array($observer))
 		return $observer['xchan_hash'];
+
 	return '';
 }
 
 
 /**
-* Returns the complete URL of the current page, e.g.: http(s)://something.com/network
-*
-* Taken from http://webcheatsheet.com/php/get_current_page_url.php
-*/
+ * Returns the complete URL of the current page, e.g.: http(s)://something.com/network
+ *
+ * Taken from http://webcheatsheet.com/php/get_current_page_url.php
+ */
 function curPageURL() {
 	$pageURL = 'http';
 	if ($_SERVER["HTTPS"] == "on") {$pageURL .= "s";}
@@ -1890,13 +1886,20 @@ function curPageURL() {
 	return $pageURL;
 }
 
-function get_custom_nav(&$a,$navname) {
+function get_custom_nav(&$a, $navname) {
 	if(! $navname)
 		return $a->page['nav'];
 	// load custom nav menu by name here
-
 }
 
+/**
+ * @brief Loads a page definition file for a module.
+ *
+ * If there is no parsed Comanche template already load a module's pdl file
+ * and parse it with Comanche.
+ *
+ * @param App &$a global application object
+ */
 function load_pdl(&$a) {
 	require_once('include/comanche.php');
 
@@ -1904,34 +1907,34 @@ function load_pdl(&$a) {
 		$n = 'mod_' . $a->module . '.pdl' ;
 		$u = comanche_get_channel_id();
 		if($u)
-			$s = get_pconfig($u,'system',$n);
+			$s = get_pconfig($u, 'system', $n);
+
 		if((! $s) && (($p = theme_include($n)) != ''))
 			$s = @file_get_contents($p);
+
 		if($s)
-			comanche_parser($a,$s);
+			comanche_parser($a, $s);
 	}
-
 }
 
-
-
+/**
+ * @brief build the page.
+ *
+ * Build the page - now that we have all the components
+ *
+ * @param App &$a global application object
+ */
 function construct_page(&$a) {
 
-
-	/**
-	 * Build the page - now that we have all the components
-	 */
-
-
 	$comanche = ((count($a->layout)) ? true : false);
 
 	require_once(theme_include('theme_init.php'));
 
 	$installing = false;
 
-	if($a->module == 'setup')
+	if($a->module == 'setup') {
 		$installing = true;
-	else {
+	} else {
 		nav($a);
 	}
 
@@ -1941,7 +1944,6 @@ function construct_page(&$a) {
 		}
 	}
 
-
 	if(($p = theme_include(current_theme() . '.js')) != '')
 		head_add_js($p);
 
@@ -1950,10 +1952,10 @@ function construct_page(&$a) {
 
 	require_once('include/js_strings.php');
 
-	if(x($a->page,'template_style'))
+	if(x($a->page, 'template_style'))
 		head_add_css($a->page['template_style'] . '.css');
 	else
-		head_add_css(((x($a->page,'template')) ? $a->page['template'] : 'default' ) . '.css');
+		head_add_css(((x($a->page, 'template')) ? $a->page['template'] : 'default' ) . '.css');
 
 	head_add_css('mod_' . $a->module . '.css');
 	head_add_css(current_theme_url($installing));
@@ -1963,11 +1965,12 @@ function construct_page(&$a) {
 	$a->build_pagehead();
 
 	$arr = $a->get_widgets();
-	ksort($arr,SORT_NUMERIC);
+	ksort($arr, SORT_NUMERIC);
 	if(count($arr)) {
 		foreach($arr as $x) {
-			if(! array_key_exists($x['location'],$a->page))
+			if(! array_key_exists($x['location'], $a->page))
 				$a->page[$x['location']] = '';
+
 			$a->page[$x['location']] .= $x['html'];
 		}
 	}
@@ -1983,27 +1986,25 @@ function construct_page(&$a) {
 
 	if($comanche) {
 		$arr = array('module' => $a->module, 'layout' => $a->layout);
-		call_hooks('construct_page',$arr);
+		call_hooks('construct_page', $arr);
 		$a->layout = $arr['layout'];
 
 		foreach($a->layout as $k => $v) {
-			if((strpos($k,'region_') === 0) && strlen($v)) {
-				if(strpos($v,'$region_') !== false) {
-					$v = preg_replace_callback('/\$region_([a-zA-Z0-9]+)/ism','comanche_replace_region',$v);
+			if((strpos($k, 'region_') === 0) && strlen($v)) {
+				if(strpos($v, '$region_') !== false) {
+					$v = preg_replace_callback('/\$region_([a-zA-Z0-9]+)/ism', 'comanche_replace_region', $v);
 				}
 
 				// And a couple of convenience macros
 
-				if(strpos($v,'$nav') !== false) {
-					$v = str_replace('$nav',$a->page['nav'],$v);
+				if(strpos($v, '$nav') !== false) {
+					$v = str_replace('$nav', $a->page['nav'], $v);
 				}
-				if(strpos($v,'$content') !== false) {
-
-					$v = str_replace('$content',$a->page['content'],$v);
+				if(strpos($v, '$content') !== false) {
+					$v = str_replace('$content', $a->page['content'], $v);
 				}
 
-				$a->page[substr($k,7)] = $v;
-
+				$a->page[substr($k, 7)] = $v;
 			}
 		}
 	}
@@ -2030,13 +2031,8 @@ function construct_page(&$a) {
 	header("Content-type: text/html; charset=utf-8");
 
 	require_once(theme_include(
-		((x($a->page,'template'))
-			? $a->page['template']
-			: 'default' )
-			. '.php' )
+		((x($a->page, 'template')) ? $a->page['template'] : 'default' ) . '.php' )
 	);
-
-	return;
 }
 
 
@@ -2047,20 +2043,24 @@ function appdirpath() {
 
 function head_set_icon($icon) {
 	global $a;
+
 	$a->data['pageicon'] = $icon;
 //	logger('head_set_icon: ' . $icon);
 }
 
 function head_get_icon() {
 	global $a;
+
 	$icon = $a->data['pageicon'];
-	if(! strpos($icon,'://'))
+	if(! strpos($icon, '://'))
 		$icon = z_root() . $icon;
+
 	return $icon;
 }
 
 function get_directory_realm() {
-	if($x = get_config('system','directory_realm'))
+	if($x = get_config('system', 'directory_realm'))
 		return $x;
+
 	return DIRECTORY_REALM;
 }
diff --git a/include/dba/dba_driver.php b/include/dba/dba_driver.php
index 3e19b7aa4..31b7890f1 100755
--- a/include/dba/dba_driver.php
+++ b/include/dba/dba_driver.php
@@ -1,23 +1,48 @@
-<?php /** @file */
+<?php
+/**
+ * @file dba_driver.php
+ * @brief some database related functions and abstract driver class.
+ *
+ * This file contains the abstract database driver class dba_driver and some
+ * functions for working with databases.
+ */
 
-function dba_factory($server, $port,$user,$pass,$db,$install = false) {
+/**
+ * @brief Returns the database driver object.
+ *
+ * If available it will use PHP's mysqli otherwise mysql driver.
+ *
+ * @param string $server DB server name
+ * @param string $port DB port
+ * @param string $user DB username
+ * @param string $pass DB password
+ * @param string $db database name
+ * @param bool $install Defaults to false
+ * @return null|dba_driver A database driver object (dba_mysql|dba_mysqli) or null if no driver found.
+ */
+function dba_factory($server, $port, $user, $pass, $db, $install = false) {
 	$dba = null;
 
-	if(class_exists('mysqli')) {
+	if (class_exists('mysqli')) {
         if (is_null($port)) $port = ini_get("mysqli.default_port");
 		require_once('include/dba/dba_mysqli.php');
-		$dba = new dba_mysqli($server, $port,$user,$pass,$db,$install);
+		$dba = new dba_mysqli($server, $port, $user, $pass, $db, $install);
 	}
 	else {
-        if (is_null($port)) $port = "3306";
+		if (is_null($port)) $port = "3306";
 		require_once('include/dba/dba_mysql.php');
-		$dba = new dba_mysql($server, $port,$user,$pass,$db,$install);
+		$dba = new dba_mysql($server, $port, $user, $pass, $db, $install);
 	}
 
 	return $dba;
 }
 
-
+/**
+ * @brief abstract database driver class.
+ *
+ * This class gets extended by the real database driver classes, e.g. dba_mysql,
+ * dba_mysqli.
+ */
 abstract class dba_driver {
 
 	protected $debug = 0;
@@ -25,20 +50,54 @@ abstract class dba_driver {
 	public  $connected = false;
 	public  $error = false;
 
-	abstract function connect($server, $port, $user,$pass,$db);
+	/**
+	 * @brief Connect to the database.
+	 *
+	 * This abstract function needs to be implemented in the real driver.
+	 *
+	 * @param string $server DB server name
+	 * @param string $port DB port
+	 * @param string $user DB username
+	 * @param string $pass DB password
+	 * @param string $db database name
+	 * @return bool
+	 */
+	abstract function connect($server, $port, $user, $pass, $db);
+
+	/**
+	 * @brief Perform a DB query with the SQL statement $sql.
+	 *
+	 * This abstract function needs to be implemented in the real driver.
+	 *
+	 * @param string $sql The SQL query to execute
+	 */
 	abstract function q($sql);
+
+	/**
+	 * @brief Escape a string before being passed to a DB query.
+	 *
+	 * This abstract function needs to be implemented in the real driver.
+	 *
+	 * @param string $str The string to escape.
+	 */
 	abstract function escape($str);
+
+	/**
+	 * @brief Close the database connection.
+	 *
+	 * This abstract function needs to be implemented in the real driver.
+	 */
 	abstract function close();
 
+
 	function __construct($server, $port, $user,$pass,$db,$install = false) {
-		if(($install) && (! $this->install($server, $port, $user,$pass,$db))) {
+		if(($install) && (! $this->install($server, $port, $user, $pass, $db))) {
 			return;
 		}
-		$this->connect($server, $port, $user,$pass,$db);
+		$this->connect($server, $port, $user, $pass, $db);
 	}
 
-
-	function install($server,$user,$pass,$db) {
+	function install($server, $user, $pass, $db) {
 		if (!(strlen($server) && strlen($user))){
 			$this->connected = false;
 			$this->db = null;
@@ -56,7 +115,11 @@ abstract class dba_driver {
 		return true;
 	}
 
-
+	/**
+	 * @brief Sets the database driver's debugging state.
+	 *
+	 * @param int $dbg 0 to disable debugging
+	 */
 	function dbg($dbg) {
 		$this->debug = $dbg;
 	}
@@ -67,10 +130,12 @@ abstract class dba_driver {
 		}
 	}
 
-}
+} // end abstract dba_driver class
 
 
 
+// Procedural functions
+
 function printable($s) {
 	$s = preg_replace("~([\x01-\x08\x0E-\x0F\x10-\x1F\x7F-\xFF])~",".", $s);
 	$s = str_replace("\x00",'.',$s);
@@ -79,91 +144,110 @@ function printable($s) {
 	return $s;
 }
 
-// Procedural functions
-
+/**
+ * @brief set database driver debugging state.
+ *
+ * @param int $state 0 to disable debugging
+ */
 function dbg($state) {
 	global $db;
+
 	if($db)
-	$db->dbg($state);
+		$db->dbg($state);
 }
 
-
+/**
+ * @brief Escape strings being passed to DB queries.
+ *
+ * Always escape strings being used in DB queries. This function returns the
+ * escaped string. Integer DB parameters should all be proven integers by
+ * wrapping with intval().
+ *
+ * @param string $str A string to pass to a DB query
+ * @return Return an escaped string of the value to pass to a DB query.
+ */
 function dbesc($str) {
 	global $db;
+
 	if($db && $db->connected)
 		return($db->escape($str));
 	else
-		return(str_replace("'","\\'",$str));
+		return(str_replace("'", "\\'", $str));
 }
 
-
-
-// Function: q($sql,$args);
-// Description: execute SQL query with printf style args.
-// Example: $r = q("SELECT * FROM `%s` WHERE `uid` = %d",
-//                   'user', 1);
-
-
+/**
+ * @brief Execute a SQL query with printf style args.
+ *
+ * printf style arguments %s and %d are replaced with variable arguments, which
+ * should each be appropriately dbesc() or intval().
+ * SELECT queries return an array of results or false if SQL or DB error. Other
+ * queries return true if the command was successful or false if it wasn't.
+ *
+ * Example:
+ *  $r = q("SELECT * FROM `%s` WHERE `uid` = %d",
+ *         'user', 1);
+ *
+ * @param string $sql The SQL query to execute
+ * @return bool|array
+ */
 function q($sql) {
-
 	global $db;
+
 	$args = func_get_args();
 	unset($args[0]);
 
 	if($db && $db->connected) {
-		$stmt = vsprintf($sql,$args);
+		$stmt = vsprintf($sql, $args);
 		if($stmt === false) {
-			if(version_compare(PHP_VERSION,'5.4.0') >= 0)
-				logger('dba: vsprintf error: ' . print_r(debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT,1),true));
+			if(version_compare(PHP_VERSION, '5.4.0') >= 0)
+				logger('dba: vsprintf error: ' .
+					print_r(debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT, 1), true));
 			else
-				logger('dba: vsprintf error: ' . print_r(debug_backtrace(),true));
+				logger('dba: vsprintf error: ' . print_r(debug_backtrace(), true));
 		}
 		return $db->q($stmt);
 	}
 
-	/**
-	 *
+	/*
 	 * This will happen occasionally trying to store the 
 	 * session data after abnormal program termination 
-	 *
 	 */
 	logger('dba: no database: ' . print_r($args,true));
-	return false; 
 
+	return false;
 }
 
 /**
+ * @brief Raw DB query, no arguments.
  *
- * Raw db query, no arguments
+ * This function executes a raw DB query without any arguments.
  *
+ * @param string $sql The SQL query to execute
  */
-
-
 function dbq($sql) {
-
 	global $db;
+
 	if($db && $db->connected)
 		$ret = $db->q($sql);
 	else
 		$ret = false;
+
 	return $ret;
 }
 
 
-// Caller is responsible for ensuring that any integer arguments to 
+
+// Caller is responsible for ensuring that any integer arguments to
 // dbesc_array are actually integers and not malformed strings containing
 // SQL injection vectors. All integer array elements should be specifically 
 // cast to int to avoid trouble. 
 
-
-
 function dbesc_array_cb(&$item, $key) {
 	if(is_string($item))
 		$item = dbesc($item);
 }
 
 
-
 function dbesc_array(&$arr) {
 	if(is_array($arr) && count($arr)) {
 		array_walk($arr,'dbesc_array_cb');