Correcting reported Doxygen syntax warnings.

Fixed wrong Doxygen syntax and add some of the available FIXME to
Doxygen documentation.
Updated Doxygen configuration to add also all capital letter tags.
Adding some more Doxygen documentation.

31 files changed, 2832 insertions, 2834 deletions

diff --git a/boot.php b/boot.php
index aac8eff12..deed8b8d3 100755
--- a/boot.php
+++ b/boot.php
@@ -52,13 +52,11 @@ define ( 'ZOT_REVISION',            1     );
 define ( 'DB_UPDATE_VERSION',       1140  );
 
 /**
- * Constant with a HTML line break.
+ * @brief Constant with a HTML line break.
  *
  * Contains a HTML line break (br) element and a real carriage return with line
  * feed for the source.
  * This can be used in HTML and JavaScript where needed a line break.
- *
- * @var string
  */
 define ( 'EOL',                    '<br>' . "\r\n"        );
 define ( 'ATOM_TIME',              'Y-m-d\TH:i:s\Z'       );
@@ -707,8 +705,6 @@ class App {
 	 *
 	 * Mostly unimplemented yet. Only options 'template_engine' and
 	 * beyond are used.
-	 *
-	 * @var array
 	 */
 	private $theme = array(
 		'sourcename' => '',
@@ -721,15 +717,11 @@ class App {
 	);
 
 	/**
-	 * array of registered template engines ('name'=>'class name')
-	 *
-	 * @var array
+	 * @brief An array of registered template engines ('name'=>'class name')
 	 */
 	public $template_engines = array();
 	/**
-	 * array of instanced template engines ('name'=>'instance')
-	 *
-	 * @var array
+	 * @brief An array of instanced template engines ('name'=>'instance')
 	 */
 	public $template_engine_instance = array();
 
@@ -806,9 +798,7 @@ class App {
 		if(substr($this->cmd, 0, 1) === '~')
 			$this->cmd = 'channel/' . substr($this->cmd, 1);
 
-
-		/**
-		 *
+		/*
 		 * Break the URL path into C style argc/argv style arguments for our
 		 * modules. Given "http://example.com/module/arg1/arg2", $this->argc
 		 * will be 3 (integer) and $this->argv will contain:
@@ -816,25 +806,22 @@ class App {
 		 *   [1] => 'arg1'
 		 *   [2] => 'arg2'
 		 *
-		 *
 		 * There will always be one argument. If provided a naked domain
 		 * URL, $this->argv[0] is set to "home".
-		 *
 		 */
 
-		$this->argv = explode('/',$this->cmd);
+		$this->argv = explode('/', $this->cmd);
 		$this->argc = count($this->argv);
-		if((array_key_exists('0',$this->argv)) && strlen($this->argv[0])) {
+		if ((array_key_exists('0', $this->argv)) && strlen($this->argv[0])) {
 			$this->module = str_replace(".", "_", $this->argv[0]);
 			$this->module = str_replace("-", "_", $this->module);
-		}
-		else {
+		} else {
 			$this->argc = 1;
 			$this->argv = array('home');
 			$this->module = 'home';
 		}
 
-		/**
+		/*
 		 * See if there is any page number information, and initialise
 		 * pagination
 		 */
@@ -846,7 +833,7 @@ class App {
 			$this->pager['start'] = 0;
 		$this->pager['total'] = 0;
 
-		/**
+		/*
 		 * Detect mobile devices
 		 */
 
@@ -858,7 +845,7 @@ class App {
 
 		BaseObject::set_app($this);
 
-		/**
+		/*
 		 * register template engines
 		 */
 		$dc = get_declared_classes();
@@ -2028,7 +2015,7 @@ function curPageURL() {
  * @return mixed
  */
 function get_custom_nav(&$a, $navname) {
-	if(! $navname)
+	if (! $navname)
 		return $a->page['nav'];
 	// load custom nav menu by name here
 }
@@ -2044,7 +2031,7 @@ function get_custom_nav(&$a, $navname) {
 function load_pdl(&$a) {
 	require_once('include/comanche.php');
 
-	if(! count($a->layout)) {
+	if (! count($a->layout)) {
 		$n = 'mod_' . $a->module . '.pdl' ;
 		$u = comanche_get_channel_id();
 		if($u)
@@ -2070,7 +2057,6 @@ function exec_pdl(&$a) {
 }
 
 
-
 /**
  * @brief build the page.
  *
@@ -2080,7 +2066,6 @@ function exec_pdl(&$a) {
  */
 function construct_page(&$a) {
 
-
 	exec_pdl($a);
 
 	$comanche = ((count($a->layout)) ? true : false);
@@ -2089,28 +2074,27 @@ function construct_page(&$a) {
 
 	$installing = false;
 
-	if($a->module == 'setup') {
+	if ($a->module == 'setup') {
 		$installing = true;
 	} else {
 		nav($a);
 	}
 
-	if($comanche) {
-
-		if($a->layout['nav']) {
+	if ($comanche) {
+		if ($a->layout['nav']) {
 			$a->page['nav'] = get_custom_nav($a, $a->layout['nav']);
 		}
 	}
 
-	if(($p = theme_include(current_theme() . '.js')) != '')
+	if (($p = theme_include(current_theme() . '.js')) != '')
 		head_add_js($p);
 
-	if(($p = theme_include('mod_' . $a->module . '.php')) != '')
+	if (($p = theme_include('mod_' . $a->module . '.php')) != '')
 		require_once($p);
 
 	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');
@@ -2147,7 +2131,6 @@ function construct_page(&$a) {
 		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) {
@@ -2249,11 +2232,11 @@ function get_directory_realm() {
  */
 function get_directory_primary() {
 
-   $dirmode = intval(get_config('system','directory_mode'));
+	$dirmode = intval(get_config('system','directory_mode'));
 
-    if($dirmode == DIRECTORY_MODE_STANDALONE || $dirmode == DIRECTORY_MODE_PRIMARY) {
+	if($dirmode == DIRECTORY_MODE_STANDALONE || $dirmode == DIRECTORY_MODE_PRIMARY) {
 		return z_root();
-    }
+	}
 
 	if($x = get_config('system', 'directory_primary'))
 		return $x;
@@ -2262,13 +2245,11 @@ function get_directory_primary() {
 }
 
 
-
 /**
- * @brief return relative date of last completed poller execution
+ * @brief return relative date of last completed poller execution.
  */
-
 function get_poller_runtime() {
-	$t = get_config('system','lastpoll');
+	$t = get_config('system', 'lastpoll');
 	return relative_date($t);
 }
 
@@ -2302,7 +2283,12 @@ function z_check_cert() {
 } 
 
 
-
+/**
+ * @brief Send email to admin if server has an invalid certificate.
+ *
+ * If a RedMatrix hub is available over https it must have a publicly valid
+ * certificate.
+ */
 function cert_bad_email() {
 
 	$a = get_app();
@@ -2319,13 +2305,12 @@ function cert_bad_email() {
 		'From: Administrator' . '@' . $a->get_hostname() . "\n"
 		. 'Content-type: text/plain; charset=UTF-8' . "\n"
 		. 'Content-transfer-encoding: 8bit' );
-
 }
 
 
-// send warnings every 3-5 days if cron is not running.
-
-
+/**
+ * @brief Send warnings every 3-5 days if cron is not running.
+ */
 function check_cron_broken() {
 
 	$t = get_config('system','lastpollcheck');
diff --git a/include/ITemplateEngine.php b/include/ITemplateEngine.php
index 53c1845f4..7bd559a63 100755
--- a/include/ITemplateEngine.php
+++ b/include/ITemplateEngine.php
@@ -1,11 +1,10 @@
-<?php

-require_once 'boot.php';

-

-

-/**

- * Interface for template engines

- */

-interface ITemplateEngine {

-	public function replace_macros($s,$v);

-	public function get_markup_template($file, $root='');

-}

+<?php
+require_once 'boot.php';
+
+/**
+ * @brief Interface for template engines.
+ */
+interface ITemplateEngine {
+	public function replace_macros($s, $v);
+	public function get_markup_template($file, $root='');
+}
diff --git a/include/account.php b/include/account.php
index caac0b178..5926e05c1 100644
--- a/include/account.php
+++ b/include/account.php
@@ -1,4 +1,8 @@
-<?php /** @file */
+<?php
+/**
+ * @file include/account.php
+ * @brief Somme account related functions.
+ */
 
 require_once('include/config.php');
 require_once('include/network.php');
@@ -43,15 +47,14 @@ function check_account_email($email) {
 function check_account_password($password) {
 	$result = array('error' => false, 'message' => '');
 
-	// The only validation we perform by default is pure Javascript to 
+	// The only validation we perform by default is pure Javascript to
 	// check minimum length and that both entered passwords match.
-	// Use hooked functions to perform complexity requirement checks. 
+	// Use hooked functions to perform complexity requirement checks.
 
 	$arr = array('password' => $password, 'result' => $result);
 	call_hooks('check_account_password', $arr);
 
 	return $arr['result'];
-
 }
 
 function check_account_invite($invite_code) {
@@ -75,7 +78,6 @@ function check_account_invite($invite_code) {
 	call_hooks('check_account_invite', $arr);
 
 	return $arr['result'];
-
 }
 
 function check_account_admin($arr) {
@@ -109,7 +111,7 @@ function create_account($arr) {
 	$flags       = ((x($arr,'account_flags')) ? intval($arr['account_flags'])      : ACCOUNT_OK);
 	$roles       = ((x($arr,'account_roles')) ? intval($arr['account_roles'])      : 0 );
 	$expires     = ((x($arr,'expires'))       ? intval($arr['expires'])            : NULL_DATE);
-	
+
 	$default_service_class = get_config('system','default_service_class');
 
 	if($default_service_class === false)
@@ -132,16 +134,16 @@ function create_account($arr) {
 	// allow the admin_email account to be admin, but only if it's the first account.
 
 	$c = account_total();
-	if(($c === 0) && (check_account_admin($arr)))
+	if (($c === 0) && (check_account_admin($arr)))
 		$roles |= ACCOUNT_ROLE_ADMIN;
 
-    // Ensure that there is a host keypair.
+	// Ensure that there is a host keypair.
 
-    if((! get_config('system','pubkey')) && (! get_config('system','prvkey'))) {
-        $hostkey = new_keypair(4096);
-        set_config('system','pubkey',$hostkey['pubkey']);
-        set_config('system','prvkey',$hostkey['prvkey']);
-    }
+	if ((! get_config('system', 'pubkey')) && (! get_config('system', 'prvkey'))) {
+		$hostkey = new_keypair(4096);
+		set_config('system', 'pubkey', $hostkey['pubkey']);
+		set_config('system', 'prvkey', $hostkey['prvkey']);
+	}
 
 	$invite_result = check_account_invite($invite_code);
 	if($invite_result['error']) {
@@ -180,7 +182,6 @@ function create_account($arr) {
 		dbesc($roles),
 		dbesc($expires),
 		dbesc($default_service_class)
-
 	);
 	if(! $r) {
 		logger('create_account: DB INSERT failed.');
@@ -195,7 +196,7 @@ function create_account($arr) {
 	if($r && count($r)) {
 		$result['account'] = $r[0];
 	}
-	else {	
+	else {
 		logger('create_account: could not retrieve newly created account');
 	}
 
@@ -215,8 +216,8 @@ function create_account($arr) {
 	$result['success']  = true;
 	$result['email']    = $email;
 	$result['password'] = $password;
-	return $result;
 
+	return $result;
 }
 
 
@@ -255,7 +256,6 @@ function verify_email_address($arr) {
 		logger('send_reg_approval_email: failed to ' . $admin['email'] . 'account_id: ' . $arr['account']['account_id']);
 
 	return $res;
-
 }
 
 
@@ -292,7 +292,6 @@ function send_reg_approval_email($arr) {
 
 	$details = (($ip) ? $ip . ' [' . gethostbyaddr($ip) . ']' : '[unknown or stealth IP]');
 
-
 	$delivered = 0;
 
 	foreach($admins as $admin) {
@@ -346,11 +345,14 @@ function send_verification_email($email,$password) {
 	return($res ? true : false);
 }
 
-
+/**
+ * @brief Allows a user registration.
+ *
+ * @param string $hash
+ * @return array|boolean
+ */
 function user_allow($hash) {
 
-	$a = get_app();
-
 	$ret = array('success' => false);
 
 	$register = q("SELECT * FROM `register` WHERE `hash` = '%s' LIMIT 1",
@@ -363,7 +365,7 @@ function user_allow($hash) {
 	$account = q("SELECT * FROM account WHERE account_id = %d LIMIT 1",
 		intval($register[0]['uid'])
 	);
-	
+
 	if(! $account)
 		return $ret;
 
@@ -381,7 +383,7 @@ function user_allow($hash) {
 		intval(ACCOUNT_PENDING),
 		intval($register[0]['uid'])
 	);
-	
+
 	push_lang($register[0]['language']);
 
 	$email_tpl = get_intltext_template("register_open_eml.tpl");
@@ -402,18 +404,23 @@ function user_allow($hash) {
 
 	pop_lang();
 
-	if($res) {
+	if ($res) {
 		info( t('Account approved.') . EOL );
 		return true;
-	}	
-
+	}
 }
 
 
-// This does not have to go through user_remove() and save the nickname
-// permanently against re-registration, as the person was not yet
-// allowed to have friends on this system
-
+/**
+ * @brief Denies a user registration.
+ *
+ * This does not have to go through user_remove() and save the nickname
+ * permanently against re-registration, as the person was not yet
+ * allowed to have friends on this system
+ *
+ * @param string $hash
+ * @return boolean
+ */
 function user_deny($hash) {
 
 	$register = q("SELECT * FROM register WHERE hash = '%s' LIMIT 1",
@@ -426,7 +433,7 @@ function user_deny($hash) {
 	$account = q("SELECT account_id, account_email FROM account WHERE account_id = %d LIMIT 1",
 		intval($register[0]['uid'])
 	);
-	
+
 	if(! $account)
 		return false;
 
@@ -438,15 +445,14 @@ function user_deny($hash) {
 		dbesc($register[0]['id'])
 	);
 	notice( sprintf(t('Registration revoked for %s'), $account[0]['account_email']) . EOL);
+
 	return true;
-	
+
 }
 
 
 function user_approve($hash) {
 
-	$a = get_app();
-
 	$ret = array('success' => false);
 
 	$register = q("SELECT * FROM `register` WHERE `hash` = '%s' and password = 'verify' LIMIT 1",
@@ -459,7 +465,7 @@ function user_approve($hash) {
 	$account = q("SELECT * FROM account WHERE account_id = %d LIMIT 1",
 		intval($register[0]['uid'])
 	);
-	
+
 	if(! $account)
 		return $ret;
 
@@ -482,21 +488,16 @@ function user_approve($hash) {
 		intval(ACCOUNT_UNVERIFIED),
 		intval($register[0]['uid'])
 	);
-	
+
 	info( t('Account verified. Please login.') . EOL );
 
 	return true;
-
 }
 
 
-
-
-
-
 /**
- * @function downgrade_accounts()
- *    Checks for accounts that have past their expiration date.
+ * @brief Checks for accounts that have past their expiration date.
+ *
  * If the account has a service class which is not the site default, 
  * the service class is reset to the site default and expiration reset to never.
  * If the account has no service class it is expired and subsequently disabled.
@@ -506,8 +507,6 @@ function user_approve($hash) {
  * not the job of this function, but this can be implemented by plugin if desired. 
  * Default behaviour is to stop allowing additional resources to be consumed. 
  */
- 
-
 function downgrade_accounts() {
 
 	$r = q("select * from account where not ( account_flags & %d )>0 
@@ -604,7 +603,7 @@ function service_class_allows($uid, $property, $usage = false) {
  *
  * @param int $aid The account_id to check
  * @param string $property The service class property to check for
- * @param int|boolean $usage, (optional) The value to check against
+ * @param int|boolean $usage (optional) The value to check against
  * @return boolean
  */
 function account_service_class_allows($aid, $property, $usage = false) {
diff --git a/include/attach.php b/include/attach.php
index 2ca302949..560313d8b 100644
--- a/include/attach.php
+++ b/include/attach.php
@@ -1,10 +1,10 @@
 <?php
-
-/** @file
+/**
+ * @file include/attach.php
  *
  * @brief File/attach API with the potential for revision control.
  *
- * TODO: a filesystem storage abstraction which maintains security (and 'data' contains a system filename
+ * @TODO: a filesystem storage abstraction which maintains security (and 'data' contains a system filename
  * which is inaccessible from the web). This could get around PHP storage limits and store videos and larger
  * items, using fread or OS methods or native code to read/write or chunk it through.
  * Also an 'append' option to the storage function might be a useful addition. 
@@ -15,10 +15,10 @@ require_once('include/security.php');
 
 /**
  * @brief Guess the mimetype from file ending.
- * 
+ *
  * This function takes a file name and guess the mimetype from the
  * filename extension.
- * 
+ *
  * @param $filename a string filename
  * @return string The mimetype according to a file ending.
  */
@@ -117,23 +117,22 @@ function z_mime_content_type($filename) {
 
 /**
  * @brief Count files/attachments.
- * 
- * 
- * @param $channel_id
- * @param $observer
- * @param $hash (optional)
- * @param $filename (optional)
- * @param $filetype (optional)
- * @return array
- * 	$ret['success'] boolean
- * 	$ret['results'] amount of found results, or false
- * 	$ret['message'] string with error messages if any
+ *
+ * @param int $channel_id
+ * @param string $observer
+ * @param string $hash (optional)
+ * @param string $filename (optional)
+ * @param string $filetype (optional)
+ * @return assoziative array with:
+ *  * \e boolean \b success
+ *  * \e int|boolean \b results amount of found results, or false
+ *  * \e string \b message with error messages if any
  */
 function attach_count_files($channel_id, $observer, $hash = '', $filename = '', $filetype = '') {
 
 	$ret = array('success' => false);
 
-	if(! perm_is_allowed($channel_id,$observer, 'read_storage')) {
+	if(! perm_is_allowed($channel_id, $observer, 'read_storage')) {
 		$ret['message'] = t('Permission denied.');
 		return $ret;
 	}
@@ -219,8 +218,9 @@ function attach_list_files($channel_id, $observer, $hash = '', $filename = '', $
  * 
  * This could exhaust memory so most useful only when immediately sending the data.
  * 
- * @param $hash
- * @param $rev
+ * @param string $hash
+ * @param int $rev Revision
+ * @return array
  */
 function attach_by_hash($hash, $rev = 0) {
 
@@ -234,7 +234,6 @@ function attach_by_hash($hash, $rev = 0) {
 	elseif($rev)
 		$sql_extra = " and revision = " . intval($rev) . " ";
 
-
 	$r = q("SELECT uid FROM attach WHERE hash = '%s' $sql_extra LIMIT 1",
 		dbesc($hash)
 	);
@@ -270,9 +269,9 @@ function attach_by_hash($hash, $rev = 0) {
 
 /**
  * @brief Find an attachment by hash and revision.
- * 
+ *
  * Returns the entire attach structure excluding data.
- * 
+ *
  * @see attach_by_hash()
  * @param $hash
  * @param $rev revision default 0
@@ -561,7 +560,7 @@ function z_readdir($channel_id, $observer_hash, $pathname, $parent_hash = '') {
 	}
 	else
 		$paths = array($pathname);
-	
+
 	$r = q("select id, aid, uid, hash, creator, filename, filetype, filesize, revision, folder, flags, created, edited, allow_cid, allow_gid, deny_cid, deny_gid from attach where id = %d and folder = '%s' and filename = '%s' and (flags & %d )>0 " . permissions_sql($channel_id),
 		intval($channel_id),
 		dbesc($parent_hash),
@@ -579,24 +578,22 @@ function z_readdir($channel_id, $observer_hash, $pathname, $parent_hash = '') {
 }
 
 /**
- * @function attach_mkdir($channel,$observer_hash,$arr);
- *
  * @brief Create directory.
  *
  * @param array $channel channel array of owner
  * @param string $observer_hash hash of current observer
  * @param array $arr parameter array to fulfil request
- * Required:
- *    $arr['filename']
- *    $arr['folder'] // hash of parent directory, empty string for root directory
- * Optional:
- *    $arr['hash']  // precumputed hash for this node
- *    $arr['allow_cid']
- *    $arr['allow_gid']
- *    $arr['deny_cid']
- *    $arr['deny_gid']
+ * - Required:
+ *  * \e string \b filename
+ *  * \e string \b folder hash of parent directory, empty string for root directory
+ * - Optional:
+ *  * \e string \b hash precumputed hash for this node
+ *  * \e tring  \b allow_cid
+ *  * \e string \b allow_gid
+ *  * \e string \b deny_cid
+ *  * \e string \b deny_gid
+ * @return array
  */
-
 function attach_mkdir($channel, $observer_hash, $arr = null) {
 
 	$ret = array('success' => false);
@@ -720,13 +717,13 @@ function attach_mkdir($channel, $observer_hash, $arr = null) {
 /**
  * @brief Changes permissions of a file.
  * 
- * @param $channel_id
- * @param $resource
- * @param $allow_cid
- * @param $allow_gid
- * @param $deny_cid
- * @param $deny_gid
- * @param $recurse
+ * @param int $channel_id
+ * @param array $resource
+ * @param string $allow_cid
+ * @param string $allow_gid
+ * @param string $deny_cid
+ * @param string $deny_gid
+ * @param boolean $recurse (optional) default false
  */
 function attach_change_permissions($channel_id, $resource, $allow_cid, $allow_gid, $deny_cid, $deny_gid, $recurse = false) {
 
@@ -836,7 +833,6 @@ function attach_delete($channel_id, $resource) {
 	);
 
 	file_activity($channel_id, $object, $object['allow_cid'], $object['allow_gid'], $object['deny_cid'], $object['deny_gid'], 'update', $no_activity=false);
-
 }
 
 /**
@@ -844,8 +840,8 @@ function attach_delete($channel_id, $resource) {
  *
  * @warning This function cannot be used with mod/dav as it always returns a
  * path valid under mod/cloud.
- * 
- * @param array assoziative array with:
+ *
+ * @param array $arr assoziative array with:
  *  * \e int \b uid the channel's uid
  *  * \e string \b folder
  *  * \e string \b filename
@@ -973,20 +969,21 @@ function pipe_streams($in, $out) {
 	$size = 0;
 	while (!feof($in))
 		$size += fwrite($out, fread($in, 8192));
+
 	return $size;
 }
 
 /**
- * @brief Activity for files
+ * @brief Activity for files.
  *
- * @param $channel_id
- * @param $object
- * @param $allow_cid
- * @param $allow_gid
- * @param $deny_cid
- * @param $deny_gid
- * @param $verb
- * @param $no_activity
+ * @param int $channel_id
+ * @param array $object
+ * @param string $allow_cid
+ * @param string $allow_gid
+ * @param string $deny_cid
+ * @param string $deny_gid
+ * @param string $verb
+ * @param boolean $no_activity
  */
 function file_activity($channel_id, $object, $allow_cid, $allow_gid, $deny_cid, $deny_gid, $verb, $no_activity) {
 
@@ -1028,7 +1025,6 @@ function file_activity($channel_id, $object, $allow_cid, $allow_gid, $deny_cid,
 
 		//filter out receivers which do not have permission to view filestorage
 		$arr_allow_cid = check_list_permissions($channel_id, $arr_allow_cid, 'view_storage');
-
 	}
 
 	$mid = item_message_id();
@@ -1109,7 +1105,6 @@ function file_activity($channel_id, $object, $allow_cid, $allow_gid, $deny_cid,
 		$update = false;
 
 		//notice( t('File activity updated') . EOL);
-
 	}
 
 	if($no_activity) {
@@ -1152,15 +1147,14 @@ function file_activity($channel_id, $object, $allow_cid, $allow_gid, $deny_cid,
 	//(($verb === 'post') ?  notice( t('File activity posted') . EOL) : notice( t('File activity dropped') . EOL));
 
 	return;
-
 }
 
 /**
  * @brief Create file activity object
  *
- * @param $channel_id
- * @param $hash
- * @param $cloudpath
+ * @param int $channel_id
+ * @param string $hash
+ * @param string $cloudpath
  */
 function get_file_activity_object($channel_id, $hash, $cloudpath) {
 
@@ -1199,8 +1193,8 @@ function get_file_activity_object($channel_id, $hash, $cloudpath) {
 		'deny_cid'	=> $x[0]['deny_cid'],
 		'deny_gid'	=> $x[0]['deny_gid']
 	);
-	return $object;
 
+	return $object;
 }
 
 /**
diff --git a/include/comanche.php b/include/comanche.php
index 71ffe99b8..62bfd0ddc 100644
--- a/include/comanche.php
+++ b/include/comanche.php
@@ -101,7 +101,7 @@ function comanche_parser(&$a, $s, $pass = 0) {
 }
 
 
-function comanche_menu($name,$class = '') {
+function comanche_menu($name, $class = '') {
 	$channel_id = comanche_get_channel_id();
 	if($channel_id) {
 		$m = menu_fetch($name,$channel_id, get_observer_hash());
@@ -111,20 +111,23 @@ function comanche_menu($name,$class = '') {
 
 function comanche_replace_region($match) {
 	$a = get_app();
-	if(array_key_exists($match[1], $a->page)) {
+	if (array_key_exists($match[1], $a->page)) {
 		return $a->page[$match[1]];
 	}
 }
 
 /**
- * @function comanche_get_channel_id()
- *    Returns the channel_id of the profile owner of the page, or the local_channel if there is no profile owner.
- * Otherwise returns 0
- */ 
-
+ * @brief Returns the channel_id of the profile owner of the page.
+ *
+ * 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
+ */
 function comanche_get_channel_id() {
 	$channel_id = ((is_array(get_app()->profile)) ? get_app()->profile['profile_uid'] : 0);
-	if((! $channel_id) && (local_channel()))
+
+	if ((! $channel_id) && (local_channel()))
 		$channel_id = local_channel();
 
 	return $channel_id;
@@ -173,23 +176,26 @@ function comanche_webpage(&$a,$s) {
 }
 
 
-// Widgets will have to get any operational arguments from the session,
-// the global app environment, or config storage until we implement argument passing
-
-
+/**
+ * Widgets will have to get any operational arguments from the session, the
+ * global app environment, or config storage until we implement argument passing
+ *
+ * @param string $name
+ * @param string $text
+ */
 function comanche_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) {
+	if ($cnt) {
+		foreach ($matches as $mtch) {
 			$vars[$mtch[1]] = $mtch[2];
 		}
 	}
 
 	$func = 'widget_' . trim($name);
-	if(function_exists($func))
+	if (function_exists($func))
 		return $func($vars);
 }
 
diff --git a/include/config.php b/include/config.php
index b459e2c7d..c94d25eb8 100644
--- a/include/config.php
+++ b/include/config.php
@@ -3,8 +3,7 @@
  * @file include/config.php
  * @brief Arbitrary configuration storage.
  *
- * Note:
- * Please do not store booleans - convert to 0/1 integer values
+ * @note Please do not store booleans - convert to 0/1 integer values.
  * The get_?config() functions return boolean false for keys that are unset,
  * and this could lead to subtle bugs.
  *
@@ -18,19 +17,20 @@
  * - <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 $var = get_pconfig(local_channel(), 'category', 'key');@endcode
+ * @code{.php} $var = get_pconfig(local_channel(), 'category', 'key');@endcode
  * - <b>xconfig</b> is the same as pconfig, except that it uses <i>xchan</i> as
  * an identifier. This is for example for people who do not have a local account.
  * The storage is of size MEDIUMTEXT.
- * @code $observer = $a->get_observer_hash();
+ * @code{.php}
+ * $observer = $a->get_observer_hash();
  * if ($observer) {
  *     $var = get_xconfig($observer, 'category', 'key');
  * }@endcode
  *
  * - get_config() and set_config() can also be done through the command line tool
- * @ref util/config
+ * @ref util/config.md "util/config"
  * - get_pconfig() and set_pconfig() can also be done through the command line tool
- * @ref util/pconfig and takes a channel_id as first argument. 
+ * @ref util/pconfig.md "util/pconfig" and takes a channel_id as first argument. 
  *
  */
 
@@ -123,7 +123,7 @@ function get_config_from_storage($family, $key) {
  *
  * Stores a config value ($value) in the category ($family) under the key ($key).
  *
- * Please do not store booleans - convert to 0/1 integer values!
+ * @note Please do not store booleans - convert to 0/1 integer values!
  *
  * @param string $family
  *  The category of the configuration value
@@ -272,14 +272,16 @@ function get_pconfig($uid, $family, $key, $instore = false) {
  * Stores a config value ($value) in the category ($family) under the key ($key)
  * for the channel_id $uid.
  *
- * Please do not store booleans - convert to 0/1 integer values!
+ * @note Please do not store booleans - convert to 0/1 integer values!
  *
  * @param string $uid
  *  The channel_id
  * @param string $family
  *  The category of the configuration value
  * @param string $key
- *  The configuration key to query
+ *  The configuration key to set
+ * @param string $value
+ *  The value to store
  * @return mixed Stored $value or false
  */
 function set_pconfig($uid, $family, $key, $value) {
@@ -315,6 +317,7 @@ function set_pconfig($uid, $family, $key, $value) {
 		);
 		if($ret)
 			return $value;
+
 		return $ret;
 	}
 
@@ -339,6 +342,7 @@ function set_pconfig($uid, $family, $key, $value) {
 
 	if($ret)
 		return $value;
+
 	return $ret;
 }
 
@@ -360,13 +364,14 @@ function del_pconfig($uid, $family, $key) {
 	global $a;
 	$ret = false;
 
-	if(x($a->config[$uid][$family], $key))
+	if (x($a->config[$uid][$family], $key))
 		unset($a->config[$uid][$family][$key]);
 		$ret = q("DELETE FROM pconfig WHERE uid = %d AND cat = '%s' AND k = '%s'",
 		intval($uid),
 		dbesc($family),
 		dbesc($key)
 	);
+
 	return $ret;
 }
 
@@ -448,7 +453,7 @@ function get_xconfig($xchan, $family, $key) {
  * Stores a config value ($value) in the category ($family) under the key ($key)
  * for the observer's $xchan hash.
  *
- * Please do not store booleans - convert to 0/1 integer values!
+ * @note Please do not store booleans - convert to 0/1 integer values!
  *
  * @param string $xchan
  *  The observer's hash
@@ -456,6 +461,8 @@ function get_xconfig($xchan, $family, $key) {
  *  The category of the configuration value
  * @param string $key
  *  The configuration key to set
+ * @param string $value
+ *  The value to store
  * @return mixed Stored $value or false
  */
 function set_xconfig($xchan, $family, $key, $value) {
diff --git a/include/conversation.php b/include/conversation.php
index 4018ced28..042d01b3e 100644
--- a/include/conversation.php
+++ b/include/conversation.php
@@ -1044,7 +1044,6 @@ function builtin_activity_puller($item, &$conv_responses) {
 			return;
 		}
 	}
-
 }
 
 
@@ -1053,7 +1052,7 @@ function builtin_activity_puller($item, &$conv_responses) {
  *
  * @param int $cnt number of people who like/dislike the item
  * @param array $arr array of pre-linked names of likers/dislikers
- * @param string $typ eone of 'like, 'dislike'
+ * @param string $type one of 'like, 'dislike'
  * @param int $id item id
  * @return string formatted text
  */
@@ -1146,7 +1145,6 @@ function status_editor($a, $x, $popup = false) {
 		'$expireswhen' => t('Expires YYYY-MM-DD HH:MM')
 	));
 
-
 	$tpl = get_markup_template('jot.tpl');
 
 	$jotplugins = '';
@@ -1461,8 +1459,8 @@ function network_tabs() {
 
 	if ($no_active=='active' && x($_GET,'order')) {
 		switch($_GET['order']){
-		 case 'post': $postord_active = 'active'; $no_active=''; break;
-		 case 'comment' : $all_active = 'active'; $no_active=''; break;
+			case 'post': $postord_active = 'active'; $no_active=''; break;
+			case 'comment' : $all_active = 'active'; $no_active=''; break;
 		}
 	}
 
diff --git a/include/datetime.php b/include/datetime.php
index 5cab5889d..b0167edb2 100644
--- a/include/datetime.php
+++ b/include/datetime.php
@@ -1,54 +1,71 @@
-<?php /** @file */
-
-// two-level sort for timezones.
+<?php
+/**
+ * @file include/datetime.php
+ * @brief Some functions for date and time related tasks.
+ */
 
 
+/**
+ * @brief Two-level sort for timezones.
+ *
+ * @param string $a
+ * @param string $b
+ * @return number
+ */
 function timezone_cmp($a, $b) {
 	if(strstr($a,'/') && strstr($b,'/')) {
 		if ( t($a) == t($b)) return 0;
 		return ( t($a) < t($b)) ? -1 : 1;
 	}
-	if(strstr($a,'/')) return -1;
-	if(strstr($b,'/')) return  1;
+	if (strstr($a,'/')) return -1;
+	if (strstr($b,'/')) return  1;
 	if ( t($a) == t($b)) return 0;
+
 	return ( t($a) < t($b)) ? -1 : 1;
 }
 
-// Return timezones grouped (primarily) by continent
+/**
+ * @brief Return timezones grouped (primarily) by continent.
+ *
+ * @return array
+ */
 function get_timezones( ){
 	$timezone_identifiers = DateTimeZone::listIdentifiers();
 
 	usort($timezone_identifiers, 'timezone_cmp');
 	$continent = '';
 	$continents = array();
-	foreach($timezone_identifiers as $value) {
+	foreach ($timezone_identifiers as $value) {
 		$ex = explode("/", $value);
-		if(count($ex) > 1) {
+		if (count($ex) > 1) {
 			$continent = t($ex[0]);
-			if(count($ex) > 2)
-				$city = substr($value,strpos($value,'/')+1);
+			if (count($ex) > 2)
+				$city = substr($value, strpos($value, '/')+1);
 			else
 				$city = $ex[1];
-		}
-		else {
+		} else {
 			$city = $ex[0];
 			$continent = t('Miscellaneous');
 		}
 		$city = str_replace('_', ' ',  t($city));
 
-		if(!x($continents,$ex[0])) $continents[$ex[0]] = array();
+		if (!x($continents, $ex[0])) $continents[$ex[0]] = array();
 		$continents[$continent][$value] = $city;
 	}
+
 	return $continents;
 }
 
-// General purpose date parse/convert function.
-// $from = source timezone
-// $to   = dest timezone
-// $s    = some parseable date/time string
-// $fmt  = output format
-
-
+/**
+ * @brief General purpose date parse/convert function.
+ *
+ * @param string $from source timezone
+ * @param string $to dest timezone
+ * @param string $s some parseable date/time string
+ * @param string $fmt output format recognised from php's DateTime class
+ *   http://www.php.net/manual/en/datetime.format.php
+ * @return string
+ */
 function datetime_convert($from = 'UTC', $to = 'UTC', $s = 'now', $fmt = "Y-m-d H:i:s") {
 
 	// Defaults to UTC if nothing is set, but throws an exception if set to empty string.
@@ -68,44 +85,46 @@ function datetime_convert($from = 'UTC', $to = 'UTC', $s = 'now', $fmt = "Y-m-d
 
 	if(substr($s,0,10) == '0000-00-00') {
 		$d = new DateTime($s . ' + 32 days', new DateTimeZone('UTC'));
-		return str_replace('1','0',$d->format($fmt));
+		return str_replace('1', '0', $d->format($fmt));
 	}
 
 	try {
 		$from_obj = new DateTimeZone($from);
-	}
-	catch(Exception $e) {
+	} catch(Exception $e) {
 		$from_obj = new DateTimeZone('UTC');
 	}
 
 	try {
 		$d = new DateTime($s, $from_obj);
-	}
-	catch(Exception $e) {
+	} catch(Exception $e) {
 		logger('datetime_convert: exception: ' . $e->getMessage());
 		$d = new DateTime('now', $from_obj);
 	}
 
 	try {
 		$to_obj = new DateTimeZone($to);
-	}
-	catch(Exception $e) {
+	} catch(Exception $e) {
 		$to_obj = new DateTimeZone('UTC');
 	}
 
 	$d->setTimeZone($to_obj);
+
 	return($d->format($fmt));
 }
 
-// wrapper for date selector, tailored for use in birthday fields
-
+/**
+ * @brief Wrapper for date selector, tailored for use in birthday fields.
+ *
+ * @param string $dob Date of Birth
+ * @return string
+ */
 function dob($dob) {
-	list($year,$month,$day) = sscanf($dob,'%4d-%2d-%2d');
-	$f = get_config('system','birthday_input_format');
-	if(! $f)
+	list($year, $month, $day) = sscanf($dob, '%4d-%2d-%2d');
+	$f = get_config('system', 'birthday_input_format');
+	if (! $f)
 		$f = 'ymd';
 
-	if($dob === '0000-00-00')
+	if ($dob === '0000-00-00')
 		$value = '';
 	else
 		$value = (($year) ? datetime_convert('UTC','UTC',$dob,'Y-m-d') : datetime_convert('UTC','UTC',$dob,'m-d'));
@@ -120,7 +139,6 @@ function dob($dob) {
 	return $o;
 }
 
-
 /**
  * returns a date selector
  * @param $format
@@ -135,7 +153,7 @@ function dob($dob) {
  *  id and name of datetimepicker (defaults to "datetimepicker")
  */
 function datesel($format, $min, $max, $default, $id = 'datepicker') {
-	return datetimesel($format,$min,$max,$default,$id,true,false, '','');
+	return datetimesel($format, $min, $max, $default, $id,true, false, '', '');
 }
 
 /**
@@ -154,7 +172,8 @@ function timesel($format, $h, $m, $id='timepicker') {
 }
 
 /**
- * returns a datetime selector
+ * @brief Returns a datetime selector.
+ *
  * @param $format
  *  format string, e.g. 'ymd' or 'mdy'. Not currently supported
  * @param $min
@@ -163,23 +182,25 @@ function timesel($format, $h, $m, $id='timepicker') {
  *  unix timestap of maximum date
  * @param $default
  *  unix timestamp of default date
- * @param $id
+ * @param string $id
  *  id and name of datetimepicker (defaults to "datetimepicker")
- * @param $pickdate
+ * @param boolean $pickdate
  *  true to show date picker (default)
- * @param $picktime
+ * @param boolean $picktime
  *  true to show time picker (default)
  * @param $minfrom
  *  set minimum date from picker with id $minfrom (none by default)
  * @param $maxfrom
  *  set maximum date from picker with id $maxfrom (none by default)
+ * @param boolean $required default false
+ * @return string Parsed HTML output.
+ * 
+ * @todo Once browser support is better this could probably be replaced with
+ * native HTML5 date picker.
  */
-function datetimesel($format, $min, $max, $default, $id = 'datetimepicker', $pickdate = true, $picktime = true, $minfrom = '', $maxfrom = '',$required = false) {
+function datetimesel($format, $min, $max, $default, $id = 'datetimepicker', $pickdate = true, $picktime = true, $minfrom = '', $maxfrom = '', $required = false) {
 
-
-	// Once browser support is better this could probably be replaced with native HTML5 date picker
 	$o = '';
-
 	$dateformat = '';
 
 	if($pickdate) $dateformat .= 'Y-m-d';
@@ -188,7 +209,7 @@ function datetimesel($format, $min, $max, $default, $id = 'datetimepicker', $pic
 
 	$minjs = $min ? ",minDate: new Date({$min->getTimestamp()}*1000), yearStart: " . $min->format('Y') : '';
 	$maxjs = $max ? ",maxDate: new Date({$max->getTimestamp()}*1000), yearEnd: " . $max->format('Y') : '';
-	
+
 	$input_text = $default ? 'value="' . date($dateformat, $default->getTimestamp()) . '"' : '';
 	$defaultdatejs = $default ? ",defaultDate: new Date({$default->getTimestamp()}*1000)" : '';
 
@@ -214,31 +235,39 @@ function datetimesel($format, $min, $max, $default, $id = 'datetimepicker', $pic
 	$o .= (($required) ? '<span class="required" title="' . t('Required') . '" >*</span>' : '');
 	$o .= '</div>';
 	$o .= "<script type='text/javascript'>\$(function () {var picker = \$('#$id').datetimepicker({step:5,format:'$dateformat' $minjs $maxjs $pickers $defaultdatejs}); $extra_js})</script>";
+
 	return $o;
 }
 
-// implements "3 seconds ago" etc.
-// based on $posted_date, (UTC).
-// Results relative to current timezone
-// Limited to range of timestamps
-
-
-function relative_date($posted_date,$format = null) {
+/**
+ * @brief Returns a relative date string.
+ *
+ * Implements "3 seconds ago" etc.
+ * Based on $posted_date, (UTC).
+ * Results relative to current timezone.
+ * Limited to range of timestamps.
+ *
+ * @param string $posted_date
+ * @param string $format (optional) parsed with sprintf()
+ *    <tt>%1$d %2$s ago</tt>, e.g. 22 hours ago, 1 minute ago
+ * @return string with relative date
+ */
+function relative_date($posted_date, $format = null) {
 
-	$localtime = datetime_convert('UTC',date_default_timezone_get(),$posted_date); 
+	$localtime = datetime_convert('UTC', date_default_timezone_get(), $posted_date); 
 
 	$abs = strtotime($localtime);
-    
-    if (is_null($posted_date) || $posted_date === NULL_DATE || $abs === False) {
-		 return t('never');
+
+	if (is_null($posted_date) || $posted_date === NULL_DATE || $abs === false) {
+		return t('never');
 	}
 
 	$etime = time() - $abs;
-    
+
 	if ($etime < 1) {
 		return t('less than a second ago');
 	}
-    
+
 	$a = array( 12 * 30 * 24 * 60 * 60  =>  array( t('year'),   t('years')),
 				30 * 24 * 60 * 60       =>  array( t('month'),  t('months')),
 				7  * 24 * 60 * 60       =>  array( t('week'),   t('weeks')),
@@ -247,231 +276,256 @@ function relative_date($posted_date,$format = null) {
 				60                      =>  array( t('minute'), t('minutes')),
 				1                       =>  array( t('second'), t('seconds'))
 	);
-    
+
 	foreach ($a as $secs => $str) {
 		$d = $etime / $secs;
 		if ($d >= 1) {
 			$r = round($d);
-			// translators - e.g. 22 hours ago, 1 minute ago
-			if(! $format)
-				$format = t('%1$d %2$s ago');
-			return sprintf( $format,$r, (($r == 1) ? $str[0] : $str[1]));
-        }
-    }
-}
-
+			if (! $format)
+				$format = t('%1$d %2$s ago', 'e.g. 22 hours ago, 1 minute ago');
 
+			return sprintf($format, $r, (($r == 1) ? $str[0] : $str[1]));
+		}
+	}
+}
 
-// Returns age in years, given a date of birth,
-// the timezone of the person whose date of birth is provided,
-// and the timezone of the person viewing the result.
-// Why? Bear with me. Let's say I live in Mittagong, Australia, and my 
-// birthday is on New Year's. You live in San Bruno, California.
-// When exactly are you going to see my age increase?
-// A: 5:00 AM Dec 31 San Bruno time. That's precisely when I start 
-// celebrating and become a year older. If you wish me happy birthday 
-// on January 1 (San Bruno time), you'll be a day late. 
-   
-function age($dob,$owner_tz = '',$viewer_tz = '') {
-	if(! intval($dob))
+/**
+ * @brief Returns timezone correct age in years.
+ *
+ * Returns the age in years, given a date of birth, the timezone of the person
+ * whose date of birth is provided, and the timezone of the person viewing the
+ * result.
+ *
+ * Why? Bear with me. Let's say I live in Mittagong, Australia, and my birthday
+ * is on New Year's. You live in San Bruno, California.
+ * When exactly are you going to see my age increase?
+ *
+ * A: 5:00 AM Dec 31 San Bruno time. That's precisely when I start celebrating
+ * and become a year older. If you wish me happy birthday on January 1
+ * (San Bruno time), you'll be a day late.
+ *
+ * @param string $dob Date of Birth
+ * @param string $owner_tz (optional) timezone of the person of interest
+ * @param string $viewer_tz (optional) timezone of the person viewing
+ * @return number
+ */
+function age($dob, $owner_tz = '', $viewer_tz = '') {
+	if (! intval($dob))
 		return 0;
-	if(! $owner_tz)
+	if (! $owner_tz)
 		$owner_tz = date_default_timezone_get();
-	if(! $viewer_tz)
+	if (! $viewer_tz)
 		$viewer_tz = date_default_timezone_get();
 
-	$birthdate = datetime_convert('UTC',$owner_tz,$dob . ' 00:00:00+00:00','Y-m-d');
-	list($year,$month,$day) = explode("-",$birthdate);
-	$year_diff  = datetime_convert('UTC',$viewer_tz,'now','Y') - $year;
-	$curr_month = datetime_convert('UTC',$viewer_tz,'now','m');
-	$curr_day   = datetime_convert('UTC',$viewer_tz,'now','d');
+	$birthdate = datetime_convert('UTC', $owner_tz, $dob . ' 00:00:00+00:00','Y-m-d');
+	list($year,$month,$day) = explode("-", $birthdate);
+	$year_diff  = datetime_convert('UTC', $viewer_tz, 'now', 'Y') - $year;
+	$curr_month = datetime_convert('UTC', $viewer_tz, 'now', 'm');
+	$curr_day   = datetime_convert('UTC', $viewer_tz, 'now', 'd');
 
-	if(($curr_month < $month) || (($curr_month == $month) && ($curr_day < $day)))
+	if (($curr_month < $month) || (($curr_month == $month) && ($curr_day < $day)))
 		$year_diff--;
+
 	return $year_diff;
 }
 
+/**
+ * @brief Get days of a month in a given year.
+ *
+ * Returns number of days in the month of the given year.
+ * $m = 1 is 'January' to match human usage.
+ *
+ * @param int $y year
+ * @param int $m month (1=January, 12=December)
+ * @return int number of days in the given month
+ */
+function get_dim($y, $m) {
+	$dim = array( 0,
+			31, 28, 31, 30, 31, 30,
+			31, 31, 30, 31, 30, 31
+	);
 
+	if ($m != 2)
+		return $dim[$m];
 
-// Get days in month
-// get_dim($year, $month);
-// returns number of days.
-// $month[1] = 'January'; 
-//   to match human usage.
-
-
-function get_dim($y,$m) {
+	if (((($y % 4) == 0) && (($y % 100) != 0)) || (($y % 400) == 0))
+		return 29;
 
-  $dim = array( 0,
-    31, 28, 31, 30, 31, 30,
-    31, 31, 30, 31, 30, 31);
- 
-  if($m != 2)
-    return $dim[$m];
-  if(((($y % 4) == 0) && (($y % 100) != 0)) || (($y % 400) == 0))
-    return 29;
-  return $dim[2];
+	return $dim[2];
 }
 
+/**
+ * @brief Returns the first day in month for a given month, year.
+ *
+ * Months start at 1.
+ *
+ * @param int $y Year
+ * @param int $m Month (1=January, 12=December)
+ * @return day 0 = Sunday through 6 = Saturday
+ */
+function get_first_dim($y, $m) {
+	$d = sprintf('%04d-%02d-01 00:00', intval($y), intval($m));
 
-// Returns the first day in month for a given month, year
-// get_first_dim($year,$month)
-// returns 0 = Sunday through 6 = Saturday
-// Months start at 1.
-
-
-function get_first_dim($y,$m) {
-  $d = sprintf('%04d-%02d-01 00:00', intval($y), intval($m));
-  return datetime_convert('UTC','UTC',$d,'w');
+	return datetime_convert('UTC', 'UTC', $d, 'w');
 }
 
-// output a calendar for the given month, year.
-// if $links are provided (array), e.g. $links[12] => 'http://mylink' , 
-// date 12 will be linked appropriately. Today's date is also noted by 
-// altering td class.
-// Months count from 1.
-
-
-// TODO: provide (prev,next) links, define class variations for different size calendars
-
-function cal($y = 0,$m = 0, $links = false, $class='') {
-
+/**
+ * @brief Output a calendar for the given month, year.
+ *
+ * If $links are provided (array), e.g. $links[12] => 'http://mylink' ,
+ * date 12 will be linked appropriately. Today's date is also noted by
+ * altering td class.
+ * Months count from 1.
+ *
+ * @param number $y Year
+ * @param number $m Month
+ * @param string $links (default false)
+ * @param string $class
+ * @return string
+ *
+ * @todo provide (prev,next) links, define class variations for different size calendars
+ */
+function cal($y = 0, $m = 0, $links = false, $class='') {
 
 	// month table - start at 1 to match human usage.
 
 	$mtab = array(' ',
-	  'January','February','March',
-	  'April','May','June',
-	  'July','August','September',
-	  'October','November','December'
-	); 
+		'January','February','March',
+		'April','May','June',
+		'July','August','September',
+		'October','November','December'
+	);
 
 	$thisyear = datetime_convert('UTC',date_default_timezone_get(),'now','Y');
 	$thismonth = datetime_convert('UTC',date_default_timezone_get(),'now','m');
-	if(! $y)
+	if (! $y)
 		$y = $thisyear;
-	if(! $m)
+	if (! $m)
 		$m = intval($thismonth);
 
-  $dn = array('Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday');
-  $f = get_first_dim($y,$m);
-  $l = get_dim($y,$m);
-  $d = 1;
-  $dow = 0;
-  $started = false;
+	$dn = array('Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday');
+	$f = get_first_dim($y, $m);
+	$l = get_dim($y, $m);
+	$d = 1;
+	$dow = 0;
+	$started = false;
 
-  if(($y == $thisyear) && ($m == $thismonth))
-    $tddate = intval(datetime_convert('UTC',date_default_timezone_get(),'now','j'));
+	if (($y == $thisyear) && ($m == $thismonth))
+		$tddate = intval(datetime_convert('UTC',date_default_timezone_get(),'now','j'));
 
 	$str_month = day_translate($mtab[$m]);
-  $o = '<table class="calendar' . $class . '">';
-  $o .= "<caption>$str_month $y</caption><tr>";
-  for($a = 0; $a < 7; $a ++)
-     $o .= '<th>' . mb_substr(day_translate($dn[$a]),0,3,'UTF-8') . '</th>';
-  $o .= '</tr><tr>';
-
-  while($d <= $l) {
-    if(($dow == $f) && (! $started))
-      $started = true;
-    $today = (((isset($tddate)) && ($tddate == $d)) ? "class=\"today\" " : '');
-    $o .= "<td $today>";
-	$day = str_replace(' ','&nbsp;',sprintf('%2.2d', $d));
-    if($started) {
-      if(is_array($links) && isset($links[$d]))
-        $o .=  "<a href=\"{$links[$d]}\">$day</a>";
-      else
-        $o .= $day;
-      $d ++;
-    }
-    else
-      $o .= '&nbsp;';
-    $o .= '</td>';
-    $dow ++;
-    if(($dow == 7) && ($d <= $l)) {
-      $dow = 0;
-      $o .= '</tr><tr>';
-    }
-  }
-  if($dow)
-    for($a = $dow; $a < 7; $a ++)
-       $o .= '<td>&nbsp;</td>';
-  $o .= '</tr></table>'."\r\n";  
-  
-  return $o;
-}
+	$o = '<table class="calendar' . $class . '">';
+	$o .= "<caption>$str_month $y</caption><tr>";
+	for ($a = 0; $a < 7; $a ++)
+		$o .= '<th>' . mb_substr(day_translate($dn[$a]),0,3,'UTF-8') . '</th>';
+
+	$o .= '</tr><tr>';
+
+	while ($d <= $l) {
+		if (($dow == $f) && (! $started))
+			$started = true;
+
+		$today = (((isset($tddate)) && ($tddate == $d)) ? "class=\"today\" " : '');
+		$o .= "<td $today>";
+		$day = str_replace(' ','&nbsp;',sprintf('%2.2d', $d));
+		if ($started) {
+			if (is_array($links) && isset($links[$d]))
+				$o .=  "<a href=\"{$links[$d]}\">$day</a>";
+			else
+				$o .= $day;
+
+			$d ++;
+		} else {
+			$o .= '&nbsp;';
+		}
+
+		$o .= '</td>';
+		$dow ++;
+		if (($dow == 7) && ($d <= $l)) {
+			$dow = 0;
+			$o .= '</tr><tr>';
+		}
+	}
+	if ($dow)
+		for ($a = $dow; $a < 7; $a ++)
+			$o .= '<td>&nbsp;</td>';
+
+	$o .= '</tr></table>'."\r\n";
 
+	return $o;
+}
 
 /**
- * Return the next birthday, converted from the owner's timezone to UTC. 
+ * @brief Return the next birthday, converted from the owner's timezone to UTC.
+ * 
  * This makes it globally portable.
  * If the provided birthday lacks a month and or day, return an empty string.
  * A missing year is acceptable.
+ *
+ * @param string $dob Date of Birth
+ * @param string $tz Timezone
+ * @param string $format
+ * @return string
  */
+function z_birthday($dob, $tz, $format="Y-m-d H:i:s") {
 
-
-function z_birthday($dob,$tz,$format="Y-m-d H:i:s") {
-
-	if(! strlen($tz))
+	if (! strlen($tz))
 		$tz = 'UTC';
 
 	$birthday = '';
 	$tmp_dob = substr($dob,5);
 	$tmp_d = substr($dob,8);
-	if(intval($tmp_dob) && intval($tmp_d)) {
+	if (intval($tmp_dob) && intval($tmp_d)) {
 		$y = datetime_convert($tz,$tz,'now','Y');
 		$bd = $y . '-' . $tmp_dob . ' 00:00';
 		$t_dob = strtotime($bd);
 		$now = strtotime(datetime_convert($tz,$tz,'now'));
-		if($t_dob < $now)
+		if ($t_dob < $now)
 			$bd = $y + 1 . '-' . $tmp_dob . ' 00:00';
+
 		$birthday = datetime_convert($tz,'UTC',$bd,$format);
 	}
 
 	return $birthday;
-
 }
 
 /**
+ * @brief Create a birthday event for any connections with a birthday in the next 1-2 weeks.
  *
- * Create a birthday event for any connections with a birthday in the next 1-2 weeks.
  * Update the year so that we don't create another event until next year.
- *
  */
-
-
 function update_birthdays() {
 
 	require_once('include/event.php');
 	require_once('include/permissions.php');
 
-    $r = q("SELECT * FROM abook left join xchan on abook_xchan = xchan_hash 
+	$r = q("SELECT * FROM abook left join xchan on abook_xchan = xchan_hash 
 		WHERE abook_dob > %s + interval %s and abook_dob < %s + interval %s",
 		db_utcnow(), db_quoteinterval('7 day'),
 		db_utcnow(), db_quoteinterval('14 day')
-		);
-	if($r) {
-		foreach($r as $rr) {
-			
-			if(! perm_is_allowed($rr['abook_channel'],$rr['xchan_hash'],'send_stream'))
+	);
+	if ($r) {
+		foreach ($r as $rr) {
+			if (! perm_is_allowed($rr['abook_channel'], $rr['xchan_hash'], 'send_stream'))
 				continue;
 
 			$ev = array();
 			$ev['uid'] = $rr['abook_channel'];
 			$ev['account'] = $rr['abook_account'];
 			$ev['event_xchan'] = $rr['xchan_hash'];
-			$ev['start'] = datetime_convert('UTC','UTC', $rr['abook_dob']);
-			$ev['finish'] = datetime_convert('UTC','UTC', $rr['abook_dob'] . ' + 1 day ');
+			$ev['start'] = datetime_convert('UTC', 'UTC', $rr['abook_dob']);
+			$ev['finish'] = datetime_convert('UTC', 'UTC', $rr['abook_dob'] . ' + 1 day ');
 			$ev['adjust'] = 1;
-            $ev['summary'] = sprintf( t('%1$s\'s birthday'), $rr['xchan_name']);
-            $ev['description'] = sprintf( t('Happy Birthday %1$s'), 
+			$ev['summary'] = sprintf( t('%1$s\'s birthday'), $rr['xchan_name']);
+			$ev['description'] = sprintf( t('Happy Birthday %1$s'), 
 				'[zrl=' . $rr['xchan_url'] . ']' . $rr['xchan_name'] . '[/zrl]') ;
 			$ev['type'] = 'birthday';
-			
+
 			$z = event_store_event($ev);
-			if($z) {
-				$item_id = event_store_item($ev,$z);
+			if ($z) {
+				$item_id = event_store_item($ev, $z);
 				q("update abook set abook_dob = '%s' where abook_id = %d",
-					dbesc(intval($rr['abook_dob']) + 1 . substr($rr['abook_dob'],4)),
+					dbesc(intval($rr['abook_dob']) + 1 . substr($rr['abook_dob'], 4)),
 					intval($rr['abook_id'])
 				);
 			}
diff --git a/include/dir_fns.php b/include/dir_fns.php
index 4c6c40f15..d1e26b637 100644
--- a/include/dir_fns.php
+++ b/include/dir_fns.php
@@ -1,14 +1,23 @@
-<?php /** @file */
+<?php
+/**
+ * @file include/dir_fns.php
+ */
 
 require_once('include/permissions.php');
 
+/**
+ * @brief
+ *
+ * @param int $dirmode
+ * @return array
+ */
 function find_upstream_directory($dirmode) {
 	global $DIRECTORY_FALLBACK_SERVERS;
 
 	$preferred = get_config('system','directory_server');
-	if(! $preferred) {
+	if (! $preferred) {
 
-		/**
+		/*
 		 * No directory has yet been set. For most sites, pick one at random
 		 * from our list of directory servers. However, if we're a directory
 		 * server ourself, point at the local instance
@@ -18,41 +27,40 @@ function find_upstream_directory($dirmode) {
 		 */
 
 		$dirmode = intval(get_config('system','directory_mode'));
-		if($dirmode == DIRECTORY_MODE_NORMAL) {
+		if ($dirmode == DIRECTORY_MODE_NORMAL) {
 			$toss = mt_rand(0,count($DIRECTORY_FALLBACK_SERVERS));
 			$preferred = $DIRECTORY_FALLBACK_SERVERS[$toss];
 			set_config('system','directory_server',$preferred);
-		}
-		else{
+		} else{
 			set_config('system','directory_server',z_root());
 		}
 	}
+
 	return array('url' => $preferred);
 }
 
+/**
+ * Directories may come and go over time. We will need to check that our
+ * directory server is still valid occasionally, and reset to something that
+ * is if our directory has gone offline for any reason
+ */
 function check_upstream_directory() {
 
-	/**
-	* Directories may come and go over time.  We will need to check that our 
-	* directory server is still valid occasionally, and reset to something that
-	* is if our directory has gone offline for any reason
-	*/
-
-	$directory = get_config('system','directory_server');
+	$directory = get_config('system', 'directory_server');
 
 	// it's possible there is no directory server configured and the local hub is being used.
 	// If so, default to preserving the absence of a specific server setting.
 
-	$isadir = true; 
+	$isadir = true;
 
-	if($directory) {
+	if ($directory) {
 		$h = parse_url($directory);
-		if($h) {
+		if ($h) {
 			$x = zot_finger('[system]@' . $h['host']);
-			if($x['success']) {
-				$j = json_decode($x['body'],true);
-				if(array_key_exists('site',$j) && array_key_exists('directory_mode',$j['site'])) {
-					if($j['site']['directory_mode'] === 'normal') {
+			if ($x['success']) {
+				$j = json_decode($x['body'], true);
+				if (array_key_exists('site', $j) && array_key_exists('directory_mode', $j['site'])) {
+					if ($j['site']['directory_mode'] === 'normal') {
 						$isadir = false;
 					}
 				}
@@ -60,9 +68,8 @@ function check_upstream_directory() {
 		}
 	}
 
-	if(! $isadir)
-		set_config('system','directory_server','');
-	return;
+	if (! $isadir)
+		set_config('system', 'directory_server', '');
 }
 
 function get_globaldir_setting($observer) {
@@ -95,12 +102,8 @@ function get_safemode_setting($observer) {
 }
 
 /**
- * @function dir_sort_links()
- * Called by the directory_sort widget
+ * @brief Called by the directory_sort widget.
  */
-
-
-	
 function dir_sort_links() {
 
 	$safe_mode = 1;
@@ -110,7 +113,7 @@ function dir_sort_links() {
 	$safe_mode = get_safemode_setting($observer);
 	$globaldir = get_globaldir_setting($observer);
 
- 	// Build urls without order and pubforums so it's easy to tack on the changed value
+	// Build urls without order and pubforums so it's easy to tack on the changed value
 	// Probably there's an easier way to do this
 
 	$current_order = (($_REQUEST['order']) ? $_REQUEST['order'] : 'date');
@@ -145,38 +148,34 @@ function dir_sort_links() {
 		'$pubforums' => array('pubforums', t('Public Forums Only'),(x($_REQUEST,'pubforums') ? $_REQUEST['pubforums'] : ''),'','',' onchange=\'window.location.href="' . $forumsurl . '&pubforums="+(this.checked ? 1 : 0)\''), 
 		'$globaldir' => array('globaldir', t('This Website Only'), 1-intval($globaldir),'','',' onchange=\'window.location.href="' . $forumsurl . '&global="+(this.checked ? 0 : 1)\''),
 	));
+
 	return $o;
 }
 
-
 /**
- * @function sync_directories($mode)
- * 
- * @param int $mode;
+ * @brief Checks the directory mode of this hub.
  *
  * Checks the directory mode of this hub to see if it is some form of directory server. If it is,
  * get the directory realm of this hub. Fetch a list of all other directory servers in this realm and request
  * a directory sync packet. This will contain both directory updates and new ratings. Store these all in the DB. 
  * In the case of updates, we will query each of them asynchronously from a poller task. Ratings are stored 
- * directly if the rater's signature matches.  
+ * directly if the rater's signature matches.
  *
+ * @param int $dirmode;
  */
-
-
 function sync_directories($dirmode) {
 
-	if($dirmode == DIRECTORY_MODE_STANDALONE || $dirmode == DIRECTORY_MODE_NORMAL)
+	if ($dirmode == DIRECTORY_MODE_STANDALONE || $dirmode == DIRECTORY_MODE_NORMAL)
 		return;
 
 	$realm = get_directory_realm();
-	if($realm == DIRECTORY_REALM) {
+	if ($realm == DIRECTORY_REALM) {
 		$r = q("select * from site where (site_flags & %d) > 0 and site_url != '%s' and ( site_realm = '%s' or site_realm = '') ",
 			intval(DIRECTORY_MODE_PRIMARY|DIRECTORY_MODE_SECONDARY),
 			dbesc(z_root()),
 			dbesc($realm)
 		);
-	}
-	else {
+	} else {
 		$r = q("select * from site where (site_flags & %d) > 0 and site_url != '%s' and site_realm like '%s' ",
 			intval(DIRECTORY_MODE_PRIMARY|DIRECTORY_MODE_SECONDARY),
 			dbesc(z_root()),
@@ -185,9 +184,9 @@ function sync_directories($dirmode) {
 	}
 
 	// If there are no directory servers, setup the fallback master
-	// FIXME - what to do if we're in a different realm?
+	/** @FIXME What to do if we're in a different realm? */
 
-	if((! $r) && (z_root() != DIRECTORY_FALLBACK_MASTER)) {
+	if ((! $r) && (z_root() != DIRECTORY_FALLBACK_MASTER)) {
 		$r = array();
 		$r[] = array(
 			'site_url' => DIRECTORY_FALLBACK_MASTER,
@@ -211,32 +210,30 @@ function sync_directories($dirmode) {
 			intval(DIRECTORY_MODE_PRIMARY|DIRECTORY_MODE_SECONDARY),
 			dbesc(z_root())
 		);
-
-	} 
-	if(! $r)
+	}
+	if (! $r)
 		return;
 
-	foreach($r as $rr) {
-		if(! $rr['site_directory'])
+	foreach ($r as $rr) {
+		if (! $rr['site_directory'])
 			continue;
 
 		logger('sync directories: ' . $rr['site_directory']);
 
 		// for brand new directory servers, only load the last couple of days.
 		// It will take about a month for a new directory to obtain the full current repertoire of channels.
-		// FIXME - go back and pick up earlier ratings if this is a new directory server. These do not get refreshed.
+		/** @FIXME Go back and pick up earlier ratings if this is a new directory server. These do not get refreshed. */
 
 		$token = get_config('system','realm_token');
 
-
 		$syncdate = (($rr['site_sync'] === NULL_DATE) ? datetime_convert('UTC','UTC','now - 2 days') : $rr['site_sync']);
 		$x = z_fetch_url($rr['site_directory'] . '?f=&sync=' . urlencode($syncdate) . (($token) ? '&t=' . $token : ''));
 
-		if(! $x['success'])
+		if (! $x['success'])
 			continue;
 
 		$j = json_decode($x['body'],true);
-		if(!($j['transactions']) || ($j['ratings']))
+		if (!($j['transactions']) || ($j['ratings']))
 			continue;
 
 		q("update site set site_sync = '%s' where site_url = '%s'",
@@ -246,17 +243,18 @@ function sync_directories($dirmode) {
 
 		logger('sync_directories: ' . $rr['site_url'] . ': ' . print_r($j,true), LOGGER_DATA);
 
-		if(is_array($j['transactions']) && count($j['transactions'])) {
-			foreach($j['transactions'] as $t) {
+		if (is_array($j['transactions']) && count($j['transactions'])) {
+			foreach ($j['transactions'] as $t) {
 				$r = q("select * from updates where ud_guid = '%s' limit 1",
 					dbesc($t['transaction_id'])
 				);
 				if($r)
 					continue;
+
 				$ud_flags = 0;
-				if(is_array($t['flags']) && in_array('deleted',$t['flags']))
+				if (is_array($t['flags']) && in_array('deleted',$t['flags']))
 					$ud_flags |= UPDATE_FLAGS_DELETED;
-				if(is_array($t['flags']) && in_array('forced',$t['flags']))
+				if (is_array($t['flags']) && in_array('forced',$t['flags']))
 					$ud_flags |= UPDATE_FLAGS_FORCED;
 
 				$z = q("insert into updates ( ud_hash, ud_guid, ud_date, ud_flags, ud_addr )
@@ -269,42 +267,41 @@ function sync_directories($dirmode) {
 				);
 			}
 		}
-		if(is_array($j['ratings']) && count($j['ratings'])) {
-			foreach($j['ratings'] as $rr) {		
+		if (is_array($j['ratings']) && count($j['ratings'])) {
+			foreach ($j['ratings'] as $rr) {
 				$x = q("select * from xlink where xlink_xchan = '%s' and xlink_link = '%s' and xlink_static = 1",
 					dbesc($rr['channel']),
 					dbesc($rr['target'])
 				);
-				if($x && $x[0]['xlink_updated'] >= $rr['edited'])
+				if ($x && $x[0]['xlink_updated'] >= $rr['edited'])
 					continue;
 
 				// Ratings are signed by the rater. We need to verify before we can accept it.
-				// TODO - queue or defer if the xchan is not yet present on our site
+				/** @TODO Queue or defer if the xchan is not yet present on our site */
 
 				$y = q("select xchan_pubkey from xchan where xchan_hash = '%s' limit 1",
 					dbesc($rr['channel'])
 				);
-				if(! $y) {
+				if (! $y) {
 					logger('key unavailable on this site for ' . $rr['channel']);
 					continue;
 				}
-				if(! rsa_verify($rr['target'] . '.' . $rr['rating'] . '.' . $rr['rating_text'], base64url_decode($rr['signature']),$y[0]['xchan_pubkey'])) {
-			        logger('failed to verify rating');
+				if (! rsa_verify($rr['target'] . '.' . $rr['rating'] . '.' . $rr['rating_text'], base64url_decode($rr['signature']),$y[0]['xchan_pubkey'])) {
+					logger('failed to verify rating');
 					continue;
 				}
 
-				if($x) {
+				if ($x) {
 					$z = q("update xlink set xlink_rating = %d, xlink_rating_text = '%s', xlink_sig = '%s', xlink_updated = '%s' where xlink_id = %d",
 						intval($rr['rating']),
 						dbesc($rr['rating_text']),
 						dbesc($rr['signature']),
 						dbesc(datetime_convert()),
 						intval($x[0]['xlink_id'])
-	        		);
-			        logger('rating updated');
-    			}
-    			else {
-        			$z = q("insert into xlink ( xlink_xchan, xlink_link, xlink_rating, xlink_rating_text, xlink_sig, xlink_updated, xlink_static ) values( '%s', '%s', %d, '%s', '%s', '%s', 1 ) ",
+					);
+					logger('rating updated');
+				} else {
+					$z = q("insert into xlink ( xlink_xchan, xlink_link, xlink_rating, xlink_rating_text, xlink_sig, xlink_updated, xlink_static ) values( '%s', '%s', %d, '%s', '%s', '%s', 1 ) ",
 						dbesc($rr['channel']),
 						dbesc($rr['target']),
 						intval($rr['rating']),
@@ -321,50 +318,51 @@ function sync_directories($dirmode) {
 
 
 /**
- * $function update_directory_entry($ud)
+ * @brief
  *
- * @param array $ud; // Entry from update table
- * Given an update record, probe the channel, grab a zot-info packet and refresh/sync the data  
+ * Given an update record, probe the channel, grab a zot-info packet and refresh/sync the data.
  *
- * Ignore updating records marked as deleted
+ * Ignore updating records marked as deleted.
  *
- * If successful, 
- *   sets ud_last in the DB to the current datetime for this reddress/webbie
+ * If successful, sets ud_last in the DB to the current datetime for this
+ * reddress/webbie.
+ *
+ * @param array $ud Entry from update table
  */
-
 function update_directory_entry($ud) {
 
 	logger('update_directory_entry: ' . print_r($ud,true), LOGGER_DATA);
 
-	if($ud['ud_addr'] && (! ($ud['ud_flags'] & UPDATE_FLAGS_DELETED))) {
+	if ($ud['ud_addr'] && (! ($ud['ud_flags'] & UPDATE_FLAGS_DELETED))) {
 		$success = false;
-		$x = zot_finger($ud['ud_addr'],'');
-		if($x['success']) {
-			$j = json_decode($x['body'],true);
-			if($j)
+		$x = zot_finger($ud['ud_addr'], '');
+		if ($x['success']) {
+			$j = json_decode($x['body'], true);
+			if ($j)
 				$success = true;
-			$y = import_xchan($j,0,$ud);
+
+			$y = import_xchan($j, 0, $ud);
 		}
-		if(! $success) {
-			$r = q("update updates set ud_last = '%s' where ud_addr = '%s'",
+		if (! $success) {
+			q("update updates set ud_last = '%s' where ud_addr = '%s'",
 				dbesc(datetime_convert()),
 				dbesc($ud['ud_addr'])
 			);
 		}
 	}
-
 }
 
 
 /**
- * @function local_dir_update($uid,$force)
- *     push local channel updates to a local directory server
- *  This is called from include/directory.php if a profile is to be pushed
- *  to the directory and the local hub in this case is any kind of directory server. 
+ * @brief Push local channel updates to a local directory server.
  *
+ * This is called from include/directory.php if a profile is to be pushed to the
+ * directory and the local hub in this case is any kind of directory server.
+ *
+ * @param int $uid
+ * @param boolean $force
  */
-
-function local_dir_update($uid,$force) {
+function local_dir_update($uid, $force) {
 
 	logger('local_dir_update: uid: ' . $uid, LOGGER_DEBUG);
 
@@ -375,12 +373,12 @@ function local_dir_update($uid,$force) {
 	$profile = array();
 	$profile['encoding'] = 'zot';
 
-	if($p) {
+	if ($p) {
 		$hash = $p[0]['channel_hash'];
 
 		$profile['description'] = $p[0]['pdesc'];
 		$profile['birthday']    = $p[0]['dob'];
-		if($age = age($p[0]['dob'],$p[0]['channel_timezone'],''))  
+		if ($age = age($p[0]['dob'],$p[0]['channel_timezone'],''))  
 			$profile['age'] = $age;
 
 		$profile['gender']      = $p[0]['gender'];
@@ -394,14 +392,15 @@ function local_dir_update($uid,$force) {
 		$profile['homepage']    = $p[0]['homepage'];
 		$profile['hometown']    = $p[0]['hometown'];
 
-		if($p[0]['keywords']) {
+		if ($p[0]['keywords']) {
 			$tags = array();
-			$k = explode(' ',$p[0]['keywords']);
-			if($k)
-				foreach($k as $kk)
-					if(trim($kk))
+			$k = explode(' ', $p[0]['keywords']);
+			if ($k)
+				foreach ($k as $kk)
+					if (trim($kk))
 						$tags[] = trim($kk);
-			if($tags)
+
+			if ($tags)
 				$profile['keywords'] = $tags;
 		}
 
@@ -414,26 +413,23 @@ function local_dir_update($uid,$force) {
 		);
 
 		// Be careful - XCHAN_FLAGS_HIDDEN should evaluate to 1
-		if(($r[0]['xchan_flags'] & XCHAN_FLAGS_HIDDEN) != $hidden)
+		if (($r[0]['xchan_flags'] & XCHAN_FLAGS_HIDDEN) != $hidden)
 			$new_flags = $r[0]['xchan_flags'] ^ XCHAN_FLAGS_HIDDEN;
 		else
 			$new_flags = $r[0]['xchan_flags'];
-		
-		if($new_flags != $r[0]['xchan_flags']) {			
 
+		if ($new_flags != $r[0]['xchan_flags']) {
 			$r = q("update xchan set xchan_flags = %d  where xchan_hash = '%s'",
 				intval($new_flags),
 				dbesc($p[0]['channel_hash'])
 			);
-
 		}
 
 		$address = $p[0]['channel_address'] . '@' . get_app()->get_hostname();
 
-		if(perm_is_allowed($uid,'','view_profile')) {
-			import_directory_profile($hash,$profile,$address,0);
-		}
-		else {
+		if (perm_is_allowed($uid, '', 'view_profile')) {
+			import_directory_profile($hash, $profile, $address, 0);
+		} else {
 			// they may have made it private
 			$r = q("delete from xprof where xprof_hash = '%s'",
 				dbesc($hash)
@@ -445,7 +441,5 @@ function local_dir_update($uid,$force) {
 	}
 
 	$ud_hash = random_string() . '@' . get_app()->get_hostname();
-	update_modtime($hash,$ud_hash,$p[0]['channel_address'] . '@' . get_app()->get_hostname(),(($force) ? UPDATE_FLAGS_FORCED : UPDATE_FLAGS_UPDATED));
-
+	update_modtime($hash, $ud_hash, $p[0]['channel_address'] . '@' . get_app()->get_hostname(),(($force) ? UPDATE_FLAGS_FORCED : UPDATE_FLAGS_UPDATED));
 }
-	
diff --git a/include/directory.php b/include/directory.php
index 801d4ec8e..9ab1d805b 100644
--- a/include/directory.php
+++ b/include/directory.php
@@ -1,14 +1,23 @@
-<?php /** @file */
+<?php
+/**
+ * @file include/directory.php
+ * @brief executes directory_run()
+ */
 
 require_once('boot.php');
 require_once('include/zot.php');
 require_once('include/cli_startup.php');
 require_once('include/dir_fns.php');
 
-
+/**
+ * @brief
+ *
+ * @param array $argv
+ * @param array $argc
+ */
 function directory_run($argv, $argc){
 
-	cli_startup();		 
+	cli_startup();
 
 	if($argc < 2)
 		return;
@@ -37,7 +46,6 @@ function directory_run($argv, $argc){
 
 	$channel = $x[0];
 
-
 	if($dirmode != DIRECTORY_MODE_NORMAL) {
 
 		// this is an in-memory update and we don't need to send a network packet.
@@ -70,8 +78,9 @@ function directory_run($argv, $argc){
 
 	if(! $z['success']) {
 
-		// FIXME - we aren't updating channel_dirdate if we have to queue
-		// the directory packet. That means we'll try again on the next poll run.
+		/** @FIXME we aren't updating channel_dirdate if we have to queue
+		 * the directory packet. That means we'll try again on the next poll run.
+		 */
 
 		$hash = random_string();
 		q("insert into outq ( outq_hash, outq_account, outq_channel, outq_driver, outq_posturl, outq_async, outq_created, outq_updated, outq_notify, outq_msg ) 
@@ -87,8 +96,7 @@ function directory_run($argv, $argc){
 			dbesc($packet),
 			dbesc('')
 		);
-	}
-	else {
+	} else {
 		q("update channel set channel_dirdate = '%s' where channel_id = %d",
 			dbesc(datetime_convert()),
 			intval($channel['channel_id'])
@@ -101,7 +109,7 @@ function directory_run($argv, $argc){
 
 }
 
-if (array_search(__file__,get_included_files())===0){
-  directory_run($argv,$argc);
-  killme();
+if (array_search(__file__, get_included_files()) === 0) {
+	directory_run($argv, $argc);
+	killme();
 }
diff --git a/include/enotify.php b/include/enotify.php
index 36d457c10..e801c3100 100644
--- a/include/enotify.php
+++ b/include/enotify.php
@@ -1,33 +1,50 @@
-<?php /** @file */
-
+<?php
+/**
+ * @file include/enotify.php
+ *
+ * @brief File with functions and a class for email notifications.
+ */
+
+/**
+ * @brief
+ *
+ * @param array $params an assoziative array with:
+ *  * \e string \b from_xchan sender xchan hash
+ *  * \e string \b to_xchan recipient xchan hash
+ *  * \e array \b item an assoziative array
+ *  * \e int \b type one of the NOTIFY_* constants from boot.php
+ *  * \e string \b link
+ *  * \e string \b parent_mid
+ *  * \e string \b otype
+ *  * \e string \b verb
+ *  * \e string \b activity
+ */
 function notification($params) {
 
 	logger('notification: entry', LOGGER_DEBUG);
 
 	// throw a small amount of entropy into the system to breakup duplicates arriving at the same precise instant.
-	usleep(mt_rand(0,10000));
-	
+	usleep(mt_rand(0, 10000));
 
 	$a = get_app();
 
 
-	if($params['from_xchan']) {
+	if ($params['from_xchan']) {
 		$x = q("select * from xchan where xchan_hash = '%s' limit 1",
 			dbesc($params['from_xchan'])
 		);
 	}
-	if($params['to_xchan']) {
+	if ($params['to_xchan']) {
 		$y = q("select channel.*, account.* from channel left join account on channel_account_id = account_id
 			where channel_hash = '%s' and not (channel_pageflags & %d)>0 limit 1",
 			dbesc($params['to_xchan']),
 			intval(PAGE_REMOVED)
 		);
 	}
-	if($x & $y) {
+	if ($x & $y) {
 		$sender = $x[0];
 		$recip = $y[0];
-	}
-	else {
+	} else {
 		logger('notification: no sender or recipient.');
 		logger('sender: ' . $params['from_xchan']);
 		logger('recip: ' . $params['to_xchan']);
@@ -55,10 +72,10 @@ function notification($params) {
 
 	$additional_mail_header = "";
 
-	if(array_key_exists('item',$params)) {
+	if (array_key_exists('item', $params)) {
 		require_once('include/conversation.php');
 		// if it's a normal item...
-		if(array_key_exists('verb',$params['item'])) {
+		if (array_key_exists('verb', $params['item'])) {
 			// localize_item() alters the original item so make a copy first
 			$i = $params['item'];
 			logger('calling localize');
@@ -66,13 +83,11 @@ function notification($params) {
 			$title = $i['title'];
 			$body = $i['body'];
 			$private = (($i['item_private']) || ($i['item_flags'] & ITEM_OBSCURED));
-		}
-		else {
+		} else {
 			$title = $params['item']['title'];
 			$body = $params['item']['body'];
 		}
-	}
-	else {
+	} else {
 		$title = $body = '';
 	}
 
@@ -80,7 +95,7 @@ function notification($params) {
 	// e.g. "your post", "David's photo", etc.
 	$possess_desc = t('%s <!item_type!>');
 
-	if($params['type'] == NOTIFY_MAIL) {
+	if ($params['type'] == NOTIFY_MAIL) {
 		logger('notification: mail');
 		$subject = 	sprintf( t('[Red:Notify] New mail received at %s'),$sitename);
 
@@ -92,28 +107,27 @@ function notification($params) {
 		$itemlink = $siteurl . '/mail/' . $params['item']['id'];
 	}
 
-	if($params['type'] == NOTIFY_COMMENT) {
+	if ($params['type'] == NOTIFY_COMMENT) {
 //		logger("notification: params = " . print_r($params, true), LOGGER_DEBUG);
 
 		$itemlink =  $params['link'];
 
-
 		// ignore like/unlike activity on posts - they probably require a sepearate notification preference
 
-		if(array_key_exists('item',$params) && (! visible_activity($params['item'])))
+		if (array_key_exists('item',$params) && (! visible_activity($params['item'])))
 			return;
 
 		$parent_mid = $params['parent_mid'];
 
 		// Check to see if there was already a notify for this post.
 		// If so don't create a second notification
-		
+
 		$p = null;
 		$p = q("select id from notify where link = '%s' and uid = %d limit 1",
 			dbesc($params['link']),
 			intval($recip['channel_id'])
 		);
-		if($p) {
+		if ($p) {
 			logger('notification: comment already notified');
 			pop_lang();
 			return;
@@ -182,26 +196,26 @@ function notification($params) {
 		$subject = sprintf( t('[Red:Notify] %s posted to your profile wall') , $sender['xchan_name']);
 
 		$preamble = sprintf( t('%1$s, %2$s posted to your profile wall at %3$s') , $recip['channel_name'], $sender['xchan_name'], $sitename);
-		
+
 		$epreamble = sprintf( t('%1$s, %2$s posted to [zrl=%3$s]your wall[/zrl]') ,
 			$recip['channel_name'], 
 			'[zrl=' . $sender['xchan_url'] . ']' . $sender['xchan_name'] . '[/zrl]',
 			$params['link']); 
-		
+
 		$sitelink = t('Please visit %s to view and/or reply to the conversation.');
 		$tsitelink = sprintf( $sitelink, $siteurl );
 		$hsitelink = sprintf( $sitelink, '<a href="' . $siteurl . '">' . $sitename . '</a>');
 		$itemlink =  $params['link'];
 	}
 
-	if($params['type'] == NOTIFY_TAGSELF) {
+	if ($params['type'] == NOTIFY_TAGSELF) {
 
 		$p = null;
 		$p = q("select id from notify where link = '%s' and uid = %d limit 1",
 			dbesc($params['link']),
 			intval($recip['channel_id'])
 		);
-		if($p) {
+		if ($p) {
 			logger('enotify: tag: already notified about this post');
 			pop_lang();
 			return;
@@ -220,8 +234,7 @@ function notification($params) {
 		$itemlink =  $params['link'];
 	}
 
-	if($params['type'] == NOTIFY_POKE) {
-
+	if ($params['type'] == NOTIFY_POKE) {
 		$subject =	sprintf( t('[Red:Notify] %1$s poked you') , $sender['xchan_name']);
 		$preamble = sprintf( t('%1$s, %2$s poked you at %3$s') , $recip['channel_name'], $sender['xchan_name'], $sitename);
 		$epreamble = sprintf( t('%1$s, %2$s [zrl=%2$s]poked you[/zrl].') ,
@@ -239,7 +252,7 @@ function notification($params) {
 		$itemlink =  $params['link'];
 	}
 
-	if($params['type'] == NOTIFY_TAGSHARE) {
+	if ($params['type'] == NOTIFY_TAGSHARE) {
 		$subject =	sprintf( t('[Red:Notify] %s tagged your post') , $sender['xchan_name']);
 		$preamble = sprintf( t('%1$s, %2$s tagged your post at %3$s') , $recip['channel_name'],$sender['xchan_name'], $sitename);
 		$epreamble = sprintf( t('%1$s, %2$s tagged [zrl=%3$s]your post[/zrl]') ,
@@ -253,7 +266,7 @@ function notification($params) {
 		$itemlink =  $params['link'];
 	}
 
-	if($params['type'] == NOTIFY_INTRO) {
+	if ($params['type'] == NOTIFY_INTRO) {
 		$subject = sprintf( t('[Red:Notify] Introduction received'));
 		$preamble = sprintf( t('%1$s, you\'ve received an new connection request from \'%2$s\' at %3$s'), $recip['channel_name'], $sender['xchan_name'], $sitename); 
 		$epreamble = sprintf( t('%1$s, you\'ve received [zrl=%2$s]a new connection request[/zrl] from %3$s.'),
@@ -268,7 +281,7 @@ function notification($params) {
 		$itemlink =  $params['link'];
 	}
 
-	if($params['type'] == NOTIFY_SUGGEST) {
+	if ($params['type'] == NOTIFY_SUGGEST) {
 		$subject = sprintf( t('[Red:Notify] Friend suggestion received'));
 		$preamble = sprintf( t('%1$s, you\'ve received a friend suggestion from \'%2$s\' at %3$s'), $recip['channel_name'], $sender['xchan_name'], $sitename); 
 		$epreamble = sprintf( t('%1$s, you\'ve received [zrl=%2$s]a friend suggestion[/zrl] for %3$s from %4$s.'),
@@ -276,7 +289,7 @@ function notification($params) {
 			$itemlink,
 			'[zrl=' . $params['item']['url'] . ']' . $params['item']['name'] . '[/zrl]',
 			'[zrl=' . $sender['xchan_url'] . ']' . $sender['xchan_name'] . '[/zrl]'); 
-									
+
 		$body = t('Name:') . ' ' . $params['item']['name'] . "\n";
 		$body .= t('Photo:') . ' ' . $params['item']['photo'] . "\n";
 		$body .= sprintf( t('You may visit their profile at %s'),$params['item']['url']);
@@ -287,27 +300,27 @@ function notification($params) {
 		$itemlink =  $params['link'];
 	}
 
-	if($params['type'] == NOTIFY_CONFIRM) {
-
+	if ($params['type'] == NOTIFY_CONFIRM) {
+		// ?
 	}
 
-	if($params['type'] == NOTIFY_SYSTEM) {
-		
+	if ($params['type'] == NOTIFY_SYSTEM) {
+		// ?
 	}
 
 	$h = array(
-		'params'    => $params, 
+		'params'    => $params,
 		'subject'   => $subject,
-		'preamble'  => $preamble, 
-		'epreamble' => $epreamble, 
-		'body'      => $body, 
+		'preamble'  => $preamble,
+		'epreamble' => $epreamble,
+		'body'      => $body,
 		'sitelink'  => $sitelink,
 		'tsitelink' => $tsitelink,
 		'hsitelink' => $hsitelink,
 		'itemlink'  => $itemlink
 	);
-		
-	call_hooks('enotify',$h);
+
+	call_hooks('enotify', $h);
 
 	$subject   = $h['subject'];
 	$preamble  = $h['preamble'];
@@ -319,16 +332,16 @@ function notification($params) {
 	$itemlink  = $h['itemlink']; 
 
 
-	require_once('include/html2bbcode.php');	
+	require_once('include/html2bbcode.php');
 
 	do {
 		$dups = false;
 		$hash = random_string();
-        $r = q("SELECT `id` FROM `notify` WHERE `hash` = '%s' LIMIT 1",
+		$r = q("SELECT `id` FROM `notify` WHERE `hash` = '%s' LIMIT 1",
 			dbesc($hash));
-		if(count($r))
+		if (count($r))
 			$dups = true;
-	} while($dups == true);
+	} while ($dups === true);
 
 
 	$datarray = array();
@@ -348,10 +361,10 @@ function notification($params) {
  	$datarray['abort']  = false;
 
 	$datarray['item'] = $params['item'];
- 
+
 	call_hooks('enotify_store', $datarray);
 
-	if($datarray['abort']) {
+	if ($datarray['abort']) {
 		pop_lang();
 		return;
 	}
@@ -365,8 +378,8 @@ function notification($params) {
 	// So easiest solution to hide them from Notices is to mark them as seen right away.
 	// Another option would be to not add them to the DB, and change how emails are handled (probably would be better that way)
 	$always_show_in_notices = get_pconfig($recip['channel_id'],'system','always_show_in_notices');
-	if(!$always_show_in_notices) {
-		if(($params['type'] == NOTIFY_WALL) || ($params['type'] == NOTIFY_MAIL) || ($params['type'] == NOTIFY_INTRO)) {
+	if (!$always_show_in_notices) {
+		if (($params['type'] == NOTIFY_WALL) || ($params['type'] == NOTIFY_MAIL) || ($params['type'] == NOTIFY_INTRO)) {
 			$seen = 1;
 		}
 	}
@@ -392,9 +405,9 @@ function notification($params) {
 		dbesc($hash),
 		intval($recip['channel_id'])
 	);
-	if($r)
+	if ($r) {
 		$notify_id = $r[0]['id'];
-	else {
+	} else {
 		logger('notification not found.');
 		pop_lang();
 		return;
@@ -405,7 +418,7 @@ function notification($params) {
 
 	// wretched hack, but we don't want to duplicate all the preamble variations and we also don't want to screw up a translation
 
-	if(($a->language === 'en' || (! $a->language)) && strpos($msg,', '))
+	if (($a->language === 'en' || (! $a->language)) && strpos($msg,', '))
 		$msg = substr($msg,strpos($msg,', ')+1);	
 
 	$r = q("update notify set msg = '%s' where id = %d and uid = %d",
@@ -413,12 +426,11 @@ function notification($params) {
 		intval($notify_id),
 		intval($datarray['uid'])
 	);
-		
 
 	// send email notification if notification preferences permit
 
 	require_once('bbcode.php');
-	if((intval($recip['channel_notifyflags']) & intval($params['type'])) || $params['type'] == NOTIFY_SYSTEM) {
+	if ((intval($recip['channel_notifyflags']) & intval($params['type'])) || $params['type'] == NOTIFY_SYSTEM) {
 
 		logger('notification: sending notification email');
 
@@ -429,8 +441,6 @@ function notification($params) {
 			return;
 		}
 
-
-
 		$textversion = strip_tags(html_entity_decode(bbcode(stripslashes(str_replace(array("\\r", "\\n"), array( "", "\n"), $body))),ENT_QUOTES,'UTF-8'));
 
 		$htmlversion = bbcode(stripslashes(str_replace(array("\\r","\\n"), array("","<br />\n"),$body)));
@@ -450,7 +460,6 @@ function notification($params) {
 		unset($_SESSION['zid_override']);
 		unset($_SESSION['zrl_override']);
 
-
 		$datarray = array();
 		$datarray['banner']       = $banner;
 		$datarray['product']      = $product;
@@ -485,13 +494,13 @@ function notification($params) {
 
 		$private_activity = false;
 
-		if(! $datarray['email_secure']) {
-			switch($params['type']) {
+		if (! $datarray['email_secure']) {
+			switch ($params['type']) {
 				case NOTIFY_WALL:
 				case NOTIFY_TAGSELF:
 				case NOTIFY_POKE:
 				case NOTIFY_COMMENT:
-					if(! $private)
+					if (! $private)
 						break;
 					$private_activity = true;
 				case NOTIFY_MAIL:
@@ -503,11 +512,12 @@ function notification($params) {
 			}
 		}
 
-		if($private_activity 
-			&& intval(get_pconfig($datarray['uid'],'system','ignore_private_notifications'))) {
+		if ($private_activity
+			&& intval(get_pconfig($datarray['uid'], 'system', 'ignore_private_notifications'))) {
+
 			pop_lang();
 			return;
-		}		
+		}
 
 		// load the template for private message notifications
 		$tpl = get_markup_template('email_notify_html.tpl');
@@ -525,13 +535,13 @@ function notification($params) {
 			'$hitemlink'    => $datarray['hitemlink'],
 			'$thanks'       => $datarray['thanks'],
 			'$site_admin'   => $datarray['site_admin'],
-			'$title'		=> $datarray['title'],
-			'$htmlversion'	=> $datarray['htmlversion'],	
+			'$title'        => $datarray['title'],
+			'$htmlversion'  => $datarray['htmlversion'],
 		));
-		
+
 		// load the template for private message notifications
 		$tpl = get_markup_template('email_notify_text.tpl');
-		$email_text_body = replace_macros($tpl,array(
+		$email_text_body = replace_macros($tpl, array(
 			'$banner'       => $datarray['banner'],
 			'$product'      => $datarray['product'],
 			'$preamble'     => $datarray['preamble'],
@@ -545,8 +555,8 @@ function notification($params) {
 			'$titemlink'    => $datarray['titemlink'],
 			'$thanks'       => $datarray['thanks'],
 			'$site_admin'   => $datarray['site_admin'],
-			'$title'		=> $datarray['title'],
-			'$textversion'	=> $datarray['textversion'],	
+			'$title'        => $datarray['title'],
+			'$textversion'  => $datarray['textversion'],
 		));
 
 //		logger('text: ' . $email_text_body);
@@ -570,41 +580,48 @@ function notification($params) {
 }
 
 
+/**
+ * @brief A class for sending email notifications.
+ *
+ * @fixme Class names start mostly with capital letter to distinguish them easier.
+ */
 class enotify {
 	/**
-	 * Send a multipart/alternative message with Text and HTML versions
+	 * @brief Send a multipart/alternative message with Text and HTML versions.
 	 *
-	 * @param fromName			name of the sender
-	 * @param fromEmail			email fo the sender
-	 * @param replyTo			replyTo address to direct responses
-	 * @param toEmail			destination email address
-	 * @param messageSubject	subject of the message
-	 * @param htmlVersion		html version of the message
-	 * @param textVersion		text only version of the message
-	 * @param additionalMailHeader	additions to the smtp mail header
+	 * @param array $params an assoziative array with:
+	 *  * \e string \b fromName        name of the sender
+	 *  * \e string \b fromEmail       email of the sender
+	 *  * \e string \b replyTo         replyTo address to direct responses
+	 *  * \e string \b toEmail         destination email address
+	 *  * \e string \b messageSubject  subject of the message
+	 *  * \e string \b htmlVersion     html version of the message
+	 *  * \e string \b textVersion     text only version of the message
+	 *  * \e string \b additionalMailHeader  additions to the smtp mail header
 	 */
 	static public function send($params) {
 
 		$fromName = email_header_encode(html_entity_decode($params['fromName'],ENT_QUOTES,'UTF-8'),'UTF-8'); 
 		$messageSubject = email_header_encode(html_entity_decode($params['messageSubject'],ENT_QUOTES,'UTF-8'),'UTF-8');
-		
+
 		// generate a mime boundary
-		$mimeBoundary   =rand(0,9)."-"
-				.rand(10000000000,9999999999)."-"
-				.rand(10000000000,9999999999)."=:"
-				.rand(10000,99999);
+		$mimeBoundary = rand(0, 9) . "-"
+				.rand(10000000000, 9999999999) . "-"
+				.rand(10000000000, 9999999999) . "=:"
+				.rand(10000, 99999);
 
 		// generate a multipart/alternative message header
 		$messageHeader =
 			$params['additionalMailHeader'] .
-			"From: $fromName <{$params['fromEmail']}>\n" . 
+			"From: $fromName <{$params['fromEmail']}>\n" .
 			"Reply-To: $fromName <{$params['replyTo']}>\n" .
 			"MIME-Version: 1.0\n" .
 			"Content-Type: multipart/alternative; boundary=\"{$mimeBoundary}\"";
 
 		// assemble the final multipart message body with the text and html types included
-		$textBody	=	chunk_split(base64_encode($params['textVersion']));
-		$htmlBody	=	chunk_split(base64_encode($params['htmlVersion']));
+		$textBody = chunk_split(base64_encode($params['textVersion']));
+		$htmlBody = chunk_split(base64_encode($params['htmlVersion']));
+
 		$multipartMessageBody =
 			"--" . $mimeBoundary . "\n" .					// plain text section
 			"Content-Type: text/plain; charset=UTF-8\n" .
@@ -618,12 +635,11 @@ class enotify {
 
 		// send the message
 		$res = mail(
-			$params['toEmail'],	 							// send to address
+			$params['toEmail'],								// send to address
 			$messageSubject,								// subject
-			$multipartMessageBody,	 						// message body
+			$multipartMessageBody,							// message body
 			$messageHeader									// message headers
 		);
 		logger("notification: enotify::send returns " . $res, LOGGER_DEBUG);
 	}
-}
-
+}
\ No newline at end of file
diff --git a/include/expire.php b/include/expire.php
index b244e65f5..e5d456896 100644
--- a/include/expire.php
+++ b/include/expire.php
@@ -1,4 +1,7 @@
-<?php /** @file */
+<?php
+/**
+ * @file include/expire.php
+ */
 
 require_once('boot.php');
 require_once('include/cli_startup.php');
@@ -7,62 +10,60 @@ function expire_run($argv, $argc){
 
 	cli_startup();
 
-
 	// perform final cleanup on previously delete items
 
-	$r = q("select id from item where (item_restrict & %d) > 0 and (item_restrict & %d) = 0 
+	$r = q("select id from item where (item_restrict & %d) > 0 and (item_restrict & %d) = 0
 		and changed < %s - INTERVAL %s",
 		intval(ITEM_DELETED),
 		intval(ITEM_PENDING_REMOVE),
 		db_utcnow(), db_quoteinterval('10 DAY')
 	);
-	if($r) {
-		foreach($r as $rr) {
-			drop_item($rr['id'],false,DROPITEM_PHASE2);
+	if ($r) {
+		foreach ($r as $rr) {
+			drop_item($rr['id'], false, DROPITEM_PHASE2);
 		}
 	}
 
 	// physically remove anything that has been deleted for more than two months
-	// FIXME - this is a wretchedly inefficient query
+	/** @FIXME - this is a wretchedly inefficient query */
 
 	$r = q("delete from item where ( item_restrict & %d ) > 0 and changed < %s - INTERVAL %s",
 		intval(ITEM_PENDING_REMOVE),
 		db_utcnow(), db_quoteinterval('36 DAY')
 	);
 
-	// make this optional as it could have a performance impact on large sites
+	/** @FIXME make this optional as it could have a performance impact on large sites */
 
-	if(intval(get_config('system','optimize_items')))
+	if (intval(get_config('system', 'optimize_items')))
 		q("optimize table item");
 
 	logger('expire: start', LOGGER_DEBUG);
-	
+
 	$site_expire = get_config('system', 'default_expire_days');
 
 	logger('site_expire: ' . $site_expire);
 
 	$r = q("SELECT channel_id, channel_address, channel_pageflags, channel_expire_days from channel where true");
 
-	if($r) {
-		foreach($r as $rr) {
+	if ($r) {
+		foreach ($r as $rr) {
 
 			// expire the sys channel separately
-			if($rr['channel_pageflags'] & PAGE_SYSTEM)
+			if ($rr['channel_pageflags'] & PAGE_SYSTEM)
 				continue;
 
 			// service class default (if non-zero) over-rides the site default
 
-			$service_class_expire = service_class_fetch($rr['channel_id'],'expire_days');
-			if(intval($service_class_expire))
+			$service_class_expire = service_class_fetch($rr['channel_id'], 'expire_days');
+			if (intval($service_class_expire))
 				$channel_expire = $service_class_expire;
 			else
 				$channel_expire = $site_expire;
 
-			if(intval($channel_expire) && (intval($channel_expire) < intval($rr['channel_expire_days'])) ||
+			if (intval($channel_expire) && (intval($channel_expire) < intval($rr['channel_expire_days'])) ||
 				intval($rr['channel_expire_days'] == 0)) {
 				$expire_days = $channel_expire;
-			}
-			else {
+			} else {
 				$expire_days = $rr['channel_expire_days'];
 			}
 
@@ -72,34 +73,30 @@ function expire_run($argv, $argc){
 		}
 	}
 
-
 	$x = get_sys_channel();
-	if($x) {
+	if ($x) {
 
 		// this should probably just fetch the channel_expire_days from the sys channel,
 		// but there's no convenient way to set it.
 
-		$expire_days = get_config('system','sys_expire_days');
-		if($expire_days === false)
+		$expire_days = get_config('system', 'sys_expire_days');
+		if ($expire_days === false)
 			$expire_days = 30;
 
-		if(intval($site_expire) && (intval($site_expire) < intval($expire_days))) {
+		if (intval($site_expire) && (intval($site_expire) < intval($expire_days))) {
 			$expire_days = $site_expire;
 		}
 
 		logger('Expire: sys interval: ' . $expire_days, LOGGER_DEBUG);
 
-		if($expire_days)
-			item_expire($x['channel_id'],$expire_days);
+		if ($expire_days)
+			item_expire($x['channel_id'], $expire_days);
 
 		logger('Expire: sys: done', LOGGER_DEBUG);
-
 	}
-
-	return;
 }
 
-if (array_search(__file__,get_included_files())===0){
-  expire_run($argv,$argc);
-  killme();
+if (array_search(__file__, get_included_files()) === 0){
+	expire_run($argv, $argc);
+	killme();
 }
diff --git a/include/identity.php b/include/identity.php
index af6cb74d2..7884c04d2 100644
--- a/include/identity.php
+++ b/include/identity.php
@@ -1,27 +1,29 @@
-<?php /** @file */
+<?php
+/**
+ * @file include/identity.php
+ */
 
 require_once('include/zot.php');
 require_once('include/crypto.php');
 
 
 /**
- * @function identity_check_service_class($account_id)
- *     Called when creating a new channel. Checks the account's service class and number
- * of current channels to determine whether creating a new channel is within the current
- * service class constraints.
+ * @brief Called when creating a new channel.
+ *
+ * Checks the account's service class and number of current channels to determine
+ * whether creating a new channel is within the current service class constraints.
  *
  * @param int $account_id
  *     Account_id used for this request
  *
- * @returns array
- *       'success' => boolean true if creating a new channel is allowed for this account
- *       'message' => if success is false, optional error text
+ * @returns assoziative array with:
+ *  * \e boolean \b success boolean true if creating a new channel is allowed for this account
+ *  * \e string \b message (optional) if success is false, optional error text
+ *  * \e int \b total_identities
  */
- 
-
 function identity_check_service_class($account_id) {
-	$ret = array('success' => false, $message => '');
-	
+	$ret = array('success' => false, 'message' => '');
+
 	$r = q("select count(channel_id) as total from channel where channel_account_id = %d and not ( channel_pageflags & %d )>0 ",
 		intval($account_id),
 		intval(PAGE_REMOVED)
@@ -30,68 +32,67 @@ function identity_check_service_class($account_id) {
 		$ret['total_identities'] = 0;
 		$ret['message'] = t('Unable to obtain identity information from database');
 		return $ret;
-	} 
+	}
 
 	$ret['total_identities'] = intval($r[0]['total']);
 
-	if(! account_service_class_allows($account_id,'total_identities',$r[0]['total'])) {
-		$result['message'] .= upgrade_message();
-		return $result;
+	if (! account_service_class_allows($account_id, 'total_identities', $r[0]['total'])) {
+		$ret['message'] .= upgrade_message();
+		return $ret;
 	}
 
 	$ret['success'] = true;
+
 	return $ret;
 }
 
 
 /**
- * @function validate_channelname($name)
- *     Determine if the channel name is allowed when creating a new channel.
+ * @brief Determine if the channel name is allowed when creating a new channel.
+ *
  * This action is pluggable.
+ * We're currently only checking for an empty name or one that exceeds our
+ * storage limit (255 chars). 255 chars is probably going to create a mess on
+ * some pages.
+ * Plugins can set additional policies such as full name requirements, character
+ * sets, multi-byte length, etc.
  *
  * @param string $name
  *
  * @returns nil return if name is valid, or string describing the error state.
- *
- * We're currently only checking for an empty name or one that exceeds our storage limit (255 chars).
- * 255 chars is probably going to create a mess on some pages. 
- * Plugins can set additional policies such as full name requirements, character sets, multi-byte
- * length, etc. 
- *
  */
-
 function validate_channelname($name) {
 
-	if(! $name)
+	if (! $name)
 		return t('Empty name');
-	if(strlen($name) > 255)
+
+	if (strlen($name) > 255)
 		return t('Name too long');
+
 	$arr = array('name' => $name);
-	call_hooks('validate_channelname',$arr);
-	if(x($arr,'message'))
+	call_hooks('validate_channelname', $arr);
+
+	if (x($arr, 'message'))
 		return $arr['message'];
-	return;
 }
 
 
 /**
- * @function create_sys_channel()
- *     Create a system channel - which has no account attached
+ * @brief Create a system channel - which has no account attached.
  *
  */
-
 function create_sys_channel() {
-	if(get_sys_channel())
+	if (get_sys_channel())
 		return;
 
-    // Ensure that there is a host keypair.
+	// Ensure that there is a host keypair.
 
-    if((! get_config('system','pubkey')) && (! get_config('system','prvkey'))) {
+	if ((! get_config('system', 'pubkey')) && (! get_config('system', 'prvkey'))) {
 		require_once('include/crypto.php');
-        $hostkey = new_keypair(4096);
-        set_config('system','pubkey',$hostkey['pubkey']);
-        set_config('system','prvkey',$hostkey['prvkey']);
-    }
+		$hostkey = new_keypair(4096);
+		set_config('system', 'pubkey', $hostkey['pubkey']);
+		set_config('system', 'prvkey', $hostkey['prvkey']);
+	}
 
 	create_identity(array(
 		'account_id' => 'xxx',  // This will create an identity with an (integer) account_id of 0, but account_id is required
@@ -103,63 +104,79 @@ function create_sys_channel() {
 	));
 }
 
+
+/**
+ * @brief Returns the sys channel.
+ *
+ * @return array|boolean
+ */
 function get_sys_channel() {
 	$r = q("select * from channel left join xchan on channel_hash = xchan_hash where (channel_pageflags & %d)>0 limit 1",
 		intval(PAGE_SYSTEM)
 	);
-	if($r)
+
+	if ($r)
 		return $r[0];
+
 	return false;
 }
 
+
+/**
+ * @brief Checks if $channel_id is sys channel.
+ *
+ * @param int $channel_id
+ * @return boolean
+ */
 function is_sys_channel($channel_id) {
 	$r = q("select channel_pageflags from channel where channel_id = %d limit 1",
 		intval($channel_id)
 	);
-	if(($r) && ($r[0]['channel_pageflags'] & PAGE_SYSTEM))
+
+	if (($r) && ($r[0]['channel_pageflags'] & PAGE_SYSTEM))
 		return true;
+
 	return false;
 }
 
 
 /**
- * @channel_total()
- *   Return the total number of channels on this site. No filtering is performed except to check PAGE_REMOVED
+ * @brief Return the total number of channels on this site.
  *
- * @returns int 
- *   on error returns boolean false
+ * No filtering is performed except to check PAGE_REMOVED.
  *
+ * @returns int|booleean
+ *   on error returns boolean false
  */
-
 function channel_total() {
 	$r = q("select channel_id from channel where not ( channel_pageflags & %d )>0",
 		intval(PAGE_REMOVED)
 	);
 
-	if(is_array($r))
+	if (is_array($r))
 		return count($r);
+
 	return false;
 }
 
 
 /**
- * @function create_identity($arr)
- *     Create a new channel
- * Also creates the related xchan, hubloc, profile, and "self" abook records, and an 
- * empty "Friends" group/collection for the new channel
+ * @brief Create a new channel.
+ *
+ * Also creates the related xchan, hubloc, profile, and "self" abook records,
+ * and an empty "Friends" group/collection for the new channel.
  *
- * @param array $arr
- *       'name'       => full name of channel
- *       'nickname'   => "email/url-compliant" nickname
- *       'account_id' => account_id to attach with this channel
- *       [other identity fields as desired]
+ * @param array $arr assoziative array with:
+ *  * \e string \b name full name of channel
+ *  * \e string \b nickname "email/url-compliant" nickname
+ *  * \e int \b account_id to attach with this channel
+ *  * [other identity fields as desired]
  *
  * @returns array
  *     'success' => boolean true or false
  *     'message' => optional error text if success is false
  *     'channel' => if successful the created channel array
  */
- 
 function create_identity($arr) {
 
 	$a = get_app();
@@ -176,7 +193,6 @@ function create_identity($arr) {
 	// save this for auto_friending
 	$total_identities = $ret['total_identities'];
 
-
 	$nick = mb_strtolower(trim($arr['nickname']));
 	if(! $nick) {
 		$ret['message'] = t('Nickname is required.');
@@ -205,7 +221,6 @@ function create_identity($arr) {
 	$guid = zot_new_uid($nick);
 	$key = new_keypair(4096);
 
-
 	$sig = base64url_encode(rsa_sign($guid,$key['prvkey']));
 	$hash = make_xchan_hash($guid,$sig);
 
@@ -221,9 +236,6 @@ function create_identity($arr) {
 	if(array_key_exists('primary', $arr))
 		$primary = intval($arr['primary']);
 
-
-	$perms_sql = '';
-
 	$role_permissions = null;
 	$global_perms = get_perms();
 
@@ -269,7 +281,6 @@ function create_identity($arr) {
 		intval($expire),
 		dbesc($a->timezone)
 	);
-			
 
 	$r = q("select * from channel where channel_account_id = %d 
 		and channel_guid = '%s' limit 1",
@@ -281,7 +292,7 @@ function create_identity($arr) {
 		$ret['message'] = t('Unable to retrieve created identity');
 		return $ret;
 	}
-	
+
 	$ret['channel'] = $r[0];
 
 	if(intval($arr['account_id']))
@@ -307,7 +318,6 @@ function create_identity($arr) {
 	if(! $r)
 		logger('create_identity: Unable to store hub location');
 
-
 	$newuid = $ret['channel']['channel_id'];
 
 	$r = q("insert into xchan ( xchan_hash, xchan_guid, xchan_guid_sig, xchan_pubkey, xchan_photo_l, xchan_photo_m, xchan_photo_s, xchan_addr, xchan_url, xchan_follow, xchan_connurl, xchan_name, xchan_network, xchan_photo_date, xchan_name_date, xchan_flags ) values ('%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', %d)",
@@ -329,9 +339,8 @@ function create_identity($arr) {
 		intval($xchanflags)
 	);
 
-	// Not checking return value. 
+	// Not checking return value.
 	// It's ok for this to fail if it's an imported channel, and therefore the hash is a duplicate
-		
 
 	$r = q("INSERT INTO profile ( aid, uid, profile_guid, profile_name, is_default, publish, name, photo, thumb)
 		VALUES ( %d, %d, '%s', '%s', %d, %d, '%s', '%s', '%s') ",
@@ -418,37 +427,31 @@ function create_identity($arr) {
 		}
 
 		call_hooks('register_account', $newuid);
-	
+
 		proc_run('php','include/directory.php', $ret['channel']['channel_id']);
 	}
 
 	$ret['success'] = true;
 	return $ret;
-
 }
 
-
 /**
- * @function set_default_login_identity($account_id, $channel_id, $force = true)
- *       Set default channel to be used on login
+ * @brief Set default channel to be used on login.
  *
  * @param int $account_id
  *       login account
  * @param int $channel_id
  *       channel id to set as default for this account
- * @param boolean force
+ * @param boolean $force
  *       if true, set this default unconditionally
  *       if $force is false only do this if there is no existing default
- * 
- * @returns nil
  */
-
-function set_default_login_identity($account_id,$channel_id,$force = true) {
+function set_default_login_identity($account_id, $channel_id, $force = true) {
 	$r = q("select account_default_channel from account where account_id = %d limit 1",
 		intval($account_id)
 	);
-	if($r) {
-		if((intval($r[0]['account_default_channel']) == 0) || ($force)) {
+	if ($r) {
+		if ((intval($r[0]['account_default_channel']) == 0) || ($force)) {
 			$r = q("update account set account_default_channel = %d where account_id = %d",
 				intval($channel_id),
 				intval($account_id)
@@ -458,8 +461,7 @@ function set_default_login_identity($account_id,$channel_id,$force = true) {
 }
 
 /**
- * @function identity_basic_export($channel_id,$items = false)
- *     Create an array representing the important channel information
+ * @brief Create an array representing the important channel information
  * which would be necessary to create a nomadic identity clone. This includes
  * most channel resources and connection information with the exception of content.
  *
@@ -470,9 +472,7 @@ function set_default_login_identity($account_id,$channel_id,$force = true) {
  *
  * @returns array
  *     See function for details
- *
  */
-
 function identity_basic_export($channel_id, $items = false) {
 
 	/*
@@ -536,7 +536,6 @@ function identity_basic_export($channel_id, $items = false) {
 	if($r)
 		$ret['config'] = $r;
 
-
 	$r = q("select type, data from photo where scale = 4 and profile = 1 and uid = %d limit 1",
 		intval($channel_id)
 	);
@@ -563,11 +562,9 @@ function identity_basic_export($channel_id, $items = false) {
 	if($r)
 		$ret['obj'] = $r;
 
-
 	if(! $items)
 		return $ret;
 
-
 	$r = q("select likes.*, item.mid from likes left join item on likes.iid = item.id where likes.channel_id = %d",
 		intval($channel_id)
 	);
@@ -575,17 +572,16 @@ function identity_basic_export($channel_id, $items = false) {
 	if($r)
 		$ret['likes'] = $r;
 
-
 	$r = q("select item_id.*, item.mid from item_id left join item on item_id.iid = item.id where item_id.uid = %d",
 		intval($channel_id)
 	);
-	
+
 	if($r)
-		$ret['item_id'] = $r;	
+		$ret['item_id'] = $r;
 
-	$key = get_config('system','prvkey');
+	//$key = get_config('system','prvkey');
 
-	// warning: this may run into memory limits on smaller systems
+	/** @warning this may run into memory limits on smaller systems */
 
 	$r = q("select * from item where (item_flags & %d)>0 and not (item_restrict & %d)>0 and uid = %d",
 		intval(ITEM_WALL),
@@ -598,25 +594,17 @@ function identity_basic_export($channel_id, $items = false) {
 		$r = fetch_post_tags($r,true);
 		foreach($r as $rr)
 			$ret['item'][] = encode_item($rr,true);
-
 	}
-	return $ret;
 
+	return $ret;
 }
 
 
-
 /**
+ * @brief Loads a profile into the App structure.
  *
- * @function : profile_load(&$a, $nickname, $profile)
- *     Generate
- * @param App $a
- * @param string $nickname
- * @param string $profile
- *
- * Summary: Loads a profile into the App structure.
- * The function requires a writeable copy of the main App structure, and the nickname
- * of a valid channel.
+ * The function requires a writeable copy of the main App structure, and the
+ * nickname of a valid channel.
  *
  * Permissions of the current observer are checked. If a restricted profile is available
  * to the current observer, that will be loaded instead of the channel default profile.
@@ -625,9 +613,10 @@ function identity_basic_export($channel_id, $items = false) {
  *
  * The channel default theme is also selected for use, unless over-riden elsewhere.
  *
+ * @param[in,out] App &$a
+ * @param string $nickname
+ * @param string $profile
  */
-
-
 function profile_load(&$a, $nickname, $profile = '') {
 
 	logger('profile_load: ' . $nickname . (($profile) ? ' profile: ' . $profile : ''));
@@ -635,7 +624,7 @@ function profile_load(&$a, $nickname, $profile = '') {
 	$user = q("select channel_id from channel where channel_address = '%s' limit 1",
 		dbesc($nickname)
 	);
-		
+
 	if(! $user) {
 		logger('profile error: ' . $a->query_string, LOGGER_DEBUG);
 		notice( t('Requested channel is not available.') . EOL );
@@ -683,7 +672,6 @@ function profile_load(&$a, $nickname, $profile = '') {
 		);
 	}
 
-
 	if(! $p) {
 		logger('profile error: ' . $a->query_string, LOGGER_DEBUG);
 		notice( t('Requested profile is not available.') . EOL );
@@ -729,10 +717,11 @@ function profile_load(&$a, $nickname, $profile = '') {
 		$p[0]['picdate'] = $z[0]['xchan_photo_date'];
 		$p[0]['reddress'] = str_replace('@','&#xff20;',$z[0]['xchan_addr']);
 	}
-	
+
 	// fetch user tags if this isn't the default profile
 
 	if(! $p[0]['is_default']) {
+		/** @BUG $profile_uid is undefinded for this query, so should not work. */
 		$x = q("select `keywords` from `profile` where uid = %d and `is_default` = 1 limit 1",
 				intval($profile_uid)
 		);
@@ -744,7 +733,6 @@ function profile_load(&$a, $nickname, $profile = '') {
 		$keywords = str_replace(array('#',',',' ',',,'),array('',' ',',',','),$p[0]['keywords']);
 		if(strlen($keywords) && $can_view_profile)
 			$a->page['htmlhead'] .= '<meta name="keywords" content="' . htmlentities($keywords,ENT_COMPAT,'UTF-8') . '" />' . "\r\n" ;
-
 	}
 
 	$a->profile = $p[0];
@@ -756,7 +744,6 @@ function profile_load(&$a, $nickname, $profile = '') {
 	if($can_view_profile) {
 		$online = get_online_status($nickname);
 		$a->profile['online_status'] = $online['result'];
-
 	}
 
 	if(local_channel()) {
@@ -764,7 +751,7 @@ function profile_load(&$a, $nickname, $profile = '') {
 		$_SESSION['mobile_theme'] = $a->profile['channel_mobile_theme'];
 	}
 
-	/**
+	/*
 	 * load/reload current theme info
 	 */
 
@@ -776,36 +763,34 @@ function profile_load(&$a, $nickname, $profile = '') {
 //	if (file_exists($theme_info_file)){
 //		require_once($theme_info_file);
 //	}
-
-	return;
 }
 
-function profile_create_sidebar(&$a,$connect = true) {
+/**
+ * @brief
+ *
+ * @param App &$a
+ * @param boolean $connect
+ */
+function profile_create_sidebar(&$a, $connect = true) {
 
-	$block = (((get_config('system','block_public')) && (! local_channel()) && (! remote_channel())) ? true : false);
+	$block = (((get_config('system', 'block_public')) && (! local_channel()) && (! remote_channel())) ? true : false);
 
-	$a->set_widget('profile',profile_sidebar($a->profile, $block, $connect));
-	return;
+	$a->set_widget('profile', profile_sidebar($a->profile, $block, $connect));
 }
 
-
 /**
+ * @brief Formats a profile for display in the sidebar.
  *
- * Function: profile_sidebar
- *
- * Formats a profile for display in the sidebar.
  * It is very difficult to templatise the HTML completely
  * because of all the conditional logic.
  *
- * @parameter: array $profile
+ * @param array $profile
+ * @param int $block
+ * @param boolean $show_connect
  *
- * Returns HTML string stuitable for sidebar inclusion
+ * @return HTML string suitable for sidebar inclusion
  * Exceptions: Returns empty string if passed $profile is wrong type or not populated
- *
  */
-
-
-
 function profile_sidebar($profile, $block = 0, $show_connect = true) {
 
 	$a = get_app();
@@ -814,14 +799,12 @@ function profile_sidebar($profile, $block = 0, $show_connect = true) {
 
 	$o = '';
 	$location = false;
-	$address = false;
 	$pdesc = true;
 	$reddress = true;
 
 	if((! is_array($profile)) && (! count($profile)))
 		return $o;
 
-
 	head_set_icon($profile['thumb']);
 
 	$is_owner = (($profile['uid'] == local_channel()) ? true : false);
@@ -849,13 +832,11 @@ function profile_sidebar($profile, $block = 0, $show_connect = true) {
 
 	// show edit profile to yourself
 	if($is_owner) {
-
 		$profile['menu'] = array(
 			'chg_photo' => t('Change profile photo'),
 			'entries' => array(),
 		);
 
-
 		$multi_profiles = feature_enabled(local_channel(), 'multi_profiles');
 		if($multi_profiles) {
 			$profile['edit'] = array($a->get_baseurl(). '/profiles', t('Profiles'),"", t('Manage/edit profiles'));
@@ -863,10 +844,9 @@ function profile_sidebar($profile, $block = 0, $show_connect = true) {
 		}
 		else
 			$profile['edit'] = array($a->get_baseurl() . '/profiles/' . $profile['id'], t('Edit Profile'),'',t('Edit Profile'));
-						
+
 		$r = q("SELECT * FROM `profile` WHERE `uid` = %d",
 				local_channel());
-		
 
 		if($r) {
 			foreach($r as $rr) {
@@ -899,21 +879,21 @@ function profile_sidebar($profile, $block = 0, $show_connect = true) {
 	$marital  = ((x($profile,'marital')  == 1) ? t('Status:')   : False);
 	$homepage = ((x($profile,'homepage') == 1) ? t('Homepage:') : False);
 	$profile['online']   = (($profile['online_status'] === 'online') ? t('Online Now') : False);
-logger('online: ' . $profile['online']);
+	logger('online: ' . $profile['online']);
 
 	if(! perm_is_allowed($profile['uid'],((is_array($observer)) ? $observer['xchan_hash'] : ''),'view_profile')) {
 		$block = true;
 	}
 
 	if(($profile['hidewall'] && (! local_channel()) && (! remote_channel())) || $block ) {
-		$location = $reddress = $pdesc = $gender = $marital = $homepage = $online = False;
+		$location = $reddress = $pdesc = $gender = $marital = $homepage = False;
 	}
 
 	$firstname = ((strpos($profile['channel_name'],' '))
 		? trim(substr($profile['channel_name'],0,strpos($profile['channel_name'],' '))) : $profile['channel_name']);
 	$lastname = (($firstname === $profile['channel_name']) ? '' : trim(substr($profile['channel_name'],strlen($firstname))));
 
-    $diaspora = array(
+	$diaspora = array(
 		'podloc'     => z_root(),
 		'searchable' => (($block) ? 'false' : 'true'),
 		'nickname'   => $profile['channel_address'],
@@ -970,9 +950,9 @@ logger('online: ' . $profile['online']);
 }
 
 
-// FIXME or remove
-
-
+/**
+ * @FIXME or remove
+ */
 	function get_birthdays() {
 
 		$a = get_app();
@@ -1030,7 +1010,6 @@ logger('online: ' . $profile['online']);
 					$rr['date'] = day_translate(datetime_convert('UTC', $a->timezone, $rr['start'], $rr['adjust'] ? $bd_format : $bd_short)) . (($today) ?  ' ' . t('[today]') : '');
 					$rr['startime'] = Null;
 					$rr['today'] = $today;
-	
 				}
 			}
 		}
@@ -1044,14 +1023,13 @@ logger('online: ' . $profile['online']);
 			'$events' => $r,
 			'$lbr' => '{',  // raw brackets mess up if/endif macro processing
 			'$rbr' => '}'
-
 		));
 	}
 
 
-// FIXME
-
-
+/**
+ * @FIXME
+ */
 	function get_events() {
 
 		require_once('include/bbcode.php');
@@ -1085,7 +1063,6 @@ logger('online: ' . $profile['online']);
 			}
 			$classtoday = (($istoday) ? 'event-today' : '');
 
-
 			foreach($r as &$rr) {
 				if($rr['adjust'])
 					$md = datetime_convert('UTC',$a->timezone,$rr['start'],'Y/m');
@@ -1132,19 +1109,19 @@ function advanced_profile(&$a) {
 	if($a->profile['name']) {
 
 		$tpl = get_markup_template('profile_advanced.tpl');
-		
+
 		$profile = array();
-		
+
 		$profile['fullname'] = array( t('Full Name:'), $a->profile['name'] ) ;
-		
+
 		if($a->profile['gender']) $profile['gender'] = array( t('Gender:'),  $a->profile['gender'] );
-		
+
 		$ob_hash = get_observer_hash();
 		if($ob_hash && perm_is_allowed($a->profile['profile_uid'],$ob_hash,'post_like')) {
 			$profile['canlike'] = true;
 			$profile['likethis'] = t('Like this channel');
 			$profile['profile_guid'] = $a->profile['profile_guid'];
-		} 
+		}
 
 		$likers = q("select liker, xchan.*  from likes left join xchan on liker = xchan_hash where channel_id = %d and target_type = '%s' and verb = '%s'",
 			intval($a->profile['profile_uid']),
@@ -1175,19 +1152,19 @@ function advanced_profile(&$a) {
 					: day_translate(datetime_convert('UTC','UTC','2001-' . substr($a->profile['dob'],5) . ' 00:00 +00:00',$short_bd_format)));
 			}
 			$profile['birthday'] = array( t('Birthday:'), $val);
-
 		}
 
-		if($age = age($a->profile['dob'],$a->profile['timezone'],''))  $profile['age'] = array( t('Age:'), $age );
-			
-
-		if($a->profile['marital']) $profile['marital'] = array( t('Status:'), $a->profile['marital']);
+		if($age = age($a->profile['dob'],$a->profile['timezone'],''))
+			$profile['age'] = array( t('Age:'), $age );
 
+		if($a->profile['marital'])
+			$profile['marital'] = array( t('Status:'), $a->profile['marital']);
 
-		if($a->profile['with']) $profile['marital']['with'] = bbcode($a->profile['with']);
+		if($a->profile['with'])
+			$profile['marital']['with'] = bbcode($a->profile['with']);
 
 		if(strlen($a->profile['howlong']) && $a->profile['howlong'] !== NULL_DATE) {
-				$profile['howlong'] = relative_date($a->profile['howlong'], t('for %1$d %2$s'));
+			$profile['howlong'] = relative_date($a->profile['howlong'], t('for %1$d %2$s'));
 		}
 
 		if($a->profile['sexual']) $profile['sexual'] = array( t('Sexual Preference:'), $a->profile['sexual'] );
@@ -1243,54 +1220,55 @@ function advanced_profile(&$a) {
 
 //		logger('mod_profile: things: ' . print_r($things,true), LOGGER_DATA); 
 
-        return replace_macros($tpl, array(
-            '$title' => t('Profile'),
+		return replace_macros($tpl, array(
+			'$title' => t('Profile'),
 			'$canlike' => (($profile['canlike'])? true : false),
 			'$likethis' => t('Like this thing'),
-            '$profile' => $profile,
+			'$profile' => $profile,
 			'$things' => $things
-        ));
-    }
+		));
+	}
 
 	return '';
 }
 
 
-
-
 function get_my_url() {
-	if(x($_SESSION,'zrl_override'))
+	if(x($_SESSION, 'zrl_override'))
 		return $_SESSION['zrl_override'];
-	if(x($_SESSION,'my_url'))
+	if(x($_SESSION, 'my_url'))
 		return $_SESSION['my_url'];
+
 	return false;
 }
 
 function get_my_address() {
-	if(x($_SESSION,'zid_override'))
+	if(x($_SESSION, 'zid_override'))
 		return $_SESSION['zid_override'];
-	if(x($_SESSION,'my_address'))
+	if(x($_SESSION, 'my_address'))
 		return $_SESSION['my_address'];
+
 	return false;
 }
 
 /**
- * @function zid_init(&$a)
- *   If somebody arrives at our site using a zid, add their xchan to our DB if we don't have it already.
- *   And if they aren't already authenticated here, attempt reverse magic auth.
+ * @brief
+ *
+ * If somebody arrives at our site using a zid, add their xchan to our DB if we don't have it already.
+ * And if they aren't already authenticated here, attempt reverse magic auth.
+ *
+ * @param App &$a
  *
  * @hooks 'zid_init'
  *      string 'zid' - their zid
  *      string 'url' - the destination url
- *
  */
-
 function zid_init(&$a) {
 	$tmp_str = get_my_address();
 	if(validate_email($tmp_str)) {
 		proc_run('php','include/gprobe.php',bin2hex($tmp_str));
 		$arr = array('zid' => $tmp_str, 'url' => $a->cmd);
-		call_hooks('zid_init',$arr);		
+		call_hooks('zid_init',$arr);
 		if(! local_channel()) {
 			$r = q("select * from hubloc where hubloc_addr = '%s' order by hubloc_connected desc limit 1",
 				dbesc($tmp_str)
@@ -1312,8 +1290,8 @@ function zid_init(&$a) {
 }
 
 /**
- * @function zid($s,$address = '')
- *   Adds a zid parameter to a url
+ * @brief Adds a zid parameter to a url.
+ *
  * @param string $s
  *   The url to accept the zid
  * @param boolean $address
@@ -1325,31 +1303,33 @@ function zid_init(&$a) {
  *      string zid - urlencoded zid
  *      string result - the return string we calculated, change it if you want to return something else
  */
-
-
 function zid($s,$address = '') {
-	if(! strlen($s) || strpos($s,'zid='))
+	if (! strlen($s) || strpos($s,'zid='))
 		return $s;
+
 	$has_params = ((strpos($s,'?')) ? true : false);
-	$num_slashes = substr_count($s,'/');
-	if(! $has_params)
-		$has_params = ((strpos($s,'&')) ? true : false);
+	$num_slashes = substr_count($s, '/');
+	if (! $has_params)
+		$has_params = ((strpos($s, '&')) ? true : false);
+
 	$achar = strpos($s,'?') ? '&' : '?';
 
 	$mine = get_my_url();
 	$myaddr = (($address) ? $address : get_my_address());
 
-	// FIXME checking against our own channel url is no longer reliable. We may have a lot
-	// of urls attached to out channel. Should probably match against our site, since we
-	// will not need to remote authenticate on our own site anyway.
+	/** @FIXME checking against our own channel url is no longer reliable. We may have a lot
+	 * of urls attached to out channel. Should probably match against our site, since we
+	 * will not need to remote authenticate on our own site anyway.
+	 */
 
-	if($mine && $myaddr && (! link_compare($mine,$s)))
+	if ($mine && $myaddr && (! link_compare($mine,$s)))
 		$zurl = $s . (($num_slashes >= 3) ? '' : '/') . $achar . 'zid=' . urlencode($myaddr);
 	else
 		$zurl = $s;
 
 	$arr = array('url' => $s, 'zid' => urlencode($myaddr), 'result' => $zurl);
 	call_hooks('zid', $arr);
+
 	return $arr['result'];
 }
 
@@ -1369,55 +1349,45 @@ function get_theme_uid() {
 		$x = get_sys_channel();
 		if($x)
 			return $x['channel_id'];
-	}	
+	}
+
 	return $uid;
 }
 
 /**
-* @function get_default_profile_photo($size = 175)
-* 	Retrieves the path of the default_profile_photo for this system
-* 	with the specified size.
+* @brief Retrieves the path of the default_profile_photo for this system
+* with the specified size.
+*
 * @param int $size
-* 	one of (175, 80, 48)
+*  one of (175, 80, 48)
 * @returns string
-*
 */
-
 function get_default_profile_photo($size = 175) {
-		$scheme = get_config('system','default_profile_photo');
-		if(! $scheme)
-			$scheme = 'rainbow_man';
-		return 'images/default_profile_photos/' . $scheme . '/' . $size . '.png';
-}
+	$scheme = get_config('system','default_profile_photo');
+	if(! $scheme)
+		$scheme = 'rainbow_man';
 
+	return 'images/default_profile_photos/' . $scheme . '/' . $size . '.png';
+}
 
 /**
+ * @brief Test whether a given identity is NOT a member of the Red Matrix.
  *
- * @function is_foreigner($s)
- *    Test whether a given identity is NOT a member of the Red Matrix
  * @param string $s;
  *    xchan_hash of the identity in question
- *
  * @returns boolean true or false
- *
  */
-
 function is_foreigner($s) {
-	return((strpbrk($s,'.:@')) ? true : false);
+	return((strpbrk($s, '.:@')) ? true : false);
 }
 
-
 /**
+ * @brief Test whether a given identity is a member of the Red Matrix.
  *
- * @function is_member($s)
- *    Test whether a given identity is a member of the Red Matrix
  * @param string $s;
  *    xchan_hash of the identity in question
- *
  * @returns boolean true or false
- *
  */
-
 function is_member($s) {
 	return((is_foreigner($s)) ? false : true);
 }
@@ -1464,8 +1434,8 @@ function remote_online_status($webbie) {
 		if($j)
 			$result = (($j['result']) ? $j['result'] : false);
 	}
-	return $result;
 
+	return $result;
 }
 
 
@@ -1477,17 +1447,20 @@ function get_channel_by_nick($nick) {
 
 }
 
-
+/**
+ * @brief
+ *
+ * @return string
+ */
 function identity_selector() {
-	if(local_channel()) {
+	if (local_channel()) {
 		$r = q("select channel.*, xchan.* from channel left join xchan on channel.channel_hash = xchan.xchan_hash where channel.channel_account_id = %d and (channel_pageflags & %d) = 0 order by channel_name ",
 			intval(get_account_id()),
 			intval(PAGE_REMOVED)
 		);
-		if(count($r) > 1) {
-			$selected_channel = null;
-			$account = get_app()->get_account();
-			$o = replace_macros(get_markup_template('channel_id_select.tpl'),array(
+		if (count($r) > 1) {
+			//$account = get_app()->get_account();
+			$o = replace_macros(get_markup_template('channel_id_select.tpl'), array(
 				'$channels' => $r,
 				'$selected' => local_channel()
 			));
@@ -1507,6 +1480,7 @@ function is_public_profile() {
 	$channel = get_app()->get_channel();
 	if($channel && $channel['channel_r_profile'] == PERMS_PUBLIC)
 		return true;
+
 	return false;
 }
 
@@ -1522,7 +1496,6 @@ function get_profile_fields_basic($filter = 0) {
 			$x[$f] = 1;
 
 	return $x;
-
 }
 
 
@@ -1536,6 +1509,7 @@ function get_profile_fields_advanced($filter = 0) {
 	if($basic)
 		foreach($basic as $f => $v)
 			$x[$f] = $v;
+
 	if($profile_fields_advanced)
 		foreach($profile_fields_advanced as $f)
 			$x[$f] = 1;
@@ -1544,28 +1518,26 @@ function get_profile_fields_advanced($filter = 0) {
 }
 
 /**
- * @function notifications_off($channel_id)
- *    Clear notifyflags for a channel - most likely during bulk import of content or other activity that is likely
- *    to generate huge amounts of undesired notifications.
+ * @brief Clear notifyflags for a channel.
+ *
+ * Most likely during bulk import of content or other activity that is likely
+ * to generate huge amounts of undesired notifications.
+ *
  * @param int $channel_id
  *    The channel to disable notifications for
  * @returns int
  *    Current notification flag value. Send this to notifications_on() to restore the channel settings when finished
  *    with the activity requiring notifications_off(); 
  */
-
-
-
 function notifications_off($channel_id) {
 	$r = q("select channel_notifyflags from channel where channel_id = %d limit 1",
 		intval($channel_id)
 	);
-	$x = q("update channel set channel_notifyflags = 0 where channel_id = %d",
+	q("update channel set channel_notifyflags = 0 where channel_id = %d",
 		intval($channel_id)
 	);
 
 	return intval($r[0]['channel_notifyflags']);
-
 }
 
 
@@ -1586,5 +1558,6 @@ function get_channel_default_perms($uid) {
 	);
 	if($r)
 		return $r[0]['abook_my_perms'];
+
 	return 0;
 }
diff --git a/include/items.php b/include/items.php
index ef269b9c4..4b83ce3e3 100755
--- a/include/items.php
+++ b/include/items.php
@@ -1,4 +1,7 @@
-<?php /** @file */
+<?php
+/**
+ * @file include/items.php
+ */
 
 require_once('include/bbcode.php');
 require_once('include/oembed.php');
@@ -6,8 +9,14 @@ require_once('include/crypto.php');
 require_once('include/photo/photo_driver.php');
 require_once('include/permissions.php');
 
-
-function collect_recipients($item,&$private_envelope) {
+/**
+ * @brief Collects recipients.
+ *
+ * @param array $item
+ * @param[out] boolean $private_envelope
+ * @return array containing the recipients
+ */
+function collect_recipients($item, &$private_envelope) {
 
 	require_once('include/group.php');
 
@@ -67,7 +76,7 @@ function collect_recipients($item,&$private_envelope) {
 
 		$private_envelope = false;
 		require_once('include/identity.php');
-		$sys = get_sys_channel();
+		//$sys = get_sys_channel();
 
 		if(array_key_exists('public_policy',$item) && $item['public_policy'] !== 'self') {
 			$r = q("select abook_xchan, xchan_network from abook left join xchan on abook_xchan = xchan_hash where abook_channel = %d and not (abook_flags & %d)>0 ",
@@ -84,7 +93,7 @@ function collect_recipients($item,&$private_envelope) {
 					switch($policy) {
 						case 'net':
 						case 'aut':
-						case 'sit':		
+						case 'sit':
 						case 'any':
 						case 'con':
 							if($rr['xchan_network'] != 'zot')
@@ -103,7 +112,6 @@ function collect_recipients($item,&$private_envelope) {
 		}
 	}
 
-
 	// This is a somewhat expensive operation but important.
 	// Don't send this item to anybody who isn't allowed to see it
 
@@ -129,7 +137,6 @@ function collect_recipients($item,&$private_envelope) {
 		$recipients[] = $item['owner_xchan'];
 
 	return $recipients;
-
 }
 
 /**
@@ -139,30 +146,35 @@ function collect_recipients($item,&$private_envelope) {
  * They can still be addressed individually.
  * Networks may need to be added or removed from this list as circumstances change.
  *
- * Update: this may need to be the default, which will force people to opt-in to sending stuff
- * privately to insecure platforms. 
+ * Update: this may need to be the default, which will force people to opt-in to
+ * sending stuff privately to insecure platforms.
+ *
+ * @param int $channel_id
+ * @param array $arr
+ * @return array containing the sane xchan_hashes
  */
-
-function filter_insecure($channel_id,$arr) {
+function filter_insecure($channel_id, $arr) {
 	$insecure_nets = " and not xchan_network in ('diaspora', 'friendica-over-diaspora') ";
 
 	$ret = array();
 
-	if((! intval(get_config($channel_id,'system','filter_insecure_collections'))) || (! $arr))
+	if((! intval(get_config($channel_id, 'system', 'filter_insecure_collections'))) || (! $arr))
 		return $arr;
 
 	$str = '';
 	foreach($arr as $rr) {
 		if(strlen($str))
 			$str .= ',';
+
 		$str .= "'" . dbesc($rr) . "'";
 	}
-	$r = q("select xchan_hash from xchan where xchan_hash in ($str) $insecure_nets ");
+	$r = q("select xchan_hash from xchan where xchan_hash in ($str) $insecure_nets");
 	if($r) {
 		foreach($r as $rr) {
 			$ret[] = $rr['xchan_hash'];
 		}
 	}
+
 	return $ret;
 }
 
@@ -173,12 +185,13 @@ function comments_are_now_closed($item) {
 		if($d > $item['comments_closed'])
 			return true;
 	}
+
 	return false;
 }
 
 
 /**
- * @function can_comment_on_post($observer_xchan,$item);
+ * @brief
  *
  * This function examines the comment_policy attached to an item and decides if the current observer has
  * sufficient privileges to comment. This will normally be called on a remote site where perm_is_allowed()
@@ -187,16 +200,18 @@ function comments_are_now_closed($item) {
  * If it is, you should be able to use perm_is_allowed( ... 'post_comments'), and if it isn't you need to call 
  * can_comment_on_post()
  * We also check the comments_closed date/time on the item if this is set. 
+ *
+ * @param string $observer_xchan
+ * @param array $item
+ * @return boolean
  */
-
-function can_comment_on_post($observer_xchan,$item) {
+function can_comment_on_post($observer_xchan, $item) {
 
 //	logger('can_comment_on_post: comment_policy: ' . $item['comment_policy'], LOGGER_DEBUG);
 
 	if(! $observer_xchan)
 		return false;
 
-
 	if($item['comment_policy'] === 'none')
 		return false;
 
@@ -205,6 +220,7 @@ function can_comment_on_post($observer_xchan,$item) {
 
 	if($observer_xchan === $item['author_xchan'] || $observer_xchan === $item['owner_xchan'])
 		return true;
+
 	switch($item['comment_policy']) {
 		case 'self':
 			if($observer_xchan === $item['author_xchan'] || $observer_xchan === $item['owner_xchan'])
@@ -233,36 +249,36 @@ function can_comment_on_post($observer_xchan,$item) {
 		return true;
 	if(strstr($item['comment_policy'],'site:') && strstr($item['comment_policy'],get_app()->get_hostname()))
 		return true;
-	
+
 	return false;
 }
 
 /**
- * @function add_source_route($iid,$hash)
- *    Adds $hash to the item source route specified by $iid
- * @param integer $iid 
- *    item['id'] of target item
- * @param string $hash
- *    xchan_hash of the channel that sent the item
- * Modifies item pointed to by $iid
+ * @brief Adds $hash to the item source route specified by $iid.
  *
  * $item['route'] contains a comma-separated list of xchans that sent the current message, 
  * somewhat analogous to the * Received: header line in email. We can use this to perform
  * loop detection and to avoid sending a particular item to any "upstream" sender (they 
- * already have a copy because they sent it to us).  
+ * already have a copy because they sent it to us).
+ *
+ * Modifies item in the database pointed to by $iid.
  *
+ * @param integer $iid
+ *    item['id'] of target item
+ * @param string $hash
+ *    xchan_hash of the channel that sent the item
  */
-
-function add_source_route($iid,$hash) {
+function add_source_route($iid, $hash) {
 //	logger('add_source_route ' . $iid . ' ' . $hash, LOGGER_DEBUG);
 
 	if((! $iid) || (! $hash))
 		return;
+
 	$r = q("select route from item where id = %d limit 1",
 		intval($iid)
 	);
 	if($r) {
-		$new_route = (($r[0]['route']) ? $r[0]['route'] . ',' : '') . $hash; 
+		$new_route = (($r[0]['route']) ? $r[0]['route'] . ',' : '') . $hash;
 		q("update item set route = '%s' where id = %d",
 			(dbesc($new_route)),
 			intval($iid)
@@ -271,17 +287,17 @@ function add_source_route($iid,$hash) {
 }
 
 
-
 /**
- * @function red_zrl_callback
- *   preg_match function when fixing 'naked' links in mod item.php
- *   Check if we've got a hubloc for the site and use a zrl if we do, a url if we don't. 
- *   Remove any existing zid= param which may have been pasted by mistake - and will have
- *   the author's credentials. zid's are dynamic and can't really be passed around like
- *   that.
+ * @brief preg_match function when fixing 'naked' links in mod item.php.
+ *
+ * Check if we've got a hubloc for the site and use a zrl if we do, a url if we don't.
+ * Remove any existing zid= param which may have been pasted by mistake - and will have
+ * the author's credentials. zid's are dynamic and can't really be passed around like
+ * that.
+ *
+ * @param array $matches
+ * @return string
  */
-
-
 function red_zrl_callback($matches) {
 	require_once('include/hubloc.php');
 	$zrl = is_matrix_url($matches[2]);
@@ -296,19 +312,24 @@ function red_zrl_callback($matches) {
 		$matches[1] = '';
 	if($zrl)
 		return $matches[1] . '#^[zrl=' . $matches[2] . ']' . $matches[2] . '[/zrl]';
+
 	return $matches[1] . '#^[url=' . $matches[2] . ']' . $matches[2] . '[/url]';
 }
 
-
-// If we've got a url or zrl tag with a naked url somewhere in the link text, 
-// escape it with quotes unless the naked url is a linked photo. 
-
+/**
+ * If we've got a url or zrl tag with a naked url somewhere in the link text,
+ * escape it with quotes unless the naked url is a linked photo.
+ *
+ * @param array $matches
+ * @return string
+ */
 function red_escape_zrl_callback($matches) {
 
 	// Uncertain why the url/zrl forms weren't picked up by the non-greedy regex.
 
-	if((strpos($matches[3],'zmg') !== false) || (strpos($matches[3],'img') !== false) || (strpos($matches[3],'zrl') !== false) || (strpos($matches[3],'url') !== false))
+	if((strpos($matches[3], 'zmg') !== false) || (strpos($matches[3], 'img') !== false) || (strpos($matches[3],'zrl') !== false) || (strpos($matches[3],'url') !== false))
 		return $matches[0];
+
 	return '[' . $matches[1] . 'rl' . $matches[2] . ']' . $matches[3] . '"' . $matches[4] . '"' . $matches[5] . '[/' . $matches[6] . 'rl]';
 }
 
@@ -318,7 +339,6 @@ function red_escape_codeblock($m) {
 
 function red_unescape_codeblock($m) {
 	return '[' . $m[2] . base64_decode($m[1]) . '[/' . $m[2] . ']';
-	
 }
 
 
@@ -334,28 +354,23 @@ function red_zrlify_img_callback($matches) {
 
 	if($zrl)
 		return '[zmg' . $matches[1] . ']' . $matches[2] . '[/zmg]';
+
 	return $matches[0];
 }
 
 
-
-
 /**
- * @function post_activity_item($arr)
- *
- *     post an activity
- * 
- * @param array $arr
+ * @brief Post an activity.
  *
  * In its simplest form one needs only to set $arr['body'] to post a note to the logged in channel's wall.
  * Much more complex activities can be created. Permissions are checked. No filtering, tag expansion 
  * or other processing is performed.
  *
- * @returns array 
- *      'success' => true or false 
- *      'activity' => the resulting activity if successful
+ * @param array $arr
+ * @returns array
+ *  * \e boolean \b success true or false
+ *  * \e array \b activity the resulting activity if successful
  */
-
 function post_activity_item($arr) {
 
 	$ret = array('success' => false);
@@ -369,14 +384,13 @@ function post_activity_item($arr) {
 			$arr['item_flags'] = ITEM_ORIGIN;
 		else
 			$arr['item_flags'] = ITEM_ORIGIN | ITEM_WALL | ITEM_THREAD_TOP;
-	}	
-
+	}
 
 	$channel  = get_app()->get_channel();
 	$observer = get_app()->get_observer();
 
-	$arr['aid']          = 	((x($arr,'aid')) ? $arr['aid'] : $channel['channel_account_id']);
-	$arr['uid']          = 	((x($arr,'uid')) ? $arr['uid'] : $channel['channel_id']);
+	$arr['aid'] = ((x($arr,'aid')) ? $arr['aid'] : $channel['channel_account_id']);
+	$arr['uid'] = ((x($arr,'uid')) ? $arr['uid'] : $channel['channel_id']);
 
 	if(! perm_is_allowed($arr['uid'],$observer['xchan_hash'],(($is_comment) ? 'post_comments' : 'post_wall'))) {
 		$ret['message'] = t('Permission denied');
@@ -410,19 +424,18 @@ function post_activity_item($arr) {
 			$arr['body']  = json_encode(crypto_encapsulate($arr['body'],$key));
 	}
 
-	$arr['mid']          = 	((x($arr,'mid')) ? $arr['mid'] : item_message_id());
-	$arr['parent_mid']   =  ((x($arr,'parent_mid')) ? $arr['parent_mid'] : $arr['mid']);
-	$arr['thr_parent']   =  ((x($arr,'thr_parent')) ? $arr['thr_parent'] : $arr['mid']);
+	$arr['mid']          = ((x($arr,'mid')) ? $arr['mid'] : item_message_id());
+	$arr['parent_mid']   = ((x($arr,'parent_mid')) ? $arr['parent_mid'] : $arr['mid']);
+	$arr['thr_parent']   = ((x($arr,'thr_parent')) ? $arr['thr_parent'] : $arr['mid']);
 
-	$arr['owner_xchan']  = 	((x($arr,'owner_xchan'))  ? $arr['owner_xchan']  : $channel['channel_hash']);
-	$arr['author_xchan'] = 	((x($arr,'author_xchan')) ? $arr['author_xchan'] : $observer['xchan_hash']);
+	$arr['owner_xchan']  = ((x($arr,'owner_xchan'))  ? $arr['owner_xchan']  : $channel['channel_hash']);
+	$arr['author_xchan'] = ((x($arr,'author_xchan')) ? $arr['author_xchan'] : $observer['xchan_hash']);
 
-	$arr['verb']         = 	((x($arr,'verb')) ? $arr['verb'] : ACTIVITY_POST);
-	$arr['obj_type']     =  ((x($arr,'obj_type')) ? $arr['obj_type'] : ACTIVITY_OBJ_NOTE);
+	$arr['verb']         = ((x($arr,'verb')) ? $arr['verb'] : ACTIVITY_POST);
+	$arr['obj_type']     = ((x($arr,'obj_type')) ? $arr['obj_type'] : ACTIVITY_OBJ_NOTE);
 	if($is_comment)
 		$arr['obj_type'] = ACTIVITY_OBJ_COMMENT;
 
-
 	$arr['allow_cid']    = ((x($arr,'allow_cid')) ? $arr['allow_cid'] : $channel['channel_allow_cid']);
 	$arr['allow_gid']    = ((x($arr,'allow_gid')) ? $arr['allow_gid'] : $channel['channel_allow_gid']);
 	$arr['deny_cid']     = ((x($arr,'deny_cid')) ? $arr['deny_cid'] : $channel['channel_deny_cid']);
@@ -430,7 +443,6 @@ function post_activity_item($arr) {
 
 	$arr['comment_policy'] = map_scope($channel['channel_w_comment']); 
 
-
 	if ((! $arr['plink']) && ($arr['item_flags'] & ITEM_THREAD_TOP)) {
 		$arr['plink'] = z_root() . '/channel/' . $channel['channel_address'] . '/?f=&mid=' . $arr['mid'];
 	}
@@ -447,7 +459,6 @@ function post_activity_item($arr) {
 		return $ret;
 	}
 
-
 	$post = item_store($arr);	
 	if($post['success'])
 		$post_id = $post['item_id'];
@@ -465,15 +476,15 @@ function post_activity_item($arr) {
 	}
 
 	return $ret;
-
 }
 
 /**
- * @function get_public_feed($channel,$params)
- *     generate an Atom feed
+ * @brief Generate an Atom feed.
+ *
+ * @param array $channel
+ * @param array $params
  */
-
-function get_public_feed($channel,$params) {
+function get_public_feed($channel, $params) {
 
 	$type      = 'xml';
 	$begin     = NULL_DATE;
@@ -494,7 +505,7 @@ function get_public_feed($channel,$params) {
 	$params['direction'] = ((x($params,'direction')) ? $params['direction']     : 'desc');
 	$params['pages']     = ((x($params,'pages'))     ? intval($params['pages']) : 0);
 	$params['top']       = ((x($params,'top'))       ? intval($params['top'])   : 0);
-		
+
 	switch($params['type']) {
 		case 'json':
 			header("Content-type: application/atom+json");
@@ -505,24 +516,26 @@ function get_public_feed($channel,$params) {
 			break;
 	}
 
-	
-	return get_feed_for($channel,get_observer_hash(),$params);
+	return get_feed_for($channel, get_observer_hash(), $params);
 }
 
-
-
-
+/**
+ * @brief
+ *
+ * @param array $channel
+ * @param string $observer_hash
+ * @param array $params
+ * @return string
+ */
 function get_feed_for($channel, $observer_hash, $params) {
 
 	if(! channel)
 		http_status_exit(401);
 
-
 	if($params['pages']) {
 		if(! perm_is_allowed($channel['channel_id'],$observer_hash,'view_pages'))
 			http_status_exit(403);
-	}
-	else {
+	} else {
 		if(! perm_is_allowed($channel['channel_id'],$observer_hash,'view_stream'))
 			http_status_exit(403);
 	}
@@ -538,7 +551,6 @@ function get_feed_for($channel, $observer_hash, $params) {
 		'top'   => $params['top']
 		), $channel, $observer_hash, CLIENT_MODE_NORMAL, get_app()->module);
 
-
 	$feed_template = get_markup_template('atom_feed.tpl');
 
 	$atom = '';
@@ -571,7 +583,8 @@ function get_feed_for($channel, $observer_hash, $params) {
 			if($item['item_private'])
 				continue;
 
-			$atom .= atom_entry($item,$type,null,$owner,true);
+			/** @BUG $owner is undefined in this call */
+			$atom .= atom_entry($item, $type, null, $owner, true);
 		}
 	}
 
@@ -604,11 +617,11 @@ function construct_activity_object($item) {
 		if($r->title)
 			$o .= '<title>' . xmlify($r->title) . '</title>' . "\r\n";
 		if($r->links) {
-			// FIXME!!
+			/** @FIXME!! */
 			if(substr($r->link,0,1) === '<') {
 				$r->link = preg_replace('/\<link(.*?)\"\>/','<link$1"/>',$r->link);
 				$o .= $r->link;
-			}					
+			}
 			else
 				$o .= '<link rel="alternate" type="text/html" href="' . xmlify($r->link) . '" />' . "\r\n";
 		}
@@ -635,7 +648,7 @@ function construct_activity_target($item) {
 		if($r->title)
 			$o .= '<title>' . xmlify($r->title) . '</title>' . "\r\n";
 		if($r->links) {
-			// FIXME !!!
+			/** @FIXME !!! */
 			if(substr($r->link,0,1) === '<') {
 				if(strstr($r->link,'&') && (! strstr($r->link,'&amp;')))
 					$r->link = str_replace('&','&amp;', $r->link);
@@ -654,12 +667,15 @@ function construct_activity_target($item) {
 	return '';
 }
 
-/* limit_body_size()
+/**
+ * @brief Limit lenght on imported system messages.
+ *
+ * The purpose of this function is to apply system message length limits to
+ * imported messages without including any embedded photos in the length.
  *
- *		The purpose of this function is to apply system message length limits to
- *		imported messages without including any embedded photos in the length
+ * @param string $body
+ * @return string|unknown
  */
-
 function limit_body_size($body) {
 
 	$maxlen = get_max_import_size();
@@ -671,7 +687,6 @@ function limit_body_size($body) {
 		$orig_body = $body;
 		$new_body = '';
 		$textlen = 0;
-		$max_found = false;
 
 		$img_start = strpos($orig_body, '[img');
 		$img_st_close = ($img_start !== false ? strpos(substr($orig_body, $img_start), ']') : false);
@@ -700,7 +715,6 @@ function limit_body_size($body) {
 				$new_body = $new_body . substr($orig_body, $img_start, $img_end - $img_start);
 			}
 			else {
-
 				if( ($textlen + $img_end) > $maxlen ) {
 					if($textlen < $maxlen) {
 						$new_body = $new_body . substr($orig_body, 0, $maxlen - $textlen);
@@ -836,12 +850,8 @@ function get_item_elements($x) {
 
 	$arr['item_flags'] = 0;
 
-
 	if(array_key_exists('flags',$x) && in_array('consensus',$x['flags']))
 		$arr['item_flags'] |= ITEM_CONSENSUS;
-
-
-
 	if(array_key_exists('flags',$x) && in_array('deleted',$x['flags']))
 		$arr['item_restrict'] |= ITEM_DELETED;
 	if(array_key_exists('flags',$x) && in_array('hidden',$x['flags']))
@@ -868,7 +878,6 @@ function get_item_elements($x) {
 			return array();
 	}
 
-
 	if($arr['sig']) {
 		$r = q("select xchan_pubkey from xchan where xchan_hash = '%s' limit 1",
 			dbesc($arr['author_xchan'])
@@ -885,7 +894,6 @@ function get_item_elements($x) {
 	// and we need plaintext to do that. 
 
 
-
 	if(intval($arr['item_private'])) {
 		$arr['item_flags'] = $arr['item_flags'] | ITEM_OBSCURED;
 		if($arr['title'])
@@ -914,7 +922,6 @@ function get_item_elements($x) {
 	}
 
 	return $arr;
-
 }
 
 
@@ -998,7 +1005,6 @@ function import_author_rss($x) {
 	}
 
 	return false;
-	
 }
 
 function import_author_unknown($x) {
@@ -1043,7 +1049,6 @@ function import_author_unknown($x) {
 	}
 
 	return false;
-	
 }
 
 function encode_item($item,$mirror = false) {
@@ -1150,7 +1155,6 @@ function encode_item($item,$mirror = false) {
 	logger('encode_item: ' . print_r($x,true), LOGGER_DATA);
 
 	return $x;
-
 }
 
 
@@ -1174,7 +1178,7 @@ function map_scope($scope,$strip = false) {
 		default:
 			return 'contacts';
 	}
-}	
+}
 
 function translate_scope($scope) {
 	if(! $scope || $scope === 'public')
@@ -1269,12 +1273,16 @@ function decode_tags($t) {
 		}
 		return $ret;
 	}
-	return '';
 
+	return '';
 }
 
-// santise a potentially complex array
-
+/**
+ * @brief Santise a potentially complex array.
+ *
+ * @param array $arr
+ * @return array|string
+ */
 function activity_sanitise($arr) {
 	if($arr) {
 		if(is_array($arr)) {
@@ -1291,11 +1299,16 @@ function activity_sanitise($arr) {
 			return htmlspecialchars($arr, ENT_COMPAT,'UTF-8', false);
 		}
 	}
+
 	return '';
 }
 
-// sanitise a simple linear array
-
+/**
+ * @brief Sanitise a simple linear array.
+ *
+ * @param array $arr
+ * @return array|string
+ */
 function array_sanitise($arr) {
 	if($arr) {
 		$ret = array();
@@ -1304,6 +1317,7 @@ function array_sanitise($arr) {
 		}
 		return $ret;
 	}
+
 	return '';
 }
 
@@ -1326,7 +1340,7 @@ function encode_item_flags($item) {
 		$ret[] = 'consensus';
 	if($item['item_private'])
 		$ret[] = 'private';
-	
+
 	return $ret;
 }
 
@@ -1419,7 +1433,6 @@ function get_mail_elements($x) {
 		return array();
 
 	return $arr;
-
 }
 
 
@@ -1448,15 +1461,17 @@ function get_profile_elements($x) {
 	$arr['keywords']     = (($x['keywords'] && is_array($x['keywords'])) ? array_sanitise($x['keywords']) : array()); 
 
 	return $arr;
-
 }
 
+/**
+ * @param object $feed
+ * @param array $item
+ * @param[out] array $author
+ * @return multitype:multitype: string NULL number Ambigous <NULL, string, number> Ambigous <mixed, string> Ambigous <multitype:multitype:string Ambigous <NULL, string>  , multitype:multitype:string unknown  > multitype:NULL unknown
+ */
+function get_atom_elements($feed, $item, &$author) {
 
-
-function get_atom_elements($feed,$item,&$author) {
-
-
-	$best_photo = array();
+	//$best_photo = array();
 
 	$res = array();
 
@@ -1531,7 +1546,7 @@ function get_atom_elements($feed,$item,&$author) {
 		if($rawmedia && $rawmedia[0]['attribs']['']['url']) {
 			$author['author_photo'] = strip_tags(unxmlify($rawmedia[0]['attribs']['']['url']));
 		}
-	}		   
+	}
 
 
 	// No photo/profile-link on the item - look at the feed level
@@ -1573,9 +1588,9 @@ function get_atom_elements($feed,$item,&$author) {
 	$apps = $item->get_item_tags(NAMESPACE_STATUSNET,'notice_info');
 	if($apps && $apps[0]['attribs']['']['source']) {
 		$res['app'] = strip_tags(unxmlify($apps[0]['attribs']['']['source']));
-	}		   
+	}
 
-	/**
+	/*
 	 * If there's a copy of the body content which is guaranteed to have survived mangling in transit, use it.
 	 */
 
@@ -1593,10 +1608,8 @@ function get_atom_elements($feed,$item,&$author) {
 		// create a term table item for them. For now just make sure they stay as links.
 
 		$res['body'] = preg_replace('/\[bookmark(.*?)\](.*?)\[\/bookmark\]/','[url$1]$2[/url]',$res['body']);
-
 	}
 
-	
 	$res['body'] = limit_body_size($res['body']);
 
 	// It isn't certain at this point whether our content is plaintext or html and we'd be foolish to trust 
@@ -1620,8 +1633,6 @@ function get_atom_elements($feed,$item,&$author) {
 		$res['body'] = purify_html($res['body']);
 
 		$res['body'] = @html2bbcode($res['body']);
-
-
 	}
 	elseif(! $have_real_body) {
 
@@ -1652,7 +1663,6 @@ function get_atom_elements($feed,$item,&$author) {
 		);
 	}
 
-
 	$private = $item->get_item_tags(NAMESPACE_DFRN,'private');
 	if($private && intval($private[0]['data']) > 0)
 		$res['item_private'] = ((intval($private[0]['data'])) ? 1 : 0);
@@ -1663,12 +1673,10 @@ function get_atom_elements($feed,$item,&$author) {
 	if($rawlocation)
 		$res['location'] = unxmlify($rawlocation[0]['data']);
 
-
 	$rawcreated = $item->get_item_tags(SIMPLEPIE_NAMESPACE_ATOM_10,'published');
 	if($rawcreated)
 		$res['created'] = unxmlify($rawcreated[0]['data']);
 
-
 	$rawedited = $item->get_item_tags(SIMPLEPIE_NAMESPACE_ATOM_10,'updated');
 	if($rawedited)
 		$res['edited'] = unxmlify($rawedited[0]['data']);
@@ -1735,7 +1743,7 @@ function get_atom_elements($feed,$item,&$author) {
 	}
 
 	// translate OStatus unfollow to activity streams if it happened to get selected
-		
+
 	if((x($res,'verb')) && ($res['verb'] === 'http://ostatus.org/schema/1.0/unfollow'))
 		$res['verb'] = ACTIVITY_UNFOLLOW;
 
@@ -1765,7 +1773,7 @@ function get_atom_elements($feed,$item,&$author) {
 					'url'   => $termurl,
 					'term'  => $termterm,
 				);
-			}		
+			}
 		}
 	}
 
@@ -1790,6 +1798,7 @@ function get_atom_elements($feed,$item,&$author) {
 				$title = ' ';
 			if(! $type)
 				$type = 'application/octet-stream';
+
 			$res['attach'][] = array('href' => $link, 'length' => $len, 'type' => $type, 'title' => $title );
 		}
 	}
@@ -1817,10 +1826,8 @@ function get_atom_elements($feed,$item,&$author) {
 			// preserve a copy of the original body content in case we later need to parse out any microformat information, e.g. events
 			$obj['orig'] = xmlify($body);
 			if((strpos($body,'<') !== false) || (strpos($body,'>') !== false)) {
-
 				$body = purify_html($body);
 				$body = html2bbcode($body);
-
 			}
 
 			$obj['content'] = $body;
@@ -1838,7 +1845,7 @@ function get_atom_elements($feed,$item,&$author) {
 		if($child[NAMESPACE_ACTIVITY]['obj_type'][0]['data']) {
 			$res['tgt_type'] = $child[NAMESPACE_ACTIVITY]['obj_type'][0]['data'];
 			$obj['type'] = $child[NAMESPACE_ACTIVITY]['obj_type'][0]['data'];
-		}	
+		}
 		if(x($child[SIMPLEPIE_NAMESPACE_ATOM_10], 'id') && $child[SIMPLEPIE_NAMESPACE_ATOM_10]['id'][0]['data'])
 			$obj['id'] = $child[SIMPLEPIE_NAMESPACE_ATOM_10]['id'][0]['data'];
 		if(x($child[SIMPLEPIE_NAMESPACE_ATOM_10], 'link') && $child[SIMPLEPIE_NAMESPACE_ATOM_10]['link'])
@@ -1849,13 +1856,12 @@ function get_atom_elements($feed,$item,&$author) {
 			$body = $child[SIMPLEPIE_NAMESPACE_ATOM_10]['content'][0]['data'];
 			if(! $body)
 				$body = $child[SIMPLEPIE_NAMESPACE_ATOM_10]['summary'][0]['data'];
+
 			// preserve a copy of the original body content in case we later need to parse out any microformat information, e.g. events
 			$obj['orig'] = xmlify($body);
 			if((strpos($body,'<') !== false) || (strpos($body,'>') !== false)) {
-
 				$body = purify_html($body);
 				$body = html2bbcode($body);
-
 			}
 
 			$obj['content'] = $body;
@@ -1896,6 +1902,7 @@ function encode_rel_links($links) {
 			$o .= 'media:height="' . $link['attribs'][NAMESPACE_MEDIA]['height'] . '" ';
 		$o .= ' />' . "\n" ;
 	}
+
 	return xmlify($o);
 }
 
@@ -1915,7 +1922,7 @@ function item_store($arr,$allow_exec = false) {
 		return $ret;
 	}
 
-	$uplinked_comment = false;
+	//$uplinked_comment = false;
 
 	// If a page layout is provided, ensure it exists and belongs to us. 
 
@@ -1955,8 +1962,6 @@ function item_store($arr,$allow_exec = false) {
 	$arr['item_private']  = ((x($arr,'item_private'))  ? intval($arr['item_private'])        : 0 );
 	$arr['item_flags']    = ((x($arr,'item_flags'))    ? intval($arr['item_flags'])          : 0 );
 
-
-
 	// only detect language if we have text content, and if the post is private but not yet
 	// obscured, make it so.
 
@@ -1966,7 +1971,6 @@ function item_store($arr,$allow_exec = false) {
 		// apply the input filter here - if it is obscured it has been filtered already
 		$arr['body'] = z_input_filter($arr['uid'],$arr['body'],$arr['mimetype']);
 
-
 		if(local_channel() && (! $arr['sig'])) {
 			$channel = get_app()->get_channel();
 			if($channel['channel_hash'] === $arr['author_xchan']) {
@@ -1995,7 +1999,6 @@ function item_store($arr,$allow_exec = false) {
 			if($arr['body'])
 				$arr['body']  = json_encode(crypto_encapsulate($arr['body'],$key));
 		}
-
 	}
 
 	if((x($arr,'object')) && is_array($arr['object'])) {
@@ -2042,13 +2045,12 @@ function item_store($arr,$allow_exec = false) {
 	$arr['public_policy'] = ((x($arr,'public_policy')) ? notags(trim($arr['public_policy']))  : '' );
 
 	$arr['comment_policy'] = ((x($arr,'comment_policy')) ? notags(trim($arr['comment_policy']))  : 'contacts' );
-	
+
 	$arr['item_unseen'] = ((array_key_exists('item_unseen',$arr)) ? intval($arr['item_unseen']) : 1);
 
 	if($arr['comment_policy'] == 'none')
 		$arr['item_flags'] = $arr['item_flags'] | ITEM_NOCOMMENT;
 
-
 	// handle time travelers
 	// Allow a bit of fudge in case somebody just has a slightly slow/fast clock
 
@@ -2062,8 +2064,6 @@ function item_store($arr,$allow_exec = false) {
 	if(! $arr['plink'])
 		$arr['plink'] = $arr['llink'];
 
-
-
 	if($arr['parent_mid'] === $arr['mid']) {
 		$parent_id = 0;
 		$parent_deleted = 0;
@@ -2134,13 +2134,12 @@ function item_store($arr,$allow_exec = false) {
 			if($r[0]['item_flags'] & ITEM_WALL)
 				$arr['item_flags'] = $arr['item_flags'] | ITEM_WALL; 
 
-
 			// An uplinked comment might arrive with a downstream owner.
 			// Fix it.
 
 			if($r[0]['owner_xchan'] !== $arr['owner_xchan']) {
 				$arr['owner_xchan'] = $r[0]['owner_xchan'];
-				$uplinked_comment = true;
+//				$uplinked_comment = true;
 			}
 
 			// if the parent is private, force privacy for the entire conversation
@@ -2164,8 +2163,7 @@ function item_store($arr,$allow_exec = false) {
 
 	if($parent_deleted)
 		$arr['item_restrict'] = $arr['item_restrict'] | ITEM_DELETED;
-	
-	
+
 	$r = q("SELECT `id` FROM `item` WHERE `mid` = '%s' AND `uid` = %d LIMIT 1",
 		dbesc($arr['mid']),
 		intval($arr['uid'])
@@ -2270,7 +2268,7 @@ function item_store($arr,$allow_exec = false) {
 		}
 
 		$arr['term'] = $terms;
-	}	
+	}
 
 	call_hooks('post_remote_end',$arr);
 
@@ -2337,7 +2335,7 @@ function item_store_update($arr,$allow_exec = false) {
 		logger('item_store_update: original post not found: ' . $orig_post_id);
 		$ret['message'] = 'no original';
 		return $ret;
-	}		
+	}
 
 	// override the unseen flag with the original
 
@@ -2350,13 +2348,12 @@ function item_store_update($arr,$allow_exec = false) {
 	if($orig[0]['item_flags'] & ITEM_OBSCURED)
 		$orig[0]['item_flags'] = $orig[0]['item_flags'] ^ ITEM_OBSCURED;
 
-
 	$arr['item_flags'] = intval($arr['item_flags']) | $orig[0]['item_flags'];
 	$arr['item_restrict'] = intval($arr['item_restrict']) | $orig[0]['item_restrict'];
 
-
 	if(array_key_exists('edit',$arr))
-		unset($arr['edit']);	
+		unset($arr['edit']);
+
 	$arr['mimetype']      = ((x($arr,'mimetype'))      ? notags(trim($arr['mimetype']))      : 'text/bbcode');
 
 	if(($arr['mimetype'] == 'application/x-php') && (! $allow_exec)) {
@@ -2365,19 +2362,19 @@ function item_store_update($arr,$allow_exec = false) {
 		return $ret;
 	}
 
-    if(! ($arr['item_flags'] & ITEM_OBSCURED)) {
+	if(! ($arr['item_flags'] & ITEM_OBSCURED)) {
 
 		$arr['lang'] = detect_language($arr['body']);
-        // apply the input filter here - if it is obscured it has been filtered already
-        $arr['body'] = z_input_filter($arr['uid'],$arr['body'],$arr['mimetype']);
-
-        if(local_channel() && (! $arr['sig'])) {
-            $channel = get_app()->get_channel();
-            if($channel['channel_hash'] === $arr['author_xchan']) {
-                $arr['sig'] = base64url_encode(rsa_sign($arr['body'],$channel['channel_prvkey']));
-                $arr['item_flags'] |= ITEM_VERIFIED;
-            }
-        }
+		// apply the input filter here - if it is obscured it has been filtered already
+		$arr['body'] = z_input_filter($arr['uid'],$arr['body'],$arr['mimetype']);
+
+		if(local_channel() && (! $arr['sig'])) {
+			$channel = get_app()->get_channel();
+			if($channel['channel_hash'] === $arr['author_xchan']) {
+				$arr['sig'] = base64url_encode(rsa_sign($arr['body'],$channel['channel_prvkey']));
+				$arr['item_flags'] |= ITEM_VERIFIED;
+			}
+		}
 
 		$allowed_languages = get_pconfig($arr['uid'],'system','allowed_languages');
 	
@@ -2392,17 +2389,15 @@ function item_store_update($arr,$allow_exec = false) {
 			$arr = $translate['item'];
 		}
 		if($arr['item_private']) {
-            $key = get_config('system','pubkey');
-            $arr['item_flags'] = $arr['item_flags'] | ITEM_OBSCURED;
-            if($arr['title'])
-                $arr['title'] = json_encode(crypto_encapsulate($arr['title'],$key));
-            if($arr['body'])
-                $arr['body']  = json_encode(crypto_encapsulate($arr['body'],$key));
-        }
-
+			$key = get_config('system','pubkey');
+			$arr['item_flags'] = $arr['item_flags'] | ITEM_OBSCURED;
+			if($arr['title'])
+				$arr['title'] = json_encode(crypto_encapsulate($arr['title'],$key));
+			if($arr['body'])
+				$arr['body']  = json_encode(crypto_encapsulate($arr['body'],$key));
+		}
 	}
 
-
 	if((x($arr,'object')) && is_array($arr['object'])) {
 		activity_sanitise($arr['object']);
 		$arr['object'] = json_encode($arr['object']);
@@ -2418,7 +2413,6 @@ function item_store_update($arr,$allow_exec = false) {
 		$arr['attach'] = json_encode($arr['attach']);
 	}
 
-
 	unset($arr['id']);
 	unset($arr['uid']);
 	unset($arr['aid']);
@@ -2465,15 +2459,13 @@ function item_store_update($arr,$allow_exec = false) {
 	$arr['app']           = ((x($arr,'app'))           ? notags(trim($arr['app']))           : $orig[0]['app']);
 //	$arr['item_restrict'] = ((x($arr,'item_restrict')) ? intval($arr['item_restrict'])       : $orig[0]['item_restrict'] );
 //	$arr['item_flags']    = ((x($arr,'item_flags'))    ? intval($arr['item_flags'])          : $orig[0]['item_flags'] );
-	
+
 	$arr['sig']           = ((x($arr,'sig'))           ? $arr['sig']                         : '');
 	$arr['layout_mid']    = ((array_key_exists('layout_mid',$arr)) ? dbesc($arr['layout_mid'])           : $orig[0]['layout_mid'] );
 
 	$arr['public_policy'] = ((x($arr,'public_policy')) ? notags(trim($arr['public_policy']))  : $orig[0]['public_policy'] );
 	$arr['comment_policy'] = ((x($arr,'comment_policy')) ? notags(trim($arr['comment_policy']))  : $orig[0]['comment_policy'] );
 
-
-
 	call_hooks('post_remote_update',$arr);
 
 	if(x($arr,'cancel')) {
@@ -2495,11 +2487,11 @@ function item_store_update($arr,$allow_exec = false) {
 	logger('item_store_update: ' . print_r($arr,true), LOGGER_DATA);
 
 	$str = '';
-		foreach($arr as $k => $v) {
-			if($str)
-				$str .= ",";
-			$str .= " `" . $k . "` = '" . $v . "' ";
-		} 
+	foreach($arr as $k => $v) {
+		if($str)
+			$str .= ",";
+		$str .= " `" . $k . "` = '" . $v . "' ";
+	} 
 
 	$r = dbq("update `item` set " . $str . " where id = " . $orig_post_id );
 
@@ -2530,7 +2522,7 @@ function item_store_update($arr,$allow_exec = false) {
 		}
 
 		$arr['term'] = $terms;
-	}	
+	}
 
 	call_hooks('post_remote_update_end',$arr);
 
@@ -2568,8 +2560,9 @@ function store_diaspora_comment_sig($datarray, $channel, $parent_item, $post_id,
 
 	$signed_text = $datarray['mid'] . ';' . $parent_item['mid'] . ';' . $signed_body . ';' . $diaspora_handle;
 
+	/** @FIXME $uprvkey is undefined, do we still need this if-statement? */
 	if( $uprvkey !== false )
-		$authorsig = base64_encode(rsa_sign($signed_text,$channel['channel_prvkey'],'sha256'));
+		$authorsig = base64_encode(rsa_sign($signed_text, $channel['channel_prvkey'], 'sha256'));
 	else
 		$authorsig = '';
 
@@ -2630,7 +2623,6 @@ function send_status_notifications($post_id,$item) {
 
 	$link =  get_app()->get_baseurl() . '/display/' . $item['mid'];
 
-
 	$y = q("select id from notify where link = '%s' and uid = %d limit 1",
 		dbesc($link),
 		intval($item['uid'])
@@ -2641,50 +2633,50 @@ function send_status_notifications($post_id,$item) {
 
 	if(! $notify)
 		return;
+
 	require_once('include/enotify.php');
 	notification(array(
 		'type'         => NOTIFY_COMMENT,
 		'from_xchan'   => $item['author_xchan'],
 		'to_xchan'     => $r[0]['channel_hash'],
 		'item'         => $item,
-		'link'		   => $link,
+		'link'         => $link,
 		'verb'         => ACTIVITY_POST,
 		'otype'        => 'item',
 		'parent'       => $parent,
 		'parent_mid'   => $item['parent_mid']
 	));
-	return;
 }
 
 
-
-
-
-
 function get_item_contact($item,$contacts) {
 	if(! count($contacts) || (! is_array($item)))
 		return false;
+
 	foreach($contacts as $contact) {
 		if($contact['id'] == $item['contact-id']) {
 			return $contact;
 			break; // NOTREACHED
 		}
 	}
+
 	return false;
 }
 
-
-function tag_deliver($uid,$item_id) {
-
-	// Called when we deliver things that might be tagged in ways that require delivery processing.
-	// Handles community tagging of posts and also look for mention tags 
-	// and sets up a second delivery chain if appropriate
-
-	$a = get_app();
+/**
+ * @brief Called when we deliver things that might be tagged in ways that require delivery processing.
+ *
+ * Handles community tagging of posts and also look for mention tags and sets up
+ * a second delivery chain if appropriate.
+ *
+ * @param int $uid
+ * @param int $item_id
+ */
+function tag_deliver($uid, $item_id) {
 
 	$mention = false;
 
-	/**
+	/*
 	 * Fetch stuff we need - a channel and an item
 	 */
 
@@ -2693,7 +2685,7 @@ function tag_deliver($uid,$item_id) {
 	);
 	if(! $u)
 		return;
-		
+
 	$i = q("select * from item where id = %d and uid = %d limit 1",
 		intval($item_id),
 		intval($uid)
@@ -2713,8 +2705,7 @@ function tag_deliver($uid,$item_id) {
 		return;
 	}
 
-
-	/**
+	/*
 	 * Seems like a good place to plug in a poke notification.
 	 */
 
@@ -2722,7 +2713,7 @@ function tag_deliver($uid,$item_id) {
 		$poke_notify = true;
 
 		if(($item['obj_type'] == "") || ($item['obj_type'] !== ACTIVITY_OBJ_PERSON) || (! $item['object'])) 
-				$poke_notify = false;
+			$poke_notify = false;
 
 		$obj = json_decode_plus($item['object']);
 		if($obj) {
@@ -2732,7 +2723,6 @@ function tag_deliver($uid,$item_id) {
 		if($item['item_restrict'] & ITEM_DELETED)
 			$poke_notify = false;
 
-
 		$verb = urldecode(substr($item['verb'],strpos($item['verb'],'#')+1));
 		if($poke_notify) {
 			require_once('include/enotify.php');
@@ -2749,7 +2739,7 @@ function tag_deliver($uid,$item_id) {
 		}
 	}
 
-	/**
+	/*
 	 * Do community tagging
 	 */
 
@@ -2783,7 +2773,7 @@ function tag_deliver($uid,$item_id) {
 							dbesc(datetime_convert()),
 							dbesc($j_tgt['id']),
 							intval($u[0]['channel_id'])
-						);		
+						);
 						proc_run('php','include/notifier.php','edit_post',$p[0]['id']);
 					}
 				}
@@ -2793,7 +2783,7 @@ function tag_deliver($uid,$item_id) {
 			logger('tag_deliver: tag permission denied for ' . $u[0]['channel_address']);
 	}
 
-	/**
+	/*
 	 * A "union" is a message which our channel has sourced from another channel.
 	 * This sets up a second delivery chain just like forum tags do.
 	 * Find out if this is a source-able post.
@@ -2819,11 +2809,10 @@ function tag_deliver($uid,$item_id) {
 	}
 
 
-	/**
+	/*
 	 * Now we've got those out of the way. Let's see if this is a post that's tagged for re-delivery
 	 */
 
-
 	$terms = get_terms_oftype($item['term'],TERM_MENTION);
 
 	if($terms)
@@ -2833,20 +2822,20 @@ function tag_deliver($uid,$item_id) {
 
 	if($terms) {
 		foreach($terms as $term) {
-			if(link_compare($term['url'],$link)) {			
+			if(link_compare($term['url'],$link)) {
 				$mention = true;
 				break;
 			}
 		}
-	}				
+	}
 
 	if($mention) {
 		logger('tag_deliver: mention found for ' . $u[0]['channel_name']);
-		
+
 		$r = q("update item set item_flags = ( item_flags | %d ) where id = %d",
 			intval(ITEM_MENTIONSME),
 			intval($item_id)
-		);			
+		);
 
 		// At this point we've determined that the person receiving this post was mentioned in it or it is a union.
 		// Now let's check if this mention was inside a reshare so we don't spam a forum
@@ -2866,6 +2855,7 @@ function tag_deliver($uid,$item_id) {
 
 		$tagged = false;
 		$plustagged = false;
+		$matches = array();
 
 		$pattern = '/@\!?\[zrl\=' . preg_quote($term['url'],'/') . '\]' . preg_quote($term['term'],'/') . '\[\/zrl\]/';
 		if(preg_match($pattern,$body,$matches)) 
@@ -2898,7 +2888,7 @@ function tag_deliver($uid,$item_id) {
 		$arr = array('channel_id' => $uid, 'item' => $item, 'body' => $body);
 		call_hooks('tagged',$arr);
 
-		/**
+		/*
 		 * Kill two birds with one stone. As long as we're here, send a mention notification.
 		 */
 
@@ -2926,7 +2916,6 @@ function tag_deliver($uid,$item_id) {
 			logger('tag_delivery denied for uid ' . $uid . ' and xchan ' . $item['author_xchan']);
 			return;
 		}
-
 	}
 
 	if((! $mention) && (! $union)) {
@@ -2948,25 +2937,18 @@ function tag_deliver($uid,$item_id) {
 
 	logger('tag_deliver: creating second delivery chain.');
 	start_delivery_chain($u[0],$item,$item_id,null);
-
 }
 
 /**
- * @function tgroup_check($uid,$item)
+ * @brief This function is called pre-deliver to see if a post matches the criteria to be tag delivered.
  *
- * This function is called pre-deliver to see if a post matches the criteria to be tag delivered.
  * We don't actually do anything except check that it matches the criteria.
  * This is so that the channel with tag_delivery enabled can receive the post even if they turn off
  * permissions for the sender to send their stream. tag_deliver() can't be called until the post is actually stored.
  * By then it would be too late to reject it. 
  */
-
-
-
 function tgroup_check($uid,$item) {
 
-	$a = get_app();
-
 	$mention = false;
 
 	// check that the message originated elsewhere and is a top-level post
@@ -2980,6 +2962,7 @@ function tgroup_check($uid,$item) {
 		);
 		if($r)
 			return true;
+
 		return false;
 	}
 	if(! perm_is_allowed($uid,$item['author_xchan'],'tag_deliver'))
@@ -3001,13 +2984,12 @@ function tgroup_check($uid,$item) {
 
 	if($terms) {
 		foreach($terms as $term) {
-			if(link_compare($term['url'],$link)) {			
+			if(link_compare($term['url'],$link)) {
 				$mention = true;
 				break;
 			}
 		}
-	}				
-
+	}
 
 	if($mention) {
 		logger('tgroup_check: mention found for ' . $u[0]['channel_name']);
@@ -3029,12 +3011,12 @@ function tgroup_check($uid,$item) {
 
 	$body = preg_replace('/\[share(.*?)\[\/share\]/','',$body);
 
-	
 //	$pattern = '/@\!?\[zrl\=' . preg_quote($term['url'],'/') . '\]' . preg_quote($term['term'] . '+','/') . '\[\/zrl\]/';
 
 	$pattern = '/@\!?\[zrl\=([^\]]*?)\]((?:.(?!\[zrl\=))*?)\+\[\/zrl\]/';
 
 	$found = false;
+	$matches = array();
 
 	if(preg_match_all($pattern,$body,$matches,PREG_SET_ORDER)) {
 		$max_forums = get_config('system','max_tagged_forums');
@@ -3059,7 +3041,6 @@ function tgroup_check($uid,$item) {
 	}
 
 	return true;
-
 }
 
 /**
@@ -3067,10 +3048,13 @@ function tgroup_check($uid,$item) {
  * receiving the post. This starts the second delivery chain, by resetting permissions and ensuring 
  * that ITEM_UPLINK is set on the parent post, and storing the current owner_xchan as the source_xchan. 
  * We'll become the new owner. If called without $parent, this *is* the parent post.
+ *
+ * @param array $channel
+ * @param array $item
+ * @param int $item_id
+ * @param boolean $parent
  */
-
-function start_delivery_chain($channel,$item,$item_id,$parent) {
-
+function start_delivery_chain($channel, $item, $item_id, $parent) {
 
 	// Change this copy of the post to a forum head message and deliver to all the tgroup members
 	// also reset all the privacy bits to the forum default permissions
@@ -3093,7 +3077,6 @@ function start_delivery_chain($channel,$item,$item_id,$parent) {
 	if(! $parent)
 		$flag_bits = $flag_bits | ITEM_ORIGIN;
 
-
 	// unset the nocomment bit if it's there. 
 
 	if($flag_bits & ITEM_NOCOMMENT)
@@ -3113,7 +3096,7 @@ function start_delivery_chain($channel,$item,$item_id,$parent) {
 		$r = q("update item set source_xchan = owner_xchan where id = %d",
 			intval($item_id)
 		);
-	} 
+	}
 
 	$title = $item['title'];
 	$body  = $item['body'];
@@ -3155,39 +3138,28 @@ function start_delivery_chain($channel,$item,$item_id,$parent) {
 		intval($item_id)
 	);
 
-
-
 	if($r)
 		proc_run('php','include/notifier.php','tgroup',$item_id);
 	else
-		logger('start_delivery_chain: failed to update item');			
-
-	return;
+		logger('start_delivery_chain: failed to update item');
 }
 
-
-
 /**
- * @function check_item_source($uid,$item)
- * @param $uid
- * @param $item
+ * @brief
  *
- * @description
  * Checks to see if this item owner is referenced as a source for this channel and if the post 
  * matches the rules for inclusion in this channel. Returns true if we should create a second delivery
  * chain and false if none of the rules apply, or if the item is private.
+ *
+ * @param int $uid
+ * @param array $item
  */
- 
-
-function check_item_source($uid,$item) {
-
-
+function check_item_source($uid, $item) {
 	$r = q("select * from source where src_channel_id = %d and ( src_xchan = '%s' or src_xchan = '*' ) limit 1",
 		intval($uid),
 		dbesc(($item['source_xchan']) ?  $item['source_xchan'] : $item['owner_xchan'])
 	);
 
-
 	if(! $r)
 		return false;
 
@@ -3196,18 +3168,15 @@ function check_item_source($uid,$item) {
 		dbesc($item['owner_xchan'])
 	);
 
-			
 	if(! $x)
 		return false;
 
-
 	if(! ($x[0]['abook_their_perms'] & PERMS_A_REPUBLISH))
 		return false;
 
 	if($item['item_private'] && (! ($x[0]['abook_flags'] & ABOOK_FLAG_FEED)))
 		return false;
 
-
 	if($r[0]['src_channel_xchan'] === $item['owner_xchan'])
 		return false;
 
@@ -3218,6 +3187,7 @@ function check_item_source($uid,$item) {
 	$text = prepare_text($item['body'],$item['mimetype']);
 	$text = html2plain($text);
 
+	/** @BUG $items is undefined, should this be $item? */
 	$tags = ((count($items['term'])) ? $items['term'] : false);
 
 	$words = explode("\n",$r[0]['src_patt']);
@@ -3232,12 +3202,11 @@ function check_item_source($uid,$item) {
 				return true;
 		}
 	}
+
 	return false;
 }
 
 
-
-
 function mail_store($arr) {
 
 	if(! $arr['channel_id']) {
@@ -3262,7 +3231,6 @@ function mail_store($arr) {
 	$arr['body']          = ((x($arr,'body'))          ? trim($arr['body'])                  : '');
 
 	$arr['mail_flags']    = ((x($arr,'mail_flags'))    ? intval($arr['mail_flags'])          : 0 );
-	
 
 	if(! $arr['parent_mid']) {
 		logger('mail_store: missing parent');
@@ -3328,9 +3296,9 @@ function mail_store($arr) {
 			'type'       => NOTIFY_MAIL,
 			'item'       => $arr,
 			'verb'       => ACTIVITY_POST,
-		    'otype'      => 'mail'
+			'otype'      => 'mail'
 		);
-			
+
 		notification($notif_params);
 	}
 
@@ -3338,35 +3306,35 @@ function mail_store($arr) {
 	return $current_post;
 }
 
-
 /**
+ * @brief Process atom feed and update anything/everything we might need to update.
  *
- * consume_feed - process atom feed and update anything/everything we might need to update
- *
- * $xml = the (atom) feed to consume - RSS isn't as fully supported but may work for simple feeds.
- *
- * $importer = the contact_record (joined to user_record) of the local user who owns this relationship.
- *             It is this person's stuff that is going to be updated.
- * $contact =  the person who is sending us stuff. If not set, we MAY be processing a "follow" activity
- *             from an external network and MAY create an appropriate contact record. Otherwise, we MUST 
- *             have a contact record.
  * $hub = should we find a hub declation in the feed, pass it back to our calling process, who might (or 
  *        might not) try and subscribe to it.
  * $datedir sorts in reverse order
- * $pass - by default ($pass = 0) we cannot guarantee that a parent item has been 
- *      imported prior to its children being seen in the stream unless we are certain
- *      of how the feed is arranged/ordered.
- * With $pass = 1, we only pull parent items out of the stream.
- * With $pass = 2, we only pull children (comments/likes).
+ *
+ * @param array $xml
+ *   The (atom) feed to consume - RSS isn't as fully supported but may work for simple feeds.
+ * @param $importer
+ *   The contact_record (joined to user_record) of the local user who owns this
+ *   relationship. It is this person's stuff that is going to be updated.
+ * @param $contact
+ *   The person who is sending us stuff. If not set, we MAY be processing a "follow" activity
+ *   from an external network and MAY create an appropriate contact record. Otherwise, we MUST 
+ *   have a contact record.
+ * @param int $pass by default ($pass = 0) we cannot guarantee that a parent item has been 
+ *   imported prior to its children being seen in the stream unless we are certain
+ *   of how the feed is arranged/ordered.
+ *  * With $pass = 1, we only pull parent items out of the stream.
+ *  * With $pass = 2, we only pull children (comments/likes).
  *
  * So running this twice, first with pass 1 and then with pass 2 will do the right
  * thing regardless of feed ordering. This won't be adequate in a fully-threaded
  * model where comments can have sub-threads. That would require some massive sorting
  * to get all the feed items into a mostly linear ordering, and might still require
- * recursion.  
+ * recursion.
  */
-
-function consume_feed($xml,$importer,&$contact,$pass = 0) {
+function consume_feed($xml, $importer, &$contact, $pass = 0) {
 
 	require_once('library/simplepie/simplepie.inc');
 
@@ -3403,7 +3371,6 @@ function consume_feed($xml,$importer,&$contact,$pass = 0) {
 					$when = datetime_convert('UTC','UTC','now','Y-m-d H:i:s');
 			}
 
-
 			if($deleted && is_array($contact)) {
 				$r = q("SELECT * from item where mid = '%s' and author_xchan = '%s' and uid = %d limit 1",
 					dbesc(base64url_encode($mid)),
@@ -3418,7 +3385,7 @@ function consume_feed($xml,$importer,&$contact,$pass = 0) {
 						logger('consume_feed: deleting item ' . $item['id'] . ' mid=' . base64url_decode($item['mid']), LOGGER_DEBUG);
 						drop_item($item['id'],false);
 					}
-				}	
+				}
 			}
 		}
 	}
@@ -3449,7 +3416,6 @@ function consume_feed($xml,$importer,&$contact,$pass = 0) {
 				if($pass == 1)
 					continue;
 
-
 				// Have we seen it? If not, import it.
 
 				$item_id  = base64url_encode($item->get_id());
@@ -3469,15 +3435,12 @@ function consume_feed($xml,$importer,&$contact,$pass = 0) {
 					$x = import_author_unknown(array('name' => $author['author_name'],'url' => $author['author_link'],'photo' => array('src' => $author['author_photo'])));
 					if($x) 
 						$datarray['author_xchan'] = $x;
-					
 				}
 				if(! $datarray['author_xchan'])
 					$datarray['author_xchan'] = $contact['xchan_hash'];
 
-
 				$datarray['owner_xchan'] = $contact['xchan_hash'];
 
-
 				$r = q("SELECT edited FROM item WHERE mid = '%s' AND uid = %d LIMIT 1",
 					dbesc($item_id),
 					intval($importer['channel_id'])
@@ -3501,15 +3464,12 @@ function consume_feed($xml,$importer,&$contact,$pass = 0) {
 				$datarray['parent_mid'] = $parent_mid;
 				$datarray['uid'] = $importer['channel_id'];
 
-
-
 				logger('consume_feed: ' . print_r($datarray,true),LOGGER_DATA);
 
 				$xx = item_store($datarray);
 				$r = $xx['item_id'];
 				continue;
 			}
-
 			else {
 
 				// Head post of a conversation. Have we seen it? If not, import it.
@@ -3538,15 +3498,12 @@ function consume_feed($xml,$importer,&$contact,$pass = 0) {
 					$x = import_author_unknown(array('name' => $author['author_name'],'url' => $author['author_link'],'photo' => array('src' => $author['author_photo'])));
 					if($x) 
 						$datarray['author_xchan'] = $x;
-					
 				}
 				if(! $datarray['author_xchan'])
 					$datarray['author_xchan'] = $contact['xchan_hash'];
 
-
 				$datarray['owner_xchan'] = $contact['xchan_hash'];
 
-
 				$r = q("SELECT edited FROM item WHERE mid = '%s' AND uid = %d LIMIT 1",
 					dbesc($item_id),
 					intval($importer['channel_id'])
@@ -3568,7 +3525,6 @@ function consume_feed($xml,$importer,&$contact,$pass = 0) {
 					continue;
 				}
 
-
 				$datarray['parent_mid'] = $item_id;
 				$datarray['uid'] = $importer['channel_id'];
 
@@ -3581,24 +3537,18 @@ function consume_feed($xml,$importer,&$contact,$pass = 0) {
 
 				logger('consume_feed: author ' . print_r($author,true),LOGGER_DEBUG); 
 
-
 				logger('consume_feed: ' . print_r($datarray,true),LOGGER_DATA);
 
 				$xx = item_store($datarray);
 				$r = $xx['item_id'];
 				continue;
-
 			}
 		}
 	}
-
-
 }
 
 function update_feed_item($uid,$datarray) {
-
 	logger('update_feed_item: not implemented! ' . $uid . ' ' . print_r($datarray,true), LOGGER_DATA);
-
 }
 
 
@@ -3608,6 +3558,7 @@ function handle_feed($uid,$abook_id,$url) {
 	$channel = channelx_by_n($uid);
 	if(! $channel)
 		return;
+
 	$x = q("select * from abook left join xchan on abook_xchan = xchan_hash where abook_id = %d and abook_channel = %d limit 1",
 		dbesc($abook_id),
 		intval($uid)
@@ -3629,13 +3580,13 @@ function atom_author($tag,$name,$uri,$h,$w,$type,$photo) {
 	$o = '';
 	if(! $tag)
 		return $o;
+
 	$name = xmlify($name);
 	$uri = xmlify($uri);
 	$h = intval($h);
 	$w = intval($w);
 	$photo = xmlify($photo);
 
-
 	$o .= "<$tag>\r\n";
 	$o .= "<name>$name</name>\r\n";
 	$o .= "<uri>$uri</uri>\r\n";
@@ -3645,13 +3596,12 @@ function atom_author($tag,$name,$uri,$h,$w,$type,$photo) {
 	call_hooks('atom_author', $o);
 
 	$o .= "</$tag>\r\n";
+
 	return $o;
 }
 
 function atom_entry($item,$type,$author,$owner,$comment = false,$cid = 0) {
 
-	$a = get_app();
-
 	if(! $item['parent'])
 		return;
 
@@ -3664,7 +3614,6 @@ function atom_entry($item,$type,$author,$owner,$comment = false,$cid = 0) {
 	else
 		$body = $item['body'];
 
-
 	$o = "\r\n\r\n<entry>\r\n";
 
 	if(is_array($author))
@@ -3698,11 +3647,9 @@ function atom_entry($item,$type,$author,$owner,$comment = false,$cid = 0) {
 	if(($item['item_private']) || strlen($item['allow_cid']) || strlen($item['allow_gid']) || strlen($item['deny_cid']) || strlen($item['deny_gid']))
 		$o .= '<zot:private>' . (($item['item_private']) ? $item['item_private'] : 1) . '</zot:private>' . "\r\n";
 
-
 	if($item['app'])
 		$o .= '<statusnet:notice_info local_id="' . $item['id'] . '" source="' . xmlify($item['app']) . '" ></statusnet:notice_info>' . "\r\n";
 
-
 	$verb = construct_verb($item);
 	$o .= '<as:verb>' . xmlify($verb) . '</as:verb>' . "\r\n";
 	$actobj = construct_activity_object($item);
@@ -3730,7 +3677,7 @@ function atom_entry($item,$type,$author,$owner,$comment = false,$cid = 0) {
 	call_hooks('atom_entry', $o);
 
 	$o .= '</entry>' . "\r\n";
-	
+
 	return $o;
 }
 
@@ -3753,7 +3700,6 @@ function fix_private_photos($s, $uid, $item = null, $cid = 0) {
 
 		logger('fix_private_photos: found photo ' . $image, LOGGER_DEBUG);
 
-
 		if(stristr($image , $site . '/photo/')) {
 			// Only embed locally hosted photos
 			$replace = false;
@@ -3815,7 +3761,7 @@ function fix_private_photos($s, $uid, $item = null, $cid = 0) {
 					}
 				}
 			}
-		}	
+		}
 
 		$new_body = $new_body . substr($orig_body, 0, $img_start + $img_st_close) . $image . '[/zmg]';
 		$orig_body = substr($orig_body, $img_start + $img_st_close + $img_len + strlen('[/zmg]'));
@@ -3836,6 +3782,7 @@ function fix_private_photos($s, $uid, $item = null, $cid = 0) {
 function has_permissions($obj) {
 	if(($obj['allow_cid'] != '') || ($obj['allow_gid'] != '') || ($obj['deny_cid'] != '') || ($obj['deny_gid'] != ''))
 		return true;
+
 	return false;
 }
 
@@ -3858,10 +3805,15 @@ function compare_permissions($obj1,$obj2) {
 	return false;
 }
 
-// returns an array of contact-ids that are allowed to see this object
-
+/**
+ * @brief Returns an array of contact-ids that are allowed to see this object.
+ *
+ * @param object $obj
+ * @return array
+ */
 function enumerate_permissions($obj) {
 	require_once('include/group.php');
+
 	$allow_people = expand_acl($obj['allow_cid']);
 	$allow_groups = expand_groups(expand_acl($obj['allow_gid']));
 	$deny_people  = expand_acl($obj['deny_cid']);
@@ -3869,6 +3821,7 @@ function enumerate_permissions($obj) {
 	$recipients   = array_unique(array_merge($allow_people,$allow_groups));
 	$deny         = array_unique(array_merge($deny_people,$deny_groups));
 	$recipients   = array_diff($recipients,$deny);
+
 	return $recipients;
 }
 
@@ -3885,6 +3838,7 @@ function item_getfeedtags($item) {
 				$ret[] = array('@',$term['url'],$term['term']);
 		}
 	}
+
 	return $ret;
 }
 
@@ -3905,11 +3859,11 @@ function item_getfeedattach($item) {
 			}
 		}
 	}
+
 	return $ret;
 }
 
 
-	
 function item_expire($uid,$days) {
 
 	if((! $uid) || ($days < 1))
@@ -3970,7 +3924,6 @@ function item_expire($uid,$days) {
 	}
 
 //	proc_run('php',"include/notifier.php","expire","$uid");
-	
 }
 
 function retain_item($id) {
@@ -4012,7 +3965,6 @@ function drop_items($items) {
 
 function drop_item($id,$interactive = true,$stage = DROPITEM_NORMAL,$force = false) {
 
-
 	$a = get_app();
 
 	// locate item to be deleted
@@ -4057,7 +4009,6 @@ function drop_item($id,$interactive = true,$stage = DROPITEM_NORMAL,$force = fal
 			intval($item['id'])
 		);
 
-
 		$arr = array('item' => $item, 'interactive' => $interactive, 'stage' => $stage);
 		call_hooks('drop_item', $arr );
 
@@ -4089,7 +4040,6 @@ function drop_item($id,$interactive = true,$stage = DROPITEM_NORMAL,$force = fal
 			proc_run('php','include/notifier.php','drop',$notify_id);
 
 		goaway($a->get_baseurl() . '/' . $_SESSION['return_url']);
-
 	}
 	else {
 		if(! $interactive)
@@ -4097,14 +4047,20 @@ function drop_item($id,$interactive = true,$stage = DROPITEM_NORMAL,$force = fal
 		notice( t('Permission denied.') . EOL);
 		goaway($a->get_baseurl() . '/' . $_SESSION['return_url']);
 	}
-	
 }
 
-// This function does not check for permission and does not send notifications and does not check recursion.
-// It merely destroys all resources associated with an item. 
-// Please do not use without a suitable wrapper.
-
-function delete_item_lowlevel($item,$stage = DROPITEM_NORMAL,$force = false) {
+/**
+ * @warning This function does not check for permission and does not send
+ * notifications and does not check recursion.
+ * It merely destroys all resources associated with an item.
+ * Please do not use without a suitable wrapper.
+ *
+ * @param array $item
+ * @param int $stage
+ * @param boolean $force
+ * @return boolean
+ */
+function delete_item_lowlevel($item, $stage = DROPITEM_NORMAL, $force = false) {
 
 	$linked_item = (($item['resource_id']) ? true : false);
 
@@ -4152,7 +4108,6 @@ function delete_item_lowlevel($item,$stage = DROPITEM_NORMAL,$force = false) {
 			break;
 	}
 
-
 	// immediately remove any undesired profile likes. 
 
 	q("delete from likes where iid = %d and channel_id = %d",
@@ -4160,7 +4115,6 @@ function delete_item_lowlevel($item,$stage = DROPITEM_NORMAL,$force = false) {
 		intval($item['uid'])
 	);
 
-
 	// network deletion request. Keep the message structure so that we can deliver delete notifications.
 	// Come back after several days (or perhaps a month) to do the lowlevel delete (DROPITEM_PHASE2).
 
@@ -4182,7 +4136,7 @@ function delete_item_lowlevel($item,$stage = DROPITEM_NORMAL,$force = false) {
 		intval(TERM_OBJ_POST)
 	);
 
-	// FIXME remove notifications for this item
+	/** @FIXME remove notifications for this item */
 
 	return true;
 }
@@ -4203,6 +4157,7 @@ function first_post_date($uid,$wall = false) {
 //		logger('first_post_date: ' . $r[0]['id'] . ' ' . $r[0]['created'], LOGGER_DATA);
 		return substr(datetime_convert('',date_default_timezone_get(),$r[0]['created']),0,10);
 	}
+
 	return false;
 }
 
@@ -4210,15 +4165,19 @@ function first_post_date($uid,$wall = false) {
  * modified posted_dates() {below} to arrange the list in years, which we'll eventually 
  * use to make a menu of years with collapsible sub-menus for the months instead of the 
  * current flat list of all representative dates.
+ *
+ * @param int $uid
+ * @param unknown $wall
+ * @param unknown $mindate
+ * @return array
  */
-
-function list_post_dates($uid,$wall,$mindate) {
+function list_post_dates($uid, $wall, $mindate) {
 	$dnow = datetime_convert('',date_default_timezone_get(),'now','Y-m-d');
 
 	if($mindate)
-		$dthen = datetime_convert('',date_default_timezone_get(),$mindate);
+		$dthen = datetime_convert('',date_default_timezone_get(), $mindate);
 	else
-		$dthen = first_post_date($uid,$wall);
+		$dthen = first_post_date($uid, $wall);
 	if(! $dthen)
 		return array();
 
@@ -4245,6 +4204,7 @@ function list_post_dates($uid,$wall,$mindate) {
  		$ret[$dyear][] = array($str,$end_month,$start_month);
 		$dnow = datetime_convert('','',$dnow . ' -1 month', 'Y-m-d');
 	}
+
 	return $ret;
 }
 
@@ -4307,7 +4267,6 @@ function fetch_post_tags($items,$link = false) {
 		);
 	}
 
-
 	for($x = 0; $x < count($items); $x ++) {
 		if($tags) {
 			foreach($tags as $t) {
@@ -4338,7 +4297,6 @@ function fetch_post_tags($items,$link = false) {
 
 function zot_feed($uid,$observer_xchan,$arr) {
 
-
 	$result = array();
 	$mindate = null;
 	$message_id = null;
@@ -4351,9 +4309,9 @@ function zot_feed($uid,$observer_xchan,$arr) {
 		$message_id = $arr['message_id'];
 	}
 
-
 	if(! $mindate)
 		$mindate = NULL_DATE;
+
 	$mindate = dbesc($mindate);
 
 	logger('zot_feed: requested for uid ' . $uid . ' from observer ' . $observer_xchan, LOGGER_DEBUG);
@@ -4383,7 +4341,7 @@ function zot_feed($uid,$observer_xchan,$arr) {
 
 	$items = array();
 
-	// FIXME
+	/** @FIXME fix this part for PostgreSQL */
 
 	if(ACTIVE_DBTYPE == DBTYPE_POSTGRES) { 
 		return array();
@@ -4426,12 +4384,10 @@ function zot_feed($uid,$observer_xchan,$arr) {
 		$items = fetch_post_tags($items);
 		require_once('include/conversation.php');
 		$items = conv_sort($items,'ascending');
-
 	}
 	else
 		$items = array();
 
-
 	logger('zot_feed: number items: ' . count($items),LOGGER_DEBUG);
 
 	foreach($items as $item)
@@ -4452,13 +4408,13 @@ function items_fetch($arr,$channel = null,$observer_hash = null,$client_mode = C
 	$sql_nets = '';
 	$sql_options = '';
 	$sql_extra2 = '';
-    $sql_extra3 = '';
+	$sql_extra3 = '';
 	$def_acl = '';
 
 	$item_uids = ' true ';
-	
+
 	if ($arr['uid']) $uid= $arr['uid'];
-	
+
 	if($channel) {
 		$uid = $channel['channel_id'];
 		$uidhash = $channel['channel_hash'];
@@ -4470,65 +4426,64 @@ function items_fetch($arr,$channel = null,$observer_hash = null,$client_mode = C
 
 	if($arr['wall'])
 		$sql_options .= " and (item_flags & " . intval(ITEM_WALL) . ")>0 ";
-									
+
 	$sql_extra = " AND item.parent IN ( SELECT parent FROM item WHERE (item_flags & " . intval(ITEM_THREAD_TOP) . ")>0 $sql_options ) ";
-	
+
 	if($arr['since_id'])
-   		$sql_extra .= " and item.id > " . $since_id . " ";
-   		
-    if($arr['gid'] && $uid) {
-        $r = q("SELECT * FROM `groups` WHERE id = %d AND uid = %d LIMIT 1",
-            intval($arr['group']),
-            intval($uid)
-        );
-        if(! $r) {
+		$sql_extra .= " and item.id > " . $since_id . " ";
+
+	if($arr['gid'] && $uid) {
+		$r = q("SELECT * FROM `groups` WHERE id = %d AND uid = %d LIMIT 1",
+			intval($arr['group']),
+			intval($uid)
+		);
+		if(! $r) {
 			$result['message']  = t('Collection not found.');
 			return $result;
-        }
+		}
 
 		$contact_str = '';
-        $contacts = group_get_members($group);
-        if($contacts) {
+		/** @FIXME $group is undefined */
+		$contacts = group_get_members($group);
+		if ($contacts) {
 			foreach($contacts as $c) {
 				if($contact_str)
 					$contact_str .= ',';
-            	$contact_str .= "'" . $c['xchan'] . "'";
+
+				$contact_str .= "'" . $c['xchan'] . "'";
 			}
-        }
-        else {
+		} else {
 			$contact_str = ' 0 ';	
 			$result['message'] = t('Collection is empty.');
 			return $result;
-        }
+		}
 
-        $sql_extra = " AND item.parent IN ( SELECT DISTINCT parent FROM item WHERE true $sql_options AND (( author_xchan IN ( $contact_str ) OR owner_xchan in ( $contact_str)) or allow_gid like '" . protect_sprintf('%<' . dbesc($r[0]['hash']) . '>%') . "' ) and id = parent and item_restrict = 0 ) ";
+		$sql_extra = " AND item.parent IN ( SELECT DISTINCT parent FROM item WHERE true $sql_options AND (( author_xchan IN ( $contact_str ) OR owner_xchan in ( $contact_str)) or allow_gid like '" . protect_sprintf('%<' . dbesc($r[0]['hash']) . '>%') . "' ) and id = parent and item_restrict = 0 ) ";
 
 		$x = group_rec_byhash($uid,$r[0]['hash']);
 		$result['headline'] = sprintf( t('Collection: %s'),$x['name']);
+	}
+	elseif($arr['cid'] && $uid) {
 
-    }
-    elseif($arr['cid'] && $uid) {
-
-        $r = q("SELECT abook.*, xchan.* from abook left join xchan on abook_xchan = xchan_hash where abook_id = %d and abook_channel = %d and not ( abook_flags & " . intval(ABOOK_FLAG_BLOCKED) . ")>0 limit 1",
+		$r = q("SELECT abook.*, xchan.* from abook left join xchan on abook_xchan = xchan_hash where abook_id = %d and abook_channel = %d and not ( abook_flags & " . intval(ABOOK_FLAG_BLOCKED) . ")>0 limit 1",
 			intval($arr['cid']),
 			intval(local_channel())
-        );
-        if($r) {
-            $sql_extra = " AND item.parent IN ( SELECT DISTINCT parent FROM item WHERE true $sql_options AND uid = " . intval($arr['uid']) . " AND ( author_xchan = '" . dbesc($r[0]['abook_xchan']) . "' or owner_xchan = '" . dbesc($r[0]['abook_xchan']) . "' ) and item_restrict = 0 ) ";
+		);
+		if ($r) {
+			$sql_extra = " AND item.parent IN ( SELECT DISTINCT parent FROM item WHERE true $sql_options AND uid = " . intval($arr['uid']) . " AND ( author_xchan = '" . dbesc($r[0]['abook_xchan']) . "' or owner_xchan = '" . dbesc($r[0]['abook_xchan']) . "' ) and item_restrict = 0 ) ";
 			$result['headline'] = sprintf( t('Connection: %s'),$r[0]['xchan_name']);
-        }
-        else {
+		} else {
 			$result['message'] = t('Connection not found.');
 			return $result;
-        }
-    }
+		}
+	}
 
-    if($arr['datequery']) {
-        $sql_extra3 .= protect_sprintf(sprintf(" AND item.created <= '%s' ", dbesc(datetime_convert(date_default_timezone_get(),'',$arr['datequery']))));
-    }
-    if($arr['datequery2']) {
-        $sql_extra3 .= protect_sprintf(sprintf(" AND item.created >= '%s' ", dbesc(datetime_convert(date_default_timezone_get(),'',$arr['datequery2']))));
-    }
+	if ($arr['datequery']) {
+		$sql_extra3 .= protect_sprintf(sprintf(" AND item.created <= '%s' ", dbesc(datetime_convert(date_default_timezone_get(),'',$arr['datequery']))));
+	}
+	if ($arr['datequery2']) {
+		$sql_extra3 .= protect_sprintf(sprintf(" AND item.created >= '%s' ", dbesc(datetime_convert(date_default_timezone_get(),'',$arr['datequery2']))));
+	}
 
 	if(! array_key_exists('nouveau',$arr)) {
 		$sql_extra2 = " AND item.parent = item.id ";
@@ -4542,37 +4497,33 @@ function items_fetch($arr,$channel = null,$observer_hash = null,$client_mode = C
             $sql_extra .= sprintf(" AND item.body like '%s' ",
                 dbesc(protect_sprintf('%' . $arr['search'] . '%'))
             );
-    }
-
-    if(strlen($arr['file'])) {
-        $sql_extra .= term_query('item',$arr['files'],TERM_FILE);
-    }
-
-    if($arr['conv'] && $channel) {
-        $sql_extra .= sprintf(" AND parent IN (SELECT distinct parent from item where ( author_xchan like '%s' or ( item_flags & %d )>0)) ",
-            dbesc(protect_sprintf($uidhash)),
-            intval(ITEM_MENTIONSME)
-        );
-    }
-
+	}
 
-    if(($client_mode & CLIENT_MODE_UPDATE) && (! ($client_mode & CLIENT_MODE_LOAD))) {
+	if (strlen($arr['file'])) {
+		$sql_extra .= term_query('item',$arr['files'],TERM_FILE);
+	}
 
-        // only setup pagination on initial page view
-        $pager_sql = '';
+	if ($arr['conv'] && $channel) {
+		$sql_extra .= sprintf(" AND parent IN (SELECT distinct parent from item where ( author_xchan like '%s' or ( item_flags & %d )>0)) ",
+			dbesc(protect_sprintf($uidhash)),
+			intval(ITEM_MENTIONSME)
+		);
+	}
 
-    }
-    else {
-        $itemspage = (($channel) ? get_pconfig($uid,'system','itemspage') : 20);
-        $a->set_pager_itemspage(((intval($itemspage)) ? $itemspage : 20));
-        $pager_sql = sprintf(" LIMIT %d OFFSET %d ", intval(get_app()->pager['itemspage']), intval(get_app()->pager['start']));
-    }
+	if (($client_mode & CLIENT_MODE_UPDATE) && (! ($client_mode & CLIENT_MODE_LOAD))) {
+		// only setup pagination on initial page view
+		$pager_sql = '';
+	} else {
+		$itemspage = (($channel) ? get_pconfig($uid,'system','itemspage') : 20);
+		$a->set_pager_itemspage(((intval($itemspage)) ? $itemspage : 20));
+		$pager_sql = sprintf(" LIMIT %d OFFSET %d ", intval(get_app()->pager['itemspage']), intval(get_app()->pager['start']));
+	}
 
-	if(isset($arr['start']) && isset($arr['records']))
-        $pager_sql = sprintf(" LIMIT %d OFFSET %d ", intval($arr['records']), intval($arr['start']));
+	if (isset($arr['start']) && isset($arr['records']))
+		$pager_sql = sprintf(" LIMIT %d OFFSET %d ", intval($arr['records']), intval($arr['start']));
 
-	if(array_key_exists('cmin',$arr) || array_key_exists('cmax',$arr)) {
-		if(($arr['cmin'] != 0) || ($arr['cmax'] != 99)) {
+	if (array_key_exists('cmin',$arr) || array_key_exists('cmax',$arr)) {
+		if (($arr['cmin'] != 0) || ($arr['cmax'] != 99)) {
 
 			// Not everybody who shows up in the network stream will be in your address book.
 			// By default those that aren't are assumed to have closeness = 99; but this isn't
@@ -4581,33 +4532,32 @@ function items_fetch($arr,$channel = null,$observer_hash = null,$client_mode = C
 
 			$sql_nets .= " AND ";
 
-			if($arr['cmax'] == 99)
+			if ($arr['cmax'] == 99)
 				$sql_nets .= " ( ";
 
 			$sql_nets .= "( abook.abook_closeness >= " . intval($arr['cmin']) . " ";
 			$sql_nets .= " AND abook.abook_closeness <= " . intval($arr['cmax']) . " ) ";
-			if($cmax == 99)
+			if ($cmax == 99)
 				$sql_nets .= " OR abook.abook_closeness IS NULL ) ";
-    	}
+		}
 	}
 
-    $simple_update = (($client_mode & CLIENT_MODE_UPDATE) ? " and ( item.item_unseen = 1 ) " : '');
-    if($client_mode & CLIENT_MODE_LOAD)
-        $simple_update = '';
+	$simple_update = (($client_mode & CLIENT_MODE_UPDATE) ? " and ( item.item_unseen = 1 ) " : '');
+	if ($client_mode & CLIENT_MODE_LOAD)
+		$simple_update = '';
 
-    $start = dba_timer();
+	//$start = dba_timer();
 
 	require_once('include/security.php');
 	$sql_extra .= item_permissions_sql($channel['channel_id']);
 
-	if($arr['pages'])
+	if ($arr['pages'])
 		$item_restrict = " AND (item_restrict & " . ITEM_WEBPAGE . ") ";
 	else
 		$item_restrict = " AND item_restrict = 0 ";
 
-
-    if($arr['nouveau'] && ($client_mode & CLIENT_MODE_LOAD) && $channel) {
-        // "New Item View" - show all items unthreaded in reverse created date order
+	if ($arr['nouveau'] && ($client_mode & CLIENT_MODE_LOAD) && $channel) {
+		// "New Item View" - show all items unthreaded in reverse created date order
 
         $items = q("SELECT item.*, item.id AS item_id FROM item
             WHERE $item_uids $item_restrict
@@ -4616,22 +4566,21 @@ function items_fetch($arr,$channel = null,$observer_hash = null,$client_mode = C
             ORDER BY item.received DESC $pager_sql "
         );
 
-        require_once('include/items.php');
+		require_once('include/items.php');
 
-        xchan_query($items);
+		xchan_query($items);
 
-        $items = fetch_post_tags($items,true);
-    }
-    else {
+		$items = fetch_post_tags($items,true);
+	} else {
 
-        // Normal conversation view
+		// Normal conversation view
 
-        if($arr['order'] === 'post')
+		if($arr['order'] === 'post')
 			$ordering = "created";
-        else
+		else
 			$ordering = "commented";
 
-        if(($client_mode & CLIENT_MODE_LOAD) || ($client_mode == CLIENT_MODE_NORMAL)) {
+		if(($client_mode & CLIENT_MODE_LOAD) || ($client_mode == CLIENT_MODE_NORMAL)) {
 
             // Fetch a page full of parent items for this page
 
@@ -4657,48 +4606,46 @@ function items_fetch($arr,$channel = null,$observer_hash = null,$client_mode = C
             );
         }
 
-        $first = dba_timer();
+		//$first = dba_timer();
 
-        // Then fetch all the children of the parents that are on this page
+		// Then fetch all the children of the parents that are on this page
 
-        if($r) {
+		if($r) {
 
-            $parents_str = ids_to_querystr($r,'item_id');
+			$parents_str = ids_to_querystr($r,'item_id');
 
 			if($arr['top'])
 				$sql_extra = ' and id = parent ' . $sql_extra;
 
-            $items = q("SELECT item.*, item.id AS item_id FROM item
-                WHERE $item_uids $item_restrict
-                AND item.parent IN ( %s )
-                $sql_extra ",
-                dbesc($parents_str)
-            );
+			$items = q("SELECT item.*, item.id AS item_id FROM item
+				WHERE $item_uids $item_restrict
+				AND item.parent IN ( %s )
+				$sql_extra ",
+				dbesc($parents_str)
+			);
 
-            $second = dba_timer();
+			$second = dba_timer();
 
-            xchan_query($items);
+			xchan_query($items);
 
-            $third = dba_timer();
+			//$third = dba_timer();
 
-            $items = fetch_post_tags($items,true);
+			$items = fetch_post_tags($items,true);
 
-            $fourth = dba_timer();
+			//$fourth = dba_timer();
 
 			require_once('include/conversation.php');
-            $items = conv_sort($items,$ordering);
-
-            //logger('items: ' . print_r($items,true));
+			$items = conv_sort($items,$ordering);
 
-        }
-        else {
-            $items = array();
-        }
+			//logger('items: ' . print_r($items,true));
+		} else {
+			$items = array();
+		}
 
-        if($parents_str && $arr['mark_seen'])
-            $update_unseen = ' AND parent IN ( ' . dbesc($parents_str) . ' )';
-			// FIXME finish mark unseen sql
-    }
+		if($parents_str && $arr['mark_seen'])
+			$update_unseen = ' AND parent IN ( ' . dbesc($parents_str) . ' )';
+			/** @FIXME finish mark unseen sql */
+	}
 
 	return $items;
 }
@@ -4719,7 +4666,7 @@ function update_remote_id($channel,$post_id,$webpage,$pagetitle,$namespace,$remo
 		$pagetitle = $remote_id;
 	}
 
-	if($page_type) {	
+	if($page_type) {
 
 		// store page info as an alternate message_id so we can access it via 
 		//    https://sitename/page/$channelname/$pagetitle
@@ -4747,17 +4694,17 @@ function update_remote_id($channel,$post_id,$webpage,$pagetitle,$namespace,$remo
 			);
 		}
 	}
-
 }
 
 
-
 /**
- * change access control for item with message_id $mid and channel_id $uid
+ * @brief Change access control for item with message_id $mid and channel_id $uid.
+ *
+ * @param string $xchan_hash
+ * @param string $mid
+ * @param int $uid
  */
-
-
-function item_add_cid($xchan_hash,$mid,$uid) {
+function item_add_cid($xchan_hash, $mid, $uid) {
 	$r = q("select id from item where mid = '%s' and uid = %d and allow_cid like '%s'",
 		dbesc($mid),
 		intval($uid),
@@ -4809,27 +4756,28 @@ function set_linkified_perms($linkified, &$str_contact_allow, &$str_group_allow,
 			}
 			if(strpos($access_tag,'cid:') === 0) {
 				$str_contact_allow .= '<' . substr($access_tag,4) . '>';
-				$access_tag = '';	
+				$access_tag = '';
 			}
 			elseif(strpos($access_tag,'gid:') === 0) {
 				$str_group_allow .= '<' . substr($access_tag,4) . '>';
-				$access_tag = '';	
+				$access_tag = '';
 			}
 		}
 	}
 }
 
-
-/*
- * We can't trust ITEM_ORIGIN to tell us if this is a local comment 
+/**
+ * We can't trust ITEM_ORIGIN to tell us if this is a local comment
  * which needs to be relayed, because it was misconfigured at one point for several
  * months and set for some remote items (in alternate delivery chains). This could
  * cause looping, so use this hackish but accurate method. 
+ *
+ * @param array $item
+ * @return boolean
  */
-
-
 function comment_local_origin($item) {
-	if(stripos($item['mid'],get_app()->get_hostname()) && ($item['parent'] != $item['id']))
+	if(stripos($item['mid'], get_app()->get_hostname()) && ($item['parent'] != $item['id']))
 		return true;
-	return false;		
+
+	return false;
 }
diff --git a/include/language.php b/include/language.php
index ec5fa84fa..1e8528dc1 100644
--- a/include/language.php
+++ b/include/language.php
@@ -1,8 +1,8 @@
 <?php
 /**
- * @file
+ * @file include/language.php
  *
- * @brief translation support
+ * @brief Translation support.
  *
  * This file contains functions to work with translations and other
  * language related tasks.
@@ -26,7 +26,7 @@ function get_browser_language() {
 	$langs = array();
 	$lang_parse = array();
 
-	if (x($_SERVER,'HTTP_ACCEPT_LANGUAGE')) {
+	if (x($_SERVER, 'HTTP_ACCEPT_LANGUAGE')) {
 		// break up string into pieces (languages and q factors)
 		preg_match_all('/([a-z]{1,8}(-[a-z]{1,8})?)\s*(;\s*q\s*=\s*(1|0\.[0-9]+))?/i', 
 			$_SERVER['HTTP_ACCEPT_LANGUAGE'], $lang_parse);
@@ -110,9 +110,12 @@ function pop_lang() {
 	$a->language = $a->langsave;
 }
 
-
-// load string translation table for alternate language
-
+/**
+ * @brief Load string translation table for alternate language.
+ *
+ * @param string $lang language code in 2-letter ISO 639-1 (en, de, fr) format
+ * @param boolean $install (optional) default false
+ */
 function load_translation_table($lang, $install = false) {
 	global $a;
 
@@ -139,14 +142,13 @@ function load_translation_table($lang, $install = false) {
 	if(file_exists("view/local-$lang/strings.php")) {
 		include("view/local-$lang/strings.php");
 	}
-
 }
 
 /**
- * @brief translate string if translation exists.
+ * @brief Translate string if translation exists.
  *
  * @param string $s string that should get translated
- * @param string $ctx optional context to appear in po file
+ * @param string $ctx (optional) context to appear in po file
  * @return translated string if exists, otherwise return $s
  *
  */
@@ -154,37 +156,53 @@ function t($s, $ctx = '') {
 	global $a;
 
 	$cs = $ctx ? '__ctx:' . $ctx . '__ ' . $s : $s;
-	if(x($a->strings, $cs)) {
+	if (x($a->strings, $cs)) {
 		$t = $a->strings[$cs];
+
 		return is_array($t) ? $t[0] : $t;
 	}
+
 	return $s;
 }
 
-
+/**
+ * @brief
+ *
+ * @param string $singular
+ * @param string $plural
+ * @param int $count
+ * @param string $ctx
+ * @return string
+ */
 function tt($singular, $plural, $count, $ctx = ''){
 	$a = get_app();
 
-	$cs = $ctx?"__ctx:".$ctx."__ ".$singular:$singular;
-	if(x($a->strings,$cs)) {
+	$cs = $ctx ? "__ctx:" . $ctx . "__ " . $singular : $singular;
+	if (x($a->strings,$cs)) {
 		$t = $a->strings[$cs];
 		$f = 'string_plural_select_' . str_replace('-', '_', $a->language);
-		if(! function_exists($f))
+		if (! function_exists($f))
 			$f = 'string_plural_select_default';
+
 		$k = $f($count);
+
 		return is_array($t) ? $t[$k] : $t;
 	}
-	
-	if ($count != 1){
+
+	if ($count != 1) {
 		return $plural;
 	} else {
 		return $singular;
 	}
 }
 
-// provide a fallback which will not collide with 
-// a function defined in any language file 
-
+/**
+ * @brief Provide a fallback which will not collide with a function defined in
+ * any language file.
+ *
+ * @param int $n
+ * @return boolean
+ */
 function string_plural_select_default($n) {
 	return ($n != 1);
 }
@@ -200,25 +218,25 @@ function string_plural_select_default($n) {
  * returned through config['system']['language_detect_min_confidence'].
  *
  * @see http://pear.php.net/package/Text_LanguageDetect
- * @param s A string to examine
+ * @param string $s A string to examine
  * @return Language code in 2-letter ISO 639-1 (en, de, fr) format
  */
 function detect_language($s) {
 	require_once('Text/LanguageDetect.php');
 
 	$min_length = get_config('system', 'language_detect_min_length');
-	if($min_length === false)
+	if ($min_length === false)
 		$min_length = LANGUAGE_DETECT_MIN_LENGTH;
 
 	$min_confidence = get_config('system', 'language_detect_min_confidence');
-	if($min_confidence === false)
+	if ($min_confidence === false)
 		$min_confidence = LANGUAGE_DETECT_MIN_CONFIDENCE;
 
 	// embedded apps have long base64 strings which will trip up the detector.
 	$naked_body = preg_replace('/\[app\](.*?)\[\/app\]/','',$s);
 	// strip off bbcode
 	$naked_body = preg_replace('/\[(.+?)\]/', '', $naked_body);
-	if(mb_strlen($naked_body) < intval($min_length)) {
+	if (mb_strlen($naked_body) < intval($min_length)) {
 		logger('string length less than ' . intval($min_length), LOGGER_DATA);
 		return '';
 	}
@@ -233,11 +251,11 @@ function detect_language($s) {
 		logger('detect language exception: ' . $e->getMessage(), LOGGER_DATA);
 	}
 
-	if((! $lng) || (! (x($lng,'language')))) {
+	if ((! $lng) || (! (x($lng,'language')))) {
 		return '';
 	}
 
-	if($lng['confidence'] < (float) $min_confidence) {
+	if ($lng['confidence'] < (float) $min_confidence) {
 		logger('detect language: confidence less than ' . (float) $min_confidence, LOGGER_DATA);
 		return '';
 	}
@@ -251,38 +269,37 @@ function detect_language($s) {
  * By default we use the localized language name. You can switch the result
  * to any language with the optional 2nd parameter $l.
  *
- * $s and $l should be in 2-letter ISO 639-1 format
+ * $s and $l should be in 2-letter ISO 639-1 format.
  *
  * If nothing could be looked up it returns $s.
  *
- * @param $s Language code to look up
- * @param $l (optional) In which language to return the name
+ * @param string $s Language code to look up
+ * @param string $l (optional) In which language to return the name
  * @return string with the language name, or $s if unrecognized
+ *
+ * @todo include CommerceGuys\Intl through composer like SabreDAV.
  */
 require_once(__DIR__ . '/../library/intl/vendor/autoload.php');
 use CommerceGuys\Intl\Language\LanguageRepository;
 function get_language_name($s, $l = null) {
 	// get() expects the second part to be in upper case
-	if(strpos($s,'-') !== false) $s = substr($s,0,2) . strtoupper(substr($s,2));
-	if($l !== null && strpos($l,'-') !== false) $l = substr($l,0,2) . strtoupper(substr($l,2));
+	if (strpos($s, '-') !== false) $s = substr($s, 0, 2) . strtoupper(substr($s, 2));
+	if ($l !== null && strpos($l, '-') !== false) $l = substr($l, 0, 2) . strtoupper(substr($l, 2));
 
 	$languageRepository = new LanguageRepository;
 
 	// Sometimes intl doesn't like the second part at all ...
 	try {
 		$language = $languageRepository->get($s, $l);
-	}
-	catch(CommerceGuys\Intl\Exception\UnknownLanguageException $e) {
-		$s = substr($s,0,2);
-		if($l !== null) $l = substr($s,0,2);
+	} catch(CommerceGuys\Intl\Exception\UnknownLanguageException $e) {
+		$s = substr($s, 0, 2);
+		if($l !== null) $l = substr($s, 0, 2);
 		try {
 			$language = $languageRepository->get($s, $l);
-		}
-		catch(CommerceGuys\Intl\Exception\UnknownLanguageException $e) {
+		} catch (CommerceGuys\Intl\Exception\UnknownLanguageException $e) {
 			return $s; // Give up
 		}
-	} 
+	}
 
 	return $language->getName();
 }
-
diff --git a/include/network.php b/include/network.php
index 6aefc0b30..a0782692e 100644
--- a/include/network.php
+++ b/include/network.php
@@ -1,33 +1,39 @@
-<?php /** @file */
-
-
+<?php
+/**
+ * @file include/network.php
+ */
 
+/**
+ * @brief Returns path to CA file.
+ *
+ * @return string
+ */
 function get_capath() {
 	return appdirpath() . '/library/cacert.pem';
 }
 
 /**
- * @function z_fetch_url
+ * @brief fetches an URL.
+ *
  * @param string $url
  *    URL to fetch
- * @param boolean $binary = false
+ * @param boolean $binary default false
  *    TRUE if asked to return binary results (file download)
- * @param int $redirects = 0
+ * @param int $redirects default 0
  *    internal use, recursion counter
- * @param array $opts (optional parameters)
- *    'accept_content' => supply Accept: header with 'accept_content' as the value
- *    'timeout' => int seconds, default system config value or 60 seconds
- *    'http_auth' => username:password
- *    'novalidate' => do not validate SSL certs, default is to validate using our CA list
- *    'nobody' => only return the header
- *    
- * @returns array
- *    'return_code' => HTTP return code or 0 if timeout or failure
- *    'success' => boolean true (if HTTP 2xx result) or false
- *    'header' => HTTP headers
- *    'body' => fetched content
+ * @param array $opts (optional parameters) assoziative array with:
+ *  * \b accept_content => supply Accept: header with 'accept_content' as the value
+ *  * \b timeout => int seconds, default system config value or 60 seconds
+ *  * \b http_auth => username:password
+ *  * \b novalidate => do not validate SSL certs, default is to validate using our CA list
+ *  * \b nobody => only return the header
+ *
+ * @return array an assoziative array with:
+ *  * \e int \b return_code => HTTP return code or 0 if timeout or failure
+ *  * \e boolean \b success => boolean true (if HTTP 2xx result) or false
+ *  * \e string \b header => HTTP headers
+ *  * \e string \b body => fetched content
  */
-
 function z_fetch_url($url, $binary = false, $redirects = 0, $opts = array()) {
 
 	$ret = array('return_code' => 0, 'success' => false, 'header' => "", 'body' => "");
@@ -129,14 +135,15 @@ function z_fetch_url($url, $binary = false, $redirects = 0, $opts = array()) {
 	if(x($opts,'debug')) {
 		$ret['debug'] = $curl_info;
 	}
-	
+
 	@curl_close($ch);
 	return($ret);
 }
 
 
 /**
- * @function z_post_url
+ * @brief
+ *
  * @param string $url
  *    URL to post
  * @param mixed $params
@@ -151,17 +158,15 @@ function z_fetch_url($url, $binary = false, $redirects = 0, $opts = array()) {
  *    'timeout' => int seconds, default system config value or 60 seconds
  *    'http_auth' => username:password
  *    'novalidate' => do not validate SSL certs, default is to validate using our CA list
- *    
- * @returns array
- *    'return_code' => HTTP return code or 0 if timeout or failure
- *    'success' => boolean true (if HTTP 2xx result) or false
- *    'header' => HTTP headers
- *    'body' => fetched content
+ * @return array an assoziative array with:
+ *  * \e int \b return_code => HTTP return code or 0 if timeout or failure
+ *  * \e boolean \b success => boolean true (if HTTP 2xx result) or false
+ *  * \e string \b header => HTTP headers
+ *  * \e string \b body => content
+ *  * \e string \b debug => from curl_info()
  */
-
-
 function z_post_url($url,$params, $redirects = 0, $opts = array()) {
-	
+
 	$ret = array('return_code' => 0, 'success' => false, 'header' => "", 'body' => "");
 
 	$ch = curl_init($url);
@@ -257,24 +262,35 @@ function z_post_url($url,$params, $redirects = 0, $opts = array()) {
 		logger('z_post_url: debug: ' . print_r($curl_info,true), LOGGER_DATA);
 	}
 
-	$ret['body'] = substr($s,strlen($header));
+	$ret['body'] = substr($s, strlen($header));
 	$ret['header'] = $header;
 
 	if(x($opts,'debug')) {
 		$ret['debug'] = $curl_info;
 	}
 
-
 	curl_close($ch);
 	return($ret);
 }
 
+/**
+ * @brief Like z_post_url() but with an application/json HTTP header.
+ *
+ * Add a "Content-Type: application/json" HTTP-header to $opts and call z_post_url().
+ *
+ * @see z_post_url()
+ *
+ * @param string $url
+ * @param array $params
+ * @param number $redirects default 0
+ * @param array $opts (optional) curl options
+ * @return z_post_url()
+ */
+function z_post_url_json($url, $params, $redirects = 0, $opts = array()) {
 
-function z_post_url_json($url,$params,$redirects = 0, $opts = array()) {
+	$opts = array_merge($opts, array('headers' => array('Content-Type: application/json')));
 
-	$opts = array_merge($opts,array('headers' => array('Content-Type: application/json')));
 	return z_post_url($url,json_encode($params),$redirects,$opts);
-
 }
 
 
@@ -305,22 +321,19 @@ function xml_status($st, $message = '') {
 }
 
 /**
- * @function http_status_exit
- * 
- * Send HTTP status header and exit
+ * @brief Send HTTP status header and exit.
+ *
  * @param int $val
  *    integer HTTP status result value
  * @param string $msg
  *    optional message
  * @returns (does not return, process is terminated)
  */
+function http_status_exit($val, $msg = '') {
 
-function http_status_exit($val,$msg = '') {
-
-	$err = '';
-	if($val >= 400)
+	if ($val >= 400)
 		$msg = (($msg) ? $msg : 'Error');
-	if($val >= 200 && $val < 300)
+	if ($val >= 200 && $val < 300)
 		$msg = (($msg) ? $msg : 'OK');
 
 	logger('http_status_exit ' . $val . ' ' . $msg);	
diff --git a/include/permissions.php b/include/permissions.php
index 4d7def346..82145066b 100644
--- a/include/permissions.php
+++ b/include/permissions.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * @file incldue/permissions.php
+ * @file include/permissions.php
  *
  * This file conntains functions to check and work with permissions.
  */
@@ -445,21 +445,21 @@ function site_default_perms() {
 
 
 /**
- * @function get_role_perms($role)
- * @param string $role
- * 
- *   Given a string for the channel role ('social','forum', etc)
+ * @brief Return an array of all permissions for this role.
+ *
+ * Given a string for the channel role ('social','forum', etc)
  * return an array of all permission fields pre-filled for this role.
  * This includes the channel permission scope indicators (anything beginning with 'channel_') as well as
- *    perms_auto:   true or false to create auto-permissions for this channel
- *    perms_follow: The permissions to apply when initiating a connection request to another channel
- *    perms_accept: The permissions to apply when accepting a connection request from another channel (not automatic)
- *    default_collection: true or false to make the default ACL include the channel's default collection 
- *    directory_publish: true or false to publish this channel in the directory
+ *  * perms_auto:   true or false to create auto-permissions for this channel
+ *  * perms_follow: The permissions to apply when initiating a connection request to another channel
+ *  * perms_accept: The permissions to apply when accepting a connection request from another channel (not automatic)
+ *  * default_collection: true or false to make the default ACL include the channel's default collection 
+ *  * directory_publish: true or false to publish this channel in the directory
  * Any attributes may be extended (new roles defined) and modified (specific permissions altered) by plugins
  *
+ * @param string $role
+ * @return array
  */
-
 function get_role_perms($role) {
 
 	$ret = array();
@@ -800,9 +800,8 @@ function get_role_perms($role) {
 }
 
 /**
- * @brief Returns a list or roles, grouped by type
+ * @brief Returns a list or roles, grouped by type.
  *
- * @param string $current The current role
  * @return string Returns an array of roles, grouped by type
  */
 function get_roles() {
@@ -811,7 +810,8 @@ function get_roles() {
 		t('Community Forum') => array('forum' => t('Mostly Public'), 'forum_restricted' => t('Restricted'), 'forum_private' => t('Private')),
 		t('Feed Republish') => array('feed' => t('Mostly Public'), 'feed_restricted' => t('Restricted')),
 		t('Special Purpose') => array('soapbox' => t('Celebrity/Soapbox'), 'repository' => t('Group Repository')),
-		t('Other') => array('custom' => t('Custom/Expert Mode')));
+		t('Other') => array('custom' => t('Custom/Expert Mode'))
+	);
 
 	return $roles;
 }
diff --git a/include/photos.php b/include/photos.php
index c4d5a33aa..1672e310a 100644
--- a/include/photos.php
+++ b/include/photos.php
@@ -1,10 +1,21 @@
-<?php /** @file */
+<?php
+/**
+ * @file include/photos.php
+ * @brief Functions related to photo handling.
+ */
 
 require_once('include/permissions.php');
 require_once('include/items.php');
 require_once('include/photo/photo_driver.php');
 
-
+/**
+ * @brief
+ *
+ * @param array $channel
+ * @param array $observer
+ * @param array $args
+ * @return array
+ */
 function photo_upload($channel, $observer, $args) {
 
 	$ret = array('success' => false);
@@ -18,12 +29,12 @@ function photo_upload($channel, $observer, $args) {
 
 	call_hooks('photo_upload_begin', $args);
 
-	/**
+	/*
 	 * Determine the album to use
 	 */
 
-	$album       = $args['album'];
-	$newalbum    = $args['newalbum'];
+	$album    = $args['album'];
+	$newalbum = $args['newalbum'];
 
 	logger('photo_upload: album= ' . $album . ' newalbum= ' . $newalbum , LOGGER_DEBUG);
 
@@ -44,8 +55,7 @@ function photo_upload($channel, $observer, $args) {
 	$str_group_deny    = perms2str(((is_array($args['group_deny']))    ? $args['group_deny']    : explode(',',$args['group_deny'])));
 	$str_contact_deny  = perms2str(((is_array($args['contact_deny']))  ? $args['contact_deny']  : explode(',',$args['contact_deny'])));
 
-
-	if($args['data']) {
+	if ($args['data']) {
 
 		// allow an import from a binary string representing the image.
 		// This bypasses the upload step and max size limit checking
@@ -56,23 +66,21 @@ function photo_upload($channel, $observer, $args) {
 		// this is going to be deleted if it exists
 		$src = '/tmp/deletemenow';
 		$type = $args['type'];
-	}
-	else {
+	} else {
 		$f = array('src' => '', 'filename' => '', 'filesize' => 0, 'type' => '');
 
 		call_hooks('photo_upload_file',$f);
 
-		if(x($f,'src') && x($f,'filesize')) {
+		if (x($f,'src') && x($f,'filesize')) {
 			$src      = $f['src'];
 			$filename = $f['filename'];
 			$filesize = $f['filesize'];
 			$type     = $f['type'];
-		}
-		else {
-			$src        = $_FILES['userfile']['tmp_name'];
-			$filename   = basename($_FILES['userfile']['name']);
-			$filesize   = intval($_FILES['userfile']['size']);
-			$type       = $_FILES['userfile']['type'];
+		} else {
+			$src      = $_FILES['userfile']['tmp_name'];
+			$filename = basename($_FILES['userfile']['name']);
+			$filesize = intval($_FILES['userfile']['size']);
+			$type     = $_FILES['userfile']['type'];
 		}
 
 		if (! $type) 
@@ -82,14 +90,14 @@ function photo_upload($channel, $observer, $args) {
 
 		$maximagesize = get_config('system','maximagesize');
 
-		if(($maximagesize) && ($filesize > $maximagesize)) {
+		if (($maximagesize) && ($filesize > $maximagesize)) {
 			$ret['message'] =  sprintf ( t('Image exceeds website size limit of %lu bytes'), $maximagesize);
 			@unlink($src);
 			call_hooks('photo_upload_end',$ret);
 			return $ret;
 		}
 
-		if(! $filesize) {
+		if (! $filesize) {
 			$ret['message'] = t('Image file is empty.');
 			@unlink($src);
 			call_hooks('photo_post_end',$ret);
@@ -101,14 +109,13 @@ function photo_upload($channel, $observer, $args) {
 		$imagedata = @file_get_contents($src);
 	}
 
-
 	$r = q("select sum(size) as total from photo where aid = %d and scale = 0 ",
 		intval($account_id)
 	);
 
 	$limit = service_class_fetch($channel_id,'photo_upload_limit');
 
-	if(($r) && ($limit !== false) && (($r[0]['total'] + strlen($imagedata)) > $limit)) {
+	if (($r) && ($limit !== false) && (($r[0]['total'] + strlen($imagedata)) > $limit)) {
 		$ret['message'] = upgrade_message();
 		@unlink($src);
 		call_hooks('photo_post_end',$ret);
@@ -117,7 +124,7 @@ function photo_upload($channel, $observer, $args) {
 
 	$ph = photo_factory($imagedata, $type);
 
-	if(! $ph->is_valid()) {
+	if (! $ph->is_valid()) {
 		$ret['message'] = t('Unable to process image');
 		logger('photo_upload: unable to process image');
 		@unlink($src);
@@ -127,13 +134,12 @@ function photo_upload($channel, $observer, $args) {
 
 	$exif = $ph->orient($src);
 
-
 	@unlink($src);
 
 	$max_length = get_config('system','max_image_length');
-	if(! $max_length)
+	if (! $max_length)
 		$max_length = MAX_IMAGE_LENGTH;
-	if($max_length > 0)
+	if ($max_length > 0)
 		$ph->scaleImage($max_length);
 
 	$width  = $ph->getWidth();
@@ -144,7 +150,7 @@ function photo_upload($channel, $observer, $args) {
 	$photo_hash = (($args['resource_id']) ? $args['resource_id'] : photo_new_resource());
 
 	$visitor = '';
-	if($channel['channel_hash'] !== $observer['xchan_hash'])
+	if ($channel['channel_hash'] !== $observer['xchan_hash'])
 		$visitor = $observer['xchan_hash'];
 
 	$errors = false;
@@ -163,7 +169,6 @@ function photo_upload($channel, $observer, $args) {
 	if($args['description'])
 		$p['description'] = $args['description'];
 
-
 	$r1 = $ph->save($p);
 	if(! $r1)
 		$errors = true;
@@ -214,8 +219,6 @@ function photo_upload($channel, $observer, $args) {
 		}
 	}
 
-
-
 	$item_flags = ITEM_WALL|ITEM_ORIGIN|ITEM_THREAD_TOP;
 	$item_restrict = (($visible) ? ITEM_VISIBLE : ITEM_HIDDEN);
 	$title = '';
@@ -263,10 +266,9 @@ function photo_upload($channel, $observer, $args) {
 			$tag = '[zmg]';
 	}
 
-
-	$arr['body']          = '[zrl=' . z_root() . '/photos/' . $channel['channel_address'] . '/image/' . $photo_hash . ']' 
-				. $tag . z_root() . "/photo/{$photo_hash}-{$smallest}.".$ph->getExt() . '[/zmg]'
-				. '[/zrl]';
+	$arr['body'] = '[zrl=' . z_root() . '/photos/' . $channel['channel_address'] . '/image/' . $photo_hash . ']' 
+			. $tag . z_root() . "/photo/{$photo_hash}-{$smallest}.".$ph->getExt() . '[/zmg]'
+			. '[/zrl]';
 
 	$result = item_store($arr);
 	$item_id = $result['item_id'];
@@ -304,7 +306,7 @@ function photos_albums_list($channel, $observer) {
 	if(! perm_is_allowed($channel_id, $observer_xchan, 'view_photos'))
 		return false;
 
-	// FIXME - create a permissions SQL which works on arbitrary observers and channels, regardless of login or web status
+	/** @FIXME create a permissions SQL which works on arbitrary observers and channels, regardless of login or web status */
 
 	$sql_extra = permissions_sql($channel_id);
 
@@ -327,7 +329,8 @@ function photos_albums_list($channel, $observer) {
 				'total' => $album['total'], 
 				'url' => z_root() . '/photos/' . $channel['channel_address'] . '/album/' . bin2hex($album['album']), 
 				'urlencode' => urlencode($album['album']),
-				'bin2hex' => bin2hex($album['album']));
+				'bin2hex' => bin2hex($album['album'])
+			);
 			$ret['albums'][] = $entry;
 		}
 	}
@@ -360,11 +363,19 @@ function photos_album_widget($channelx,$observer,$albums = null) {
 				? t('Upload New Photos') : '')
 		));
 	}
+
 	return $o;
 }
 
-
-function photos_list_photos($channel,$observer,$album = '') {
+/**
+ * @brief
+ *
+ * @param array $channel
+ * @param array $observer
+ * @param string $album default empty
+ * @return boolean|array
+ */
+function photos_list_photos($channel, $observer, $album = '') {
 
 	$channel_id     = $channel['channel_id'];
 	$observer_xchan = (($observer) ? $observer['xchan_hash'] : '');
@@ -384,7 +395,7 @@ function photos_list_photos($channel,$observer,$album = '') {
 		intval(PHOTO_NORMAL),
 		intval(PHOTO_PROFILE)
 	);
-	
+
 	if($r) {
 		for($x = 0; $x < count($r); $x ++) {
 			$r[$x]['src'] = z_root() . '/photo/' . $r[$x]['resource_id'] . '-' . $r[$x]['scale'];
@@ -416,6 +427,7 @@ function photos_album_exists($channel_id, $album) {
  * @brief Renames a photo album in a channel.
  *
  * @todo Do we need to check if new album name already exists?
+ *
  * @param int $channel_id id of the channel
  * @param string $oldname The name of the album to rename
  * @param string $newname The new name of the album
@@ -429,25 +441,31 @@ function photos_album_rename($channel_id, $oldname, $newname) {
 	);
 }
 
+/**
+ * @brief
+ *
+ * @param int $channel_id
+ * @param string $album
+ * @param string $remote_xchan
+ * @return string|boolean
+ */
+function photos_album_get_db_idstr($channel_id, $album, $remote_xchan = '') {
 
-function photos_album_get_db_idstr($channel_id,$album,$remote_xchan = '') {
-
-	if($remote_xchan) {
+	if ($remote_xchan) {
 		$r = q("SELECT distinct resource_id as from photo where xchan = '%s' and uid = %d and album = '%s' ",
 			dbesc($remote_xchan),
 			intval($channel_id),
 			dbesc($album)
 		);
-	}
-	else {
+	} else {
 		$r = q("SELECT distinct resource_id  from photo where uid = %d and album = '%s' ",
 			intval($channel_id),
 			dbesc($album)
 		);
 	}
-	if($r) {
+	if ($r) {
 		$arr = array();
-		foreach($r as $rr) {
+		foreach ($r as $rr) {
 			$arr[] = "'" . dbesc($rr['resource_id']) . "'" ;
 		}
 		$str = implode(',',$arr);
@@ -457,6 +475,15 @@ function photos_album_get_db_idstr($channel_id,$album,$remote_xchan = '') {
 	return false;
 }
 
+/**
+ * @brief Creates a new photo item.
+ *
+ * @param array $channel
+ * @param string $creator_hash
+ * @param array $photo
+ * @param boolean $visible default false
+ * @return int item_id
+ */
 function photos_create_item($channel, $creator_hash, $photo, $visible = false) {
 
 	// Create item container
@@ -506,7 +533,6 @@ function getGps($exifCoord, $hemi) {
     $flip = ($hemi == 'W' or $hemi == 'S') ? -1 : 1;
 
     return floatval($flip * ($degrees + ($minutes / 60) + ($seconds / 3600)));
-
 }
 
 function gps2Num($coordPart) {
@@ -521,4 +547,3 @@ function gps2Num($coordPart) {
 
     return floatval($parts[0]) / floatval($parts[1]);
 }
-
diff --git a/include/plugin.php b/include/plugin.php
index b6cfc8d89..4d8405b62 100755
--- a/include/plugin.php
+++ b/include/plugin.php
@@ -7,13 +7,12 @@
 
 require_once("include/smarty.php");
 
+
 /**
  * @brief unloads an addon.
  *
  * @param string $plugin name of the addon
- * @return void
  */
-
 function unload_plugin($plugin){
 	logger("Addons: unloading " . $plugin, LOGGER_DEBUG);
 
@@ -28,9 +27,8 @@ function unload_plugin($plugin){
  * @brief uninstalls an addon.
  *
  * @param string $plugin name of the addon
- * @return bool
+ * @return boolean
  */
-
 function uninstall_plugin($plugin) {
 	unload_plugin($plugin);
 
@@ -70,7 +68,7 @@ function install_plugin($plugin) {
 
 	$plugin_admin = (function_exists($plugin . '_plugin_admin') ? 1 : 0);
 
-	$r = q("INSERT INTO `addon` (`name`, `installed`, `timestamp`, `plugin_admin`) VALUES ( '%s', 1, %d , %d ) ",
+	q("INSERT INTO `addon` (`name`, `installed`, `timestamp`, `plugin_admin`) VALUES ( '%s', 1, %d , %d ) ",
 		dbesc($plugin),
 		intval($t),
 		$plugin_admin
@@ -196,6 +194,7 @@ function register_hook($hook, $file, $function, $priority = 0) {
 		dbesc($function),
 		dbesc($priority)
 	);
+
 	return $r;
 }
 
@@ -206,7 +205,7 @@ function register_hook($hook, $file, $function, $priority = 0) {
  * @param string $hook the name of the hook
  * @param string $file the name of the file that hooks into
  * @param string $function the name of the function that the hook called
- * @return mixed
+ * @return array
  */
 function unregister_hook($hook, $file, $function) {
 	$r = q("DELETE FROM hook WHERE hook = '%s' AND `file` = '%s' AND `function` = '%s'",
@@ -214,6 +213,7 @@ function unregister_hook($hook, $file, $function) {
 		dbesc($file),
 		dbesc($function)
 	);
+
 	return $r;
 }
 
@@ -243,8 +243,7 @@ function load_hooks() {
 }
 
 /**
- *
- * @function insert_hook($hook,$fn)
+ * @brief Inserts a hook into a page request.
  *
  * Insert a short-lived hook into the running page request. 
  * Hooks are normally persistent so that they can be called 
@@ -255,9 +254,9 @@ function load_hooks() {
  * which will not persist beyond the life of this page request
  * or the current process. 
  *
- * @param string $hook;
+ * @param string $hook
  *     name of hook to attach callback
- * @param string $fn;
+ * @param string $fn
  *     function name of callback handler
  */ 
 function insert_hook($hook, $fn) {
@@ -305,9 +304,10 @@ function call_hooks($name, &$data = null) {
 
 
 /**
- * @brief parse plugin comment in search of plugin infos.
+ * @brief Parse plugin comment in search of plugin infos.
  *
  * like
+ * \code
  *   * Name: Plugin
  *   * Description: A plugin which plugs in
  *   * Version: 1.2.3
@@ -315,7 +315,7 @@ function call_hooks($name, &$data = null) {
  *   * Author: Jane <email>
  *   * Compat: Red [(version)], Friendica [(version)]
  *   *
- *
+ *\endcode
  * @param string $plugin the name of the plugin
  * @return array with the plugin information
  */
@@ -363,9 +363,10 @@ function get_plugin_info($plugin){
 
 
 /**
- * @brief parse theme comment in search of theme infos.
+ * @brief Parse theme comment in search of theme infos.
  *
  * like
+ * \code
  *   * Name: My Theme
  *   * Description: My Cool Theme
  *   * Version: 1.2.3
@@ -373,7 +374,7 @@ function get_plugin_info($plugin){
  *   * Maintainer: Jane <profile url>
  *   * Compat: Friendica [(version)], Red [(version)]
  *   *
- *
+ * \endcode
  * @param string $theme the name of the theme
  * @return array
  */
@@ -456,13 +457,11 @@ function get_theme_screenshot($theme) {
 	return($a->get_baseurl() . '/images/blank.png');
 }
 
-
 /**
- * @brief add CSS to <head>
+ * @brief add CSS to \<head\>
  *
  * @param string $src
  * @param string $media change media attribute (default to 'screen')
- * @return void
  */
 function head_add_css($src, $media = 'screen') {
 	get_app()->css_sources[] = array($src, $media);
@@ -471,21 +470,23 @@ function head_add_css($src, $media = 'screen') {
 function head_remove_css($src, $media = 'screen') {
 	$a = get_app();
 	$index = array_search(array($src, $media), $a->css_sources);
-	if($index !== false)
+	if ($index !== false)
 		unset($a->css_sources[$index]);
 }
 
 function head_get_css() {
 	$str = '';
 	$sources = get_app()->css_sources;
-	if(count($sources)) 
-		foreach($sources as $source)
+	if (count($sources)) {
+		foreach ($sources as $source)
 			$str .= format_css_if_exists($source);
+	}
+
 	return $str;
 }
 
 function format_css_if_exists($source) {
-	if(strpos($source[0], '/') !== false)
+	if (strpos($source[0], '/') !== false)
 		$path = $source[0];
 	else
 		$path = theme_include($source[0]);
@@ -592,6 +593,7 @@ function theme_include($file, $root = '') {
 		if(file_exists($p))
 			return $p;
 	}
+
 	return '';
 }
 
diff --git a/include/template_processor.php b/include/template_processor.php
index 74acc9c67..d2bf283e3 100755
--- a/include/template_processor.php
+++ b/include/template_processor.php
@@ -1,305 +1,307 @@
 <?php
-	require_once 'include/ITemplateEngine.php';
-
-	define ("KEY_NOT_EXISTS", '^R_key_not_Exists^');
-
-	class Template implements ITemplateEngine {
-		static $name ="internal";
-	
-		var $r;
-		var $search;
-		var $replace;
-		var $stack = array();
-		var $nodes = array();
-		var $done = false;
-		var $d = false;
-		var $lang = null;
-		var $debug=false;
-		
-		private function _preg_error(){
-			
-			switch(preg_last_error()){
-			    case PREG_INTERNAL_ERROR: echo('PREG_INTERNAL_ERROR'); break;
-			    case PREG_BACKTRACK_LIMIT_ERROR: echo('PREG_BACKTRACK_LIMIT_ERROR'); break;
-			    case PREG_RECURSION_LIMIT_ERROR: echo('PREG_RECURSION_LIMIT_ERROR'); break;
-			    case PREG_BAD_UTF8_ERROR: echo('PREG_BAD_UTF8_ERROR'); break;
+require_once 'include/ITemplateEngine.php';
+
+define ("KEY_NOT_EXISTS", '^R_key_not_Exists^');
+
+class Template implements ITemplateEngine {
+	static $name ="internal";
+
+	var $r;
+	var $search;
+	var $replace;
+	var $stack = array();
+	var $nodes = array();
+	var $done = false;
+	var $d = false;
+	var $lang = null;
+	var $debug=false;
+
+	private function _preg_error() {
+		switch(preg_last_error()) {
+			case PREG_INTERNAL_ERROR: echo('PREG_INTERNAL_ERROR'); break;
+			case PREG_BACKTRACK_LIMIT_ERROR: echo('PREG_BACKTRACK_LIMIT_ERROR'); break;
+			case PREG_RECURSION_LIMIT_ERROR: echo('PREG_RECURSION_LIMIT_ERROR'); break;
+			case PREG_BAD_UTF8_ERROR: echo('PREG_BAD_UTF8_ERROR'); break;
 // This is only valid for php > 5.3, not certain how to code around it for unit tests
-//			    case PREG_BAD_UTF8_OFFSET_ERROR: echo('PREG_BAD_UTF8_OFFSET_ERROR'); break;
-			    default:
-					//die("Unknown preg error.");
-					return;
-			}
-			echo "<hr><pre>";
-			debug_print_backtrace();
-			die();
+//			case PREG_BAD_UTF8_OFFSET_ERROR: echo('PREG_BAD_UTF8_OFFSET_ERROR'); break;
+			default:
+				//die("Unknown preg error.");
+				return;
 		}
-		
-		
-		private function _push_stack(){
-			$this->stack[] = array($this->r, $this->nodes);
-		}
-		private function _pop_stack(){
-			list($this->r, $this->nodes) = array_pop($this->stack);
-			
-		}
-		
-		private function _get_var($name, $retNoKey=false){
-			$keys = array_map('trim',explode(".",$name));
-			if ($retNoKey && !array_key_exists($keys[0], $this->r)) return KEY_NOT_EXISTS;
-			$val = $this->r;
-			foreach($keys as $k) {
-				$val = (isset($val[$k]) ? $val[$k] : null);
-			}
-			return template_escape($val);
+		echo "<hr><pre>";
+		debug_print_backtrace();
+		die();
+	}
+
+	private function _push_stack() {
+		$this->stack[] = array($this->r, $this->nodes);
+	}
+
+	private function _pop_stack(){
+		list($this->r, $this->nodes) = array_pop($this->stack);
+	}
+
+	private function _get_var($name, $retNoKey=false) {
+		$keys = array_map('trim',explode(".",$name));
+		if ($retNoKey && !array_key_exists($keys[0], $this->r))
+			return KEY_NOT_EXISTS;
+
+		$val = $this->r;
+		foreach($keys as $k) {
+			$val = (isset($val[$k]) ? $val[$k] : null);
 		}
-		
-		/**
-		 * IF node
-		 * 
-		 * {{ if <$var> }}...[{{ else }} ...] {{ endif }}
-		 * {{ if <$var>==<val|$var> }}...[{{ else }} ...]{{ endif }}
-		 * {{ if <$var>!=<val|$var> }}...[{{ else }} ...]{{ endif }}
-		 */
-		private function _replcb_if($args){
-			if (strpos($args[2],"==")>0){
-				list($a,$b) = array_map("trim",explode("==",$args[2]));
-				$a = $this->_get_var($a);
-				if ($b[0]=="$") $b =  $this->_get_var($b);
-				$val = ($a == $b);
-			} else if (strpos($args[2],"!=")>0){
-				list($a,$b) = array_map("trim", explode("!=",$args[2]));
-				$a = $this->_get_var($a);
-				if ($b[0]=="$") $b =  $this->_get_var($b);
-				$val = ($a != $b);
-			} else {
-				$val = $this->_get_var($args[2]);
-			}
-			$x = preg_split("|{{ *else *}}|", $args[3]);
-			return ( ($val) ? $x[0] : (isset($x[1]) ? $x[1] : ""));
+
+		return template_escape($val);
+	}
+
+	/**
+	 * IF node
+	 * \code
+	 * {{ if <$var> }}...[{{ else }} ...] {{ endif }}
+	 * {{ if <$var>==<val|$var> }}...[{{ else }} ...]{{ endif }}
+	 * {{ if <$var>!=<val|$var> }}...[{{ else }} ...]{{ endif }}
+	 * \endcode
+	 */
+	private function _replcb_if($args) {
+		if (strpos($args[2],"==")>0){
+			list($a,$b) = array_map("trim",explode("==",$args[2]));
+			$a = $this->_get_var($a);
+			if ($b[0]=="$") $b =  $this->_get_var($b);
+			$val = ($a == $b);
+		} else if (strpos($args[2],"!=")>0){
+			list($a,$b) = array_map("trim", explode("!=",$args[2]));
+			$a = $this->_get_var($a);
+			if ($b[0]=="$") $b =  $this->_get_var($b);
+			$val = ($a != $b);
+		} else {
+			$val = $this->_get_var($args[2]);
 		}
-		
-		/**
-		 * FOR node
-		 * 
-		 * {{ for <$var> as $name }}...{{ endfor }}
-		 * {{ for <$var> as $key=>$name }}...{{ endfor }}
-		 */
-		private function _replcb_for($args){
-			$m = array_map('trim', explode(" as ", $args[2]));
-			$x = explode("=>",$m[1]);
-			if (count($x) == 1) {
-				$varname = $x[0];
-				$keyname = "";
-			} else {
-				list($keyname, $varname) = $x;
-			}
-			if ($m[0]=="" || $varname=="" || is_null($varname)) die("template error: 'for ".$m[0]." as ".$varname."'") ;
-			//$vals = $this->r[$m[0]];
-			$vals = $this->_get_var($m[0]);
-			$ret="";
-			if (!is_array($vals)) return $ret; 
-			foreach ($vals as $k=>$v){
-				$this->_push_stack();
-				$r = $this->r;
-				$r[$varname] = $v;
-				if ($keyname!='') $r[$keyname] = (($k === 0) ? '0' : $k);
-				$ret .=  $this->replace($args[3], $r);
-				$this->_pop_stack();
-			}
-			return $ret;
+		$x = preg_split("|{{ *else *}}|", $args[3]);
+
+		return ( ($val) ? $x[0] : (isset($x[1]) ? $x[1] : ""));
+	}
+
+	/**
+	 * FOR node
+	 * \code
+	 * {{ for <$var> as $name }}...{{ endfor }}
+	 * {{ for <$var> as $key=>$name }}...{{ endfor }}
+	 * \endcode
+	 */
+	private function _replcb_for($args) {
+		$m = array_map('trim', explode(" as ", $args[2]));
+		$x = explode("=>",$m[1]);
+		if (count($x) == 1) {
+			$varname = $x[0];
+			$keyname = "";
+		} else {
+			list($keyname, $varname) = $x;
 		}
+		if ($m[0]=="" || $varname=="" || is_null($varname)) die("template error: 'for ".$m[0]." as ".$varname."'") ;
+		//$vals = $this->r[$m[0]];
+		$vals = $this->_get_var($m[0]);
+		$ret="";
+		if (!is_array($vals)) return $ret;
 
-		/**
-		 * INC node
-		 * 
-		 * {{ inc <templatefile> [with $var1=$var2] }}{{ endinc }}
-		 */
-		private function _replcb_inc($args){
-			if (strpos($args[2],"with")) {
-				list($tplfile, $newctx) = array_map('trim', explode("with",$args[2]));
-			} else {
-				$tplfile = trim($args[2]);
-				$newctx = null;
-			}
-			
-			if ($tplfile[0]=="$") $tplfile = $this->_get_var($tplfile);
-			
+		foreach ($vals as $k=>$v){
 			$this->_push_stack();
 			$r = $this->r;
-			if (!is_null($newctx)) {
-				list($a,$b) = array_map('trim', explode("=",$newctx));
-				$r[$a] = $this->_get_var($b); 
-			}
-			$this->nodes = Array();
-			$tpl = get_markup_template($tplfile);
-			$ret = $this->replace($tpl, $r);
+			$r[$varname] = $v;
+			if ($keyname!='') $r[$keyname] = (($k === 0) ? '0' : $k);
+			$ret .=  $this->replace($args[3], $r);
 			$this->_pop_stack();
-			return $ret;
-			
 		}
-		
-		/**
-		 * DEBUG node
-		 * 
-		 * {{ debug $var [$var [$var [...]]] }}{{ enddebug }}
-		 * 
-		 * replace node with <pre>var_dump($var, $var, ...);</pre>
-		 */
-		private function _replcb_debug($args){
-			$vars = array_map('trim', explode(" ",$args[2]));
-			$vars[] = $args[1];
-
-			$ret = "<pre>";
-			foreach ($vars as $var){
-				$ret .= htmlspecialchars(var_export( $this->_get_var($var), true ));
-				$ret .= "\n";
-			}
-			$ret .= "</pre>";
-			return $ret;
+
+		return $ret;
+	}
+
+	/**
+	 * INC node
+	 * \code
+	 * {{ inc <templatefile> [with $var1=$var2] }}{{ endinc }}
+	 * \endcode
+	 */
+	private function _replcb_inc($args) {
+		if (strpos($args[2],"with")) {
+			list($tplfile, $newctx) = array_map('trim', explode("with",$args[2]));
+		} else {
+			$tplfile = trim($args[2]);
+			$newctx = null;
 		}
 
-		private function _replcb_node($m) {
-			$node = $this->nodes[$m[1]];
-			if (method_exists($this, "_replcb_".$node[1])){
-				$s = call_user_func(array($this, "_replcb_".$node[1]),  $node);
-			} else {
-				$s = "";
-			}
-			$s = preg_replace_callback('/\|\|([0-9]+)\|\|/', array($this, "_replcb_node"), $s);
-			return $s;
+		if ($tplfile[0]=="$") $tplfile = $this->_get_var($tplfile);
+
+		$this->_push_stack();
+		$r = $this->r;
+		if (!is_null($newctx)) {
+			list($a,$b) = array_map('trim', explode("=",$newctx));
+			$r[$a] = $this->_get_var($b); 
+		}
+		$this->nodes = Array();
+		$tpl = get_markup_template($tplfile);
+		$ret = $this->replace($tpl, $r);
+		$this->_pop_stack();
+
+		return $ret;
+	}
+
+	/**
+	 * DEBUG node
+	 * \code
+	 * {{ debug $var [$var [$var [...]]] }}{{ enddebug }}
+	 * \endcode
+	 * replace node with <pre>var_dump($var, $var, ...);</pre>
+	 */
+	private function _replcb_debug($args) {
+		$vars = array_map('trim', explode(" ",$args[2]));
+		$vars[] = $args[1];
+
+		$ret = "<pre>";
+		foreach ($vars as $var){
+			$ret .= htmlspecialchars(var_export( $this->_get_var($var), true ));
+			$ret .= "\n";
 		}
-						
-		private function _replcb($m){
-			//var_dump(array_map('htmlspecialchars', $m));
-			$this->done = false;	
-			$this->nodes[] = (array) $m;
-			return "||". (count($this->nodes)-1) ."||";
+		$ret .= "</pre>";
+
+		return $ret;
+	}
+
+	private function _replcb_node($m) {
+		$node = $this->nodes[$m[1]];
+		if (method_exists($this, "_replcb_".$node[1])){
+			$s = call_user_func(array($this, "_replcb_".$node[1]),  $node);
+		} else {
+			$s = "";
 		}
-		
-		private function _build_nodes($s){
-			$this->done = false;
-			while (!$this->done){
-				$this->done=true;
-				$s = preg_replace_callback('|{{ *([a-z]*) *([^}]*)}}([^{]*({{ *else *}}[^{]*)?){{ *end\1 *}}|', array($this, "_replcb"), $s);
-				if ($s==Null) $this->_preg_error();
-			}
-			//({{ *else *}}[^{]*)?
-			krsort($this->nodes);
-			return $s;
+		$s = preg_replace_callback('/\|\|([0-9]+)\|\|/', array($this, "_replcb_node"), $s);
+
+		return $s;
+	}
+
+	private function _replcb($m) {
+		//var_dump(array_map('htmlspecialchars', $m));
+		$this->done = false;
+		$this->nodes[] = (array) $m;
+
+		return "||". (count($this->nodes)-1) ."||";
+	}
+
+	private function _build_nodes($s) {
+		$this->done = false;
+		while (!$this->done) {
+			$this->done=true;
+			$s = preg_replace_callback('|{{ *([a-z]*) *([^}]*)}}([^{]*({{ *else *}}[^{]*)?){{ *end\1 *}}|', array($this, "_replcb"), $s);
+			if ($s==Null) $this->_preg_error();
 		}
-		
-
-		private function var_replace($s){
-			$m = array();
-			/** regexp:
-			 * \$ 						literal $
-			 * (\[)?					optional open square bracket
-			 * ([a-zA-Z0-9-_]+\.?)+		var name, followed by optional
-			 * 							dot, repeated at least 1 time
-			 * (?(1)\])					if there was opened square bracket
-			 * 							(subgrup 1), match close bracket
-			 */
-			if (preg_match_all('/\$(\[)?([a-zA-Z0-9-_]+\.?)+(?(1)\])/', $s,$m)){
-					foreach($m[0] as $var){
-
-              $exp = str_replace(array("[", "]"), array("", ""), $var);
-                $exptks = explode("|", $exp);
-
-                $varn = $exptks[0];
-                unset($exptks[0]);
-                $val = $this->_get_var($varn, true);
-                if ($val != KEY_NOT_EXISTS) {
-                    /* run filters */
-                    /*
-                     * Filter are in form of:
-                     * filtername:arg:arg:arg
-                     *
-                     * "filtername" is function name
-                     * "arg"s are optional, var value is appended to the end
-                     *          if one "arg"==='x' , is replaced with var value
-                     *
-                     * examples:
-                     * $item.body|htmlspecialchars              // escape html chars
-                     * $item.body|htmlspecialchars|strtoupper   // escape html and uppercase result
-                     * $item.created|date:%Y %M %j              // format date (created is a timestamp)
-                     * $item.body|str_replace:cat:dog           // replace all "cat" with "dog"
-                     * $item.body|str_replace:cat:dog:x:1       // replace one "cat" with "dog"
-
-                     */
-                    foreach ($exptks as $filterstr) {
-                        $filter = explode(":", $filterstr);
-                        $filtername = $filter[0];
-                        unset($filter[0]);
-                        $valkey = array_search("x", $filter);
-                        if ($valkey === false) {
-                            $filter[] = $val;
-                        } else {
-                            $filter[$valkey] = $val;
-                        }
-                        if (function_exists($filtername)) {
-                            $val = call_user_func_array($filtername, $filter);
-                        }
-                    }
-                    $s = str_replace($var, $val, $s);
+		//({{ *else *}}[^{]*)?
+		krsort($this->nodes);
+
+		return $s;
+	}
 
+	private function var_replace($s) {
+		$m = array();
+		/** regexp:
+		 * \$ 						literal $
+		 * (\[)?					optional open square bracket
+		 * ([a-zA-Z0-9-_]+\.?)+		var name, followed by optional
+		 * 							dot, repeated at least 1 time
+		 * (?(1)\])					if there was opened square bracket
+		 * 							(subgrup 1), match close bracket
+		 */
+		if (preg_match_all('/\$(\[)?([a-zA-Z0-9-_]+\.?)+(?(1)\])/', $s,$m)) {
+			foreach ($m[0] as $var) {
+				$exp = str_replace(array("[", "]"), array("", ""), $var);
+				$exptks = explode("|", $exp);
+
+				$varn = $exptks[0];
+				unset($exptks[0]);
+				$val = $this->_get_var($varn, true);
+				if ($val != KEY_NOT_EXISTS) {
+					/* run filters */
+					/*
+					 * Filter are in form of:
+					 * filtername:arg:arg:arg
+					 *
+					 * "filtername" is function name
+					 * "arg"s are optional, var value is appended to the end
+					 *          if one "arg"==='x' , is replaced with var value
+					 *
+					 * examples:
+					 * $item.body|htmlspecialchars              // escape html chars
+					 * $item.body|htmlspecialchars|strtoupper   // escape html and uppercase result
+					 * $item.created|date:%Y %M %j              // format date (created is a timestamp)
+					 * $item.body|str_replace:cat:dog           // replace all "cat" with "dog"
+					 * $item.body|str_replace:cat:dog:x:1       // replace one "cat" with "dog"
+					 */
+					foreach ($exptks as $filterstr) {
+						$filter = explode(":", $filterstr);
+						$filtername = $filter[0];
+						unset($filter[0]);
+						$valkey = array_search("x", $filter);
+						if ($valkey === false) {
+							$filter[] = $val;
+						} else {
+							$filter[$valkey] = $val;
+						}
+						if (function_exists($filtername)) {
+							$val = call_user_func_array($filtername, $filter);
+						}
 					}
+					$s = str_replace($var, $val, $s);
 				}
 			}
-			
-			return $s;
-		}
-		
-		private function replace($s,$r) {
-			$this->replace_macros($s, $r);
-		}
-		
-		// TemplateEngine interface
-		public function replace_macros($s, $r) {
-			$this->r = $r;
-			
-			$s = $this->_build_nodes($s);
-
-			$s = preg_replace_callback('/\|\|([0-9]+)\|\|/', array($this, "_replcb_node"), $s);
-			if ($s==Null) $this->_preg_error();
-			
-			// remove comments block
-			$s = preg_replace('/{#[^#]*#}/', "" , $s);
-			
-			$t2 = dba_timer();
-
-			// replace strings recursively (limit to 10 loops)
-			$os = ""; $count=0;
-			while(($os !== $s) && $count<10){
-				$os=$s; $count++;
-				$s = $this->var_replace($s);
-			}
-			return $s;
 		}
 
-		public function get_markup_template($file, $root='') {
-			$template_file = theme_include($file, $root);
-			if ($template_file) {
-				$content = file_get_contents($template_file);
-			}
-			return $content;		
-		}			
+		return $s;
 	}
-	
 
+	private function replace($s, $r) {
+		$this->replace_macros($s, $r);
+	}
 
+	// TemplateEngine interface
+	public function replace_macros($s, $r) {
+		$this->r = $r;
 
+		$s = $this->_build_nodes($s);
 
-function template_escape($s) {
+		$s = preg_replace_callback('/\|\|([0-9]+)\|\|/', array($this, "_replcb_node"), $s);
+		if ($s == Null)
+			$this->_preg_error();
 
-	return str_replace(array('$','{{'),array('!_Doll^Ars1Az_!','!_DoubLe^BraceS4Rw_!'),$s);
+		// remove comments block
+		$s = preg_replace('/{#[^#]*#}/', "" , $s);
 
+		//$t2 = dba_timer();
 
-}
+		// replace strings recursively (limit to 10 loops)
+		$os = "";
+		$count=0;
+		while (($os !== $s) && $count<10) {
+			$os=$s;
+			$count++;
+			$s = $this->var_replace($s);
+		}
 
-function template_unescape($s) {
+		return $s;
+	}
 
-	return str_replace(array('!_Doll^Ars1Az_!','!_DoubLe^BraceS4Rw_!'),array('$','{{'),$s);
+	public function get_markup_template($file, $root='') {
+		$template_file = theme_include($file, $root);
+		if ($template_file) {
+			$content = file_get_contents($template_file);
+		}
 
+		return $content;
+	}
+}
 
 
+function template_escape($s) {
+	return str_replace(array('$','{{'),array('!_Doll^Ars1Az_!','!_DoubLe^BraceS4Rw_!'),$s);
+}
+
+function template_unescape($s) {
+	return str_replace(array('!_Doll^Ars1Az_!','!_DoubLe^BraceS4Rw_!'),array('$','{{'),$s);
 }
diff --git a/include/text.php b/include/text.php
index 75125c606..664d5f83d 100644
--- a/include/text.php
+++ b/include/text.php
@@ -1,18 +1,26 @@
-<?php /** @file */
-
+<?php
+/**
+ * @file include/text.php
+ */
 
 require_once("include/template_processor.php");
 require_once("include/smarty.php");
 
+// random string, there are 86 characters max in text mode, 128 for hex
+// output is urlsafe
+
+define('RANDOM_STRING_HEX',  0x00 );
+define('RANDOM_STRING_TEXT', 0x01 );
+
 /**
- * This is our template processor
+ * @brief This is our template processor.
  *
  * @param string|FriendicaSmarty $s the string requiring macro substitution,
- *									or an instance of FriendicaSmarty
+ *   or an instance of FriendicaSmarty
  * @param array $r key value pairs (search => replace)
  * @return string substituted string
  */
-function replace_macros($s,$r) {
+function replace_macros($s, $r) {
 	$a = get_app();
 
 	$arr = array('template' => $s, 'params' => $r);
@@ -24,40 +32,38 @@ function replace_macros($s,$r) {
 	return $output;
 }
 
-
-// random string, there are 86 characters max in text mode, 128 for hex
-// output is urlsafe
-
-define('RANDOM_STRING_HEX',  0x00 );
-define('RANDOM_STRING_TEXT', 0x01 );
-
-
-function random_string($size = 64,$type = RANDOM_STRING_HEX) {
+/**
+ * @brief Generates a random string.
+ *
+ * @param number $size
+ * @param int $type
+ * @return string
+ */
+function random_string($size = 64, $type = RANDOM_STRING_HEX) {
 	// generate a bit of entropy and run it through the whirlpool
 	$s = hash('whirlpool', (string) rand() . uniqid(rand(),true) . (string) rand(),(($type == RANDOM_STRING_TEXT) ? true : false));
 	$s = (($type == RANDOM_STRING_TEXT) ? str_replace("\n","",base64url_encode($s,true)) : $s);
-	return(substr($s,0,$size));
+
+	return(substr($s, 0, $size));
 }
 
 /**
- * This is our primary input filter.
+ * @brief This is our primary input filter.
  *
  * The high bit hack only involved some old IE browser, forget which (IE5/Mac?)
  * that had an XSS attack vector due to stripping the high-bit on an 8-bit character
  * after cleansing, and angle chars with the high bit set could get through as markup.
- * 
+ *
  * This is now disabled because it was interfering with some legitimate unicode sequences 
  * and hopefully there aren't a lot of those browsers left. 
  *
  * Use this on any text input where angle chars are not valid or permitted
  * They will be replaced with safer brackets. This may be filtered further
- * if these are not allowed either.   
+ * if these are not allowed either.
  *
  * @param string $string Input string
  * @return string Filtered string
  */
-
-
 function notags($string) {
 
 	return(str_replace(array("<",">"), array('[',']'), $string));
@@ -105,7 +111,6 @@ function z_input_filter($channel_id,$s,$type = 'text/bbcode') {
 		return purify_html($s);
 
 	return escape_tags($s);
-
 }
 
 
@@ -114,39 +119,38 @@ function purify_html($s) {
 	require_once('library/HTMLPurifier.auto.php');
 	require_once('include/html2bbcode.php');
 
-// FIXME this function has html output, not bbcode - so safely purify these
-//	$s = html2bb_video($s);
-//	$s = oembed_html2bbcode($s);
+/**
+ * @FIXME this function has html output, not bbcode - so safely purify these
+ * $s = html2bb_video($s);
+ * $s = oembed_html2bbcode($s);
+ */
 
 	$config = HTMLPurifier_Config::createDefault();
 	$config->set('Cache.DefinitionImpl', null);
 	$config->set('Attr.EnableID', true);
 
 	$purifier = new HTMLPurifier($config);
+
 	return $purifier->purify($s);
 }
 
 
 
-
-
-// generate a string that's random, but usually pronounceable. 
-// used to generate initial passwords
-
-
 /**
- * generate a string that's random, but usually pronounceable. 
- * used to generate initial passwords
+ * @brief generate a string that's random, but usually pronounceable.
+ *
+ * Used to generate initial passwords.
+ *
  * @param int $len
  * @return string
  */
 function autoname($len) {
 
-	if($len <= 0)
+	if ($len <= 0)
 		return '';
 
 	$vowels = array('a','a','ai','au','e','e','e','ee','ea','i','ie','o','ou','u'); 
-	if(mt_rand(0,5) == 4)
+	if (mt_rand(0, 5) == 4)
 		$vowels[] = 'y';
 
 	$cons = array(
@@ -178,8 +182,8 @@ function autoname($len) {
 	$noend = array('bl', 'br', 'cl','cr','dr','fl','fr','gl','gr',
 				'kh', 'kl','kr','mn','pl','pr','rh','tr','qu','wh');
 
-	$start = mt_rand(0,2);
-	if($start == 0)
+	$start = mt_rand(0, 2);
+	if ($start == 0)
 		$table = $vowels;
 	else
 		$table = $cons;
@@ -190,33 +194,30 @@ function autoname($len) {
 		$r = mt_rand(0,count($table) - 1);
 		$word .= $table[$r];
 
-		if($table == $vowels)
-			$table = array_merge($cons,$midcons);
+		if ($table == $vowels)
+			$table = array_merge($cons, $midcons);
 		else
 			$table = $vowels;
-
 	}
 
 	$word = substr($word,0,$len);
 
-	foreach($noend as $noe) {
-		if((strlen($word) > 2) && (substr($word,-2) == $noe)) {
+	foreach ($noend as $noe) {
+		if ((strlen($word) > 2) && (substr($word,-2) == $noe)) {
 			$word = substr($word,0,-1);
 			break;
 		}
 	}
-	if(substr($word,-1) == 'q')
-		$word = substr($word,0,-1);
+	if (substr($word, -1) == 'q')
+		$word = substr($word, 0, -1);
+
 	return $word;
 }
 
 
-// escape text ($str) for XML transport
-// returns escaped text.
-
-
 /**
- * escape text ($str) for XML transport
+ * @brief escape text ($str) for XML transport
+ *
  * @param string $str
  * @return string Escaped text.
  */
@@ -228,7 +229,6 @@ function xmlify($str) {
 		$char = mb_substr($str,$x,1);
 
 		switch( $char ) {
-
 			case "\r" :
 				break;
 			case "&" :
@@ -252,9 +252,10 @@ function xmlify($str) {
 			default :
 				$buffer .= $char;
 				break;
-		}	
+		}
 	}
 	$buffer = trim($buffer);
+
 	return($buffer);
 }
 
@@ -268,10 +269,12 @@ function unxmlify($s) {
 	return $ret;
 }
 
-// convenience wrapper, reverse the operation "bin2hex"
-
-// This is a built-in function in php >= 5.4
-
+/**
+ * Convenience wrapper, reverse the operation "bin2hex"
+ * This is a built-in function in php >= 5.4
+ *
+ * @FIXME We already have php >= 5.4 requirements, so can we remove this?
+ */
 if(! function_exists('hex2bin')) {
 function hex2bin($s) {
 	if(! (is_string($s) && strlen($s)))
@@ -381,14 +384,16 @@ function alt_pager(&$a, $i, $more = '', $less = '') {
 
 }
 
-// Turn user/group ACLs stored as angle bracketed text into arrays
-
-
+/**
+ * @brief Turn user/group ACLs stored as angle bracketed text into arrays.
+ *
+ * turn string array of angle-bracketed elements into string array
+ * e.g. "<123xyz><246qyo><sxo33e>" => array(123xyz,246qyo,sxo33e);
+ *
+ * @param string $s
+ * @return array
+ */
 function expand_acl($s) {
-
-	// turn string array of angle-bracketed elements into string array
-	// e.g. "<123xyz><246qyo><sxo33e>" => array(123xyz,246qyo,sxo33e);
-
 	$ret = array();
 
 	if(strlen($s)) {
@@ -399,34 +404,41 @@ function expand_acl($s) {
 				$ret[] = $aa;
 		}
 	}
+
 	return $ret;
 }
 
-// Used to wrap ACL elements in angle brackets for storage 
-
-
+/**
+ * @brief Used to wrap ACL elements in angle brackets for storage.
+ *
+ * @param[in,out] array &$item
+ */
 function sanitise_acl(&$item) {
-	if(strlen($item))
+	if (strlen($item))
 		$item = '<' . notags(trim($item)) . '>';
 	else
 		unset($item);
 }
 
-
-// Convert an ACL array to a storable string
-
+/**
+ * @brief Convert an ACL array to a storable string.
+ *
+ * @param array $p
+ * @return array
+ */
 function perms2str($p) {
 	$ret = '';
 
-	if(is_array($p))
+	if (is_array($p))
 		$tmp = $p;
 	else
-		$tmp = explode(',',$p);
+		$tmp = explode(',', $p);
 
-	if(is_array($tmp)) {
-		array_walk($tmp,'sanitise_acl');
-		$ret = implode('',$tmp);
+	if (is_array($tmp)) {
+		array_walk($tmp, 'sanitise_acl');
+		$ret = implode('', $tmp);
 	}
+
 	return $ret;
 }
 
@@ -858,51 +870,48 @@ function valid_email($x){
 	return false;
 }
 
-
 /**
+ * @brief Replace naked text hyperlink with HTML formatted hyperlink.
  *
- * Function: linkify
- *
- * Replace naked text hyperlink with HTML formatted hyperlink
- *
+ * @param string $s
+ * @param boolean $me (optional) default false
+ * @return string
  */
-
-
-function linkify($s,$me = false) {
+function linkify($s, $me = false) {
 	$s = preg_replace("/(https?\:\/\/[a-zA-Z0-9\:\/\-\?\&\;\.\=\_\@\~\#\'\%\$\!\+\,\@]*)/", (($me) ? ' <a href="$1" rel="me" >$1</a>' : ' <a href="$1" >$1</a>'), $s);
 	$s = preg_replace("/\<(.*?)(src|href)=(.*?)\&amp\;(.*?)\>/ism",'<$1$2=$3&$4>',$s);
+
 	return($s);
 }
 
-
 /**
- * @function sslify($s)
- *    Replace media element using http url with https to a local redirector if using https locally
- * @param string $s
+ * @brief Replace media element using http url with https to a local redirector
+ *  if using https locally.
  *
  * Looks for HTML tags containing src elements that are http when we're viewing an https page
  * Typically this throws an insecure content violation in the browser. So we redirect them
  * to a local redirector which uses https and which redirects to the selected content
  *
+ * @param string $s
  * @returns string
  */
 function sslify($s) {
-	if(strpos(z_root(),'https:') === false)
+	if (strpos(z_root(),'https:') === false)
 		return $s;
 
 	$matches = null;
 	$cnt = preg_match_all("/\<(.*?)src=\"(http\:.*?)\"(.*?)\>/",$s,$matches,PREG_SET_ORDER);
-	if($cnt) {
-		foreach($matches as $match) {
-			$filename = basename( parse_url($match[2],PHP_URL_PATH) );
+	if ($cnt) {
+		foreach ($matches as $match) {
+			$filename = basename( parse_url($match[2], PHP_URL_PATH) );
 			$s = str_replace($match[2],z_root() . '/sslify/' . $filename . '?f=&url=' . urlencode($match[2]),$s);
 		}
 	}
+
 	return $s;
 }
 
 
-
 function get_poke_verbs() {
 	// index is present tense verb
 	// value is array containing past tense verb, translation of present, translation of past
@@ -1033,47 +1042,42 @@ function list_smilies() {
 
 	$params = array('texts' => $texts, 'icons' => $icons);
 	call_hooks('smilie', $params);
+
 	return $params;
 }
 /**
- * 
- * Function: smilies
- *
- * Description:
- * Replaces text emoticons with graphical images
- *
- * @Parameter: string $s
- *
- * Returns string
+ * @brief Replaces text emoticons with graphical images.
  *
  * It is expected that this function will be called using HTML text.
  * We will escape text between HTML pre and code blocks, and HTML attributes
  * (such as urls) from being processed.
- * 
+ *
  * At a higher level, the bbcode [nosmile] tag can be used to prevent this 
  * function from being executed by the prepare_text() routine when preparing
- * bbcode source for HTML display
+ * bbcode source for HTML display.
  *
+ * @param string $s
+ * @param boolean $sample (optional) default false
+ * @return string
  */
 function smilies($s, $sample = false) {
 
-	if(intval(get_config('system','no_smilies')) 
-		|| (local_channel() && intval(get_pconfig(local_channel(),'system','no_smilies'))))
+	if(intval(get_config('system', 'no_smilies')) 
+		|| (local_channel() && intval(get_pconfig(local_channel(), 'system', 'no_smilies'))))
 		return $s;
 
-	$s = preg_replace_callback('{<(pre|code)>.*?</\1>}ism','smile_shield',$s);
-	$s = preg_replace_callback('/<[a-z]+ .*?>/ism','smile_shield',$s);
+	$s = preg_replace_callback('{<(pre|code)>.*?</\1>}ism', 'smile_shield', $s);
+	$s = preg_replace_callback('/<[a-z]+ .*?>/ism', 'smile_shield', $s);
 
 	$params = list_smilies();
 	$params['string'] = $s;
 
-	if($sample) {
+	if ($sample) {
 		$s = '<div class="smiley-sample">';
-		for($x = 0; $x < count($params['texts']); $x ++) {
+		for ($x = 0; $x < count($params['texts']); $x ++) {
 			$s .= '<dl><dt>' . $params['texts'][$x] . '</dt><dd>' . $params['icons'][$x] . '</dd></dl>';
 		}
-	}
-	else {
+	} else {
 		$params['string'] = preg_replace_callback('/&lt;(3+)/','preg_heart',$params['string']);
 		$s = str_replace($params['texts'],$params['icons'],$params['string']);
 	}
@@ -1083,6 +1087,12 @@ function smilies($s, $sample = false) {
 	return $s;
 }
 
+/**
+ * @brief
+ *
+ * @param array $m
+ * @return string
+ */
 function smile_shield($m) {
 	return '<!--base64:' . base64url_encode($m[0]) . '-->';
 }
@@ -1091,16 +1101,22 @@ function smile_unshield($m) {
 	return base64url_decode($m[1]); 
 }
 
-// expand <3333 to the correct number of hearts
-
+/**
+ * @brief Expand <3333 to the correct number of hearts.
+ *
+ * @param array $x
+ */
 function preg_heart($x) {
 	$a = get_app();
-	if(strlen($x[1]) == 1)
+	if (strlen($x[1]) == 1)
 		return $x[0];
+
 	$t = '';
 	for($cnt = 0; $cnt < strlen($x[1]); $cnt ++)
 		$t .= '<img class="smiley" src="' . $a->get_baseurl() . '/images/smiley-heart.gif" alt="<3" />';
+
 	$r =  str_replace($x[0],$t,$x[0]);
+
 	return $r;
 }
 
@@ -1118,27 +1134,33 @@ function day_translate($s) {
 	return $ret;
 }
 
-
-
+/**
+ * @brief normalises a string.
+ *
+ * @param string $url
+ * @return string
+ */
 function normalise_link($url) {
-	$ret = str_replace(array('https:','//www.'), array('http:','//'), $url);
-	return(rtrim($ret,'/'));
+	$ret = str_replace(array('https:', '//www.'), array('http:', '//'), $url);
+
+	return(rtrim($ret, '/'));
 }
 
 /**
+ * @brief Compare two URLs to see if they are the same.
  *
- * Compare two URLs to see if they are the same, but ignore
- * slight but hopefully insignificant differences such as if one 
- * is https and the other isn't, or if one is www.something and 
- * the other isn't - and also ignore case differences.
+ * But ignore slight but hopefully insignificant differences such as if one
+ * is https and the other isn't, or if one is www.something and the other
+ * isn't - and also ignore case differences.
  *
- * Return true if the URLs match, otherwise false.
+ * @see normalis_link()
  *
+ * @param string $a
+ * @param string $b
+ * @return true if the URLs match, otherwise false
  */
-
-
-function link_compare($a,$b) {
-	if(strcasecmp(normalise_link($a),normalise_link($b)) === 0)
+function link_compare($a, $b) {
+	if (strcasecmp(normalise_link($a), normalise_link($b)) === 0)
 		return true;
 
 	return false;
@@ -1167,8 +1189,10 @@ function theme_attachments(&$item) {
 			$icon = '';
 			$icontype = substr($r['type'],0,strpos($r['type'],'/'));
 
-			// FIXME This should probably be a giant "if" statement in the template so that we don't have icon names
-			// embedded in php code
+			/**
+			 * @FIXME This should probably be a giant "if" statement in the
+			 * template so that we don't have icon names embedded in php code.
+			 */
 
 			switch($icontype) {
 				case 'video':
@@ -1394,11 +1418,14 @@ function prepare_body(&$item,$attach = false) {
 	return $prep_arr['html'];
 }
 
-
-// Given a text string, convert from bbcode to html and add smilie icons.
-
-
-function prepare_text($text,$content_type = 'text/bbcode') {
+/**
+ * @brief Given a text string, convert from bbcode to html and add smilie icons.
+ *
+ * @param string $text
+ * @param sting $content_type
+ * @return string
+ */
+function prepare_text($text, $content_type = 'text/bbcode') {
 
 	switch($content_type) {
 		case 'text/plain':
@@ -1451,19 +1478,21 @@ function prepare_text($text,$content_type = 'text/bbcode') {
 
 /**
  * zidify_callback() and zidify_links() work together to turn any HTML a tags with class="zrl" into zid links
- * These will typically be generated by a bbcode '[zrl]' tag. This is done inside prepare_text() rather than bbcode() 
+ * These will typically be generated by a bbcode '[zrl]' tag. This is done inside prepare_text() rather than bbcode()
  * because the latter is used for general purpose conversions and the former is used only when preparing text for
  * immediate display.
- * 
+ *
  * Issues: Currently the order of HTML parameters in the text is somewhat rigid and inflexible.
- *    We assume it looks like <a class="zrl" href="xxxxxxxxxx"> and will not work if zrl and href appear in a different order. 
+ *    We assume it looks like \<a class="zrl" href="xxxxxxxxxx"\> and will not work if zrl and href appear in a different order.
+ *
+ * @param array $match
+ * @return string
  */
-
-
 function zidify_callback($match) {
 	$is_zid = ((feature_enabled(local_channel(),'sendzid')) || (strpos($match[1],'zrl')) ? true : false);
 	$replace = '<a' . $match[1] . ' href="' . (($is_zid) ? zid($match[2]) : $match[2]) . '"';			
 	$x = str_replace($match[0],$replace,$match[0]);
+
 	return $x;
 }
 
@@ -1472,6 +1501,7 @@ function zidify_img_callback($match) {
 	$replace = '<img' . $match[1] . ' src="' . (($is_zid) ? zid($match[2]) : $match[2]) . '"';
 
 	$x = str_replace($match[0],$replace,$match[0]);
+
 	return $x;
 }
 
@@ -1479,16 +1509,17 @@ function zidify_img_callback($match) {
 function zidify_links($s) {
 	$s = preg_replace_callback('/\<a(.*?)href\=\"(.*?)\"/ism','zidify_callback',$s);
 	$s = preg_replace_callback('/\<img(.*?)src\=\"(.*?)\"/ism','zidify_img_callback',$s);
+
 	return $s;
 }
 
-
 /**
- * return atom link elements for all of our hubs
+ * @brief Return atom link elements for all of our hubs.
+ *
+ * @return string
  */
-
 function feed_hublinks() {
-	$hub = get_config('system','huburl');
+	$hub = get_config('system', 'huburl');
 
 	$hubxml = '';
 	if(strlen($hub)) {
@@ -1498,6 +1529,7 @@ function feed_hublinks() {
 				$h = trim($h);
 				if(! strlen($h))
 					continue;
+
 				$hubxml .= '<link rel="hub" href="' . xmlify($h) . '" />' . "\n" ;
 			}
 		}
@@ -2094,15 +2126,16 @@ function extra_query_args() {
 }
 
 /**
- * This function removes the tag $tag from the text $body and replaces it with 
- * the appropiate link. 
- * 
- * @param unknown_type $body the text to replace the tag in
- * @param unknown_type $access_tag  - used to return tag ACL exclusions e.g. @!foo
- * @param unknown_type $str_tags string to add the tag to
- * @param unknown_type $profile_uid
- * @param unknown_type $tag the tag to replace
+ * @brief This function removes the tag $tag from the text $body and replaces it
+ * with the appropiate link.
  *
+ * @param App $a
+ * @param[in,out] string &$body the text to replace the tag in
+ * @param[in,out] string &$access_tag used to return tag ACL exclusions e.g. @!foo
+ * @param[in,out] string &$str_tags string to add the tag to
+ * @param int $profile_uid
+ * @param string $tag the tag to replace
+ * @param boolean $diaspora default false
  * @return boolean true if replaced, false if not replaced
  */
 function handle_tag($a, &$body, &$access_tag, &$str_tags, $profile_uid, $tag, $diaspora = false) {
diff --git a/include/zot.php b/include/zot.php
index 99a787cd9..28a2e8957 100644
--- a/include/zot.php
+++ b/include/zot.php
@@ -1,110 +1,113 @@
-<?php /** @file */
-
-require_once('include/crypto.php');
-require_once('include/items.php');
-require_once('include/hubloc.php');
-
+<?php
 /**
- * Red implementation of zot protocol.
+ * @file include/zot.php
+ * @brief RedMatrix implementation of zot protocol.
  *
  * https://github.com/friendica/red/wiki/zot
  * https://github.com/friendica/red/wiki/Zot---A-High-Level-Overview
  *
  */
 
+require_once('include/crypto.php');
+require_once('include/items.php');
+require_once('include/hubloc.php');
+
 
 /**
+ * @brief Generates a unique string for use as a zot guid.
  *
- * @function zot_new_uid($channel_nick)
- *
- *    Generates a unique string for use as a zot guid using our DNS-based url, the channel nickname and some entropy.
- *    The entropy ensures uniqueness against re-installs where the same URL and nickname are chosen.
- *    NOTE: zot doesn't require this to be unique. Internally we use a whirlpool hash of this guid and the signature
- *    of this guid signed with the channel private key. This can be verified and should make the probability of
- *    collision of the verified result negligible within the constraints of our immediate universe.
+ * Generates a unique string for use as a zot guid using our DNS-based url, the
+ * channel nickname and some entropy.
+ * The entropy ensures uniqueness against re-installs where the same URL and
+ * nickname are chosen.
  *
- * @param string channel_nickname = unique nickname of controlling entity
+ * @note zot doesn't require this to be unique. Internally we use a whirlpool
+ * hash of this guid and the signature of this guid signed with the channel
+ * private key. This can be verified and should make the probability of
+ * collision of the verified result negligible within the constraints of our
+ * immediate universe.
  *
+ * @param string $channel_nick a unique nickname of controlling entity
  * @returns string
- *
  */
-
 function zot_new_uid($channel_nick) {
 	$rawstr = z_root() . '/' . $channel_nick . '.' . mt_rand();
-	return(base64url_encode(hash('whirlpool',$rawstr,true),true));
+	return(base64url_encode(hash('whirlpool', $rawstr, true), true));
 }
 
-
 /**
+ * @brief Generates a portable hash identifier for a channel.
  *
- * function make_xchan_hash($guid,$guid_sig)
- *
- * Generates a portable hash identifier for the channel identified by $guid and signed with $guid_sig
- * This ID is portable across the network but MUST be calculated locally by verifying the signature
- * and can not be trusted as an identity.
+ * Generates a portable hash identifier for the channel identified by $guid and
+ * signed with $guid_sig.
+ * This ID is portable across the network but MUST be calculated locally by
+ * verifying the signature and can not be trusted as an identity.
  *
+ * @param string $guid
+ * @param string $guid_sig
  */
-
-function make_xchan_hash($guid,$guid_sig) {
-	return base64url_encode(hash('whirlpool',$guid . $guid_sig, true));
+function make_xchan_hash($guid, $guid_sig) {
+	return base64url_encode(hash('whirlpool', $guid . $guid_sig, true));
 }
 
 /**
- * @function zot_get_hublocs($hash)
- *     Given a zot hash, return all distinct hubs.
- *     This function is used in building the zot discovery packet
- *     and therefore should only be used by channels which are defined
- *     on this hub
- * @param string $hash - xchan_hash
- * @retuns array of hubloc (hub location structures)
- *    hubloc_id          int
- *    hubloc_guid        char(255)
- *	  hubloc_guid_sig    text
- *    hubloc_hash        char(255)
- *    hubloc_addr        char(255)
- *    hubloc_flags       int
- *    hubloc_status      int
- *    hubloc_url         char(255)
- *    hubloc_url_sig     text
- *	  hubloc_host        char(255)
- *    hubloc_callback    char(255)
- *    hubloc_connect     char(255)
- *    hubloc_sitekey     text
- *    hubloc_updated     datetime
- *    hubloc_connected   datetime
+ * @brief Given a zot hash, return all distinct hubs.
+ *
+ * This function is used in building the zot discovery packet and therefore
+ * should only be used by channels which are defined on this hub.
  *
+ * @param string $hash - xchan_hash
+ * @returns array of hubloc (hub location structures)
+ *  * \b hubloc_id          int
+ *  * \b hubloc_guid        char(255)
+ *  * \b hubloc_guid_sig    text
+ *  * \b hubloc_hash        char(255)
+ *  * \b hubloc_addr        char(255)
+ *  * \b hubloc_flags       int
+ *  * \b hubloc_status      int
+ *  * \b hubloc_url         char(255)
+ *  * \b hubloc_url_sig     text
+ *  * \b hubloc_host        char(255)
+ *  * \b hubloc_callback    char(255)
+ *  * \b hubloc_connect     char(255)
+ *  * \b hubloc_sitekey     text
+ *  * \b hubloc_updated     datetime
+ *  * \b hubloc_connected   datetime
  */
-
 function zot_get_hublocs($hash) {
 
-	/** Only search for active hublocs - e.g. those that haven't been marked deleted */
+	/* Only search for active hublocs - e.g. those that haven't been marked deleted */
 
 	$ret = q("select * from hubloc where hubloc_hash = '%s' and not ( hubloc_flags & %d )>0 order by hubloc_url ",
 		dbesc($hash),
 		intval(HUBLOC_FLAGS_DELETED)
 	);
+
 	return $ret;
 }
 
 /**
+ * @brief Builds a zot notification packet.
  *
- * @function zot_build_packet($channel,$type = 'notify',$recipients = null, $remote_key = null, $secret = null)
- *    builds a zot notification packet that you can either
- *    store in the queue with a message array or call zot_zot to immediately
- *    zot it to the other side
- *
- * @param array $channel     => sender channel structure
- * @param string $type       => packet type: one of 'ping', 'pickup', 'purge', 'refresh', 'force_refresh', 'notify', 'auth_check'
- * @param array $recipients  => envelope information, array ( 'guid' => string, 'guid_sig' => string ); empty for public posts
- * @param string $remote_key => optional public site key of target hub used to encrypt entire packet
- *    NOTE: remote_key and encrypted packets are required for 'auth_check' packets, optional for all others
- * @param string $secret     => random string, required for packets which require verification/callback
- *    e.g. 'pickup', 'purge', 'notify', 'auth_check'. Packet types 'ping', 'force_refresh', and 'refresh' do not require verification
+ * Builds a zot notification packet that you can either store in the queue with
+ * a message array or call zot_zot to immediately zot it to the other side.
  *
+ * @param array $channel
+ *   sender channel structure
+ * @param string $type
+ *   packet type: one of 'ping', 'pickup', 'purge', 'refresh', 'force_refresh', 'notify', 'auth_check'
+ * @param array $recipients
+ *   envelope information, array ( 'guid' => string, 'guid_sig' => string ); empty for public posts
+ * @param string $remote_key
+ *   optional public site key of target hub used to encrypt entire packet
+ *   NOTE: remote_key and encrypted packets are required for 'auth_check' packets, optional for all others
+ * @param string $secret
+ *   random string, required for packets which require verification/callback
+ *   e.g. 'pickup', 'purge', 'notify', 'auth_check'. Packet types 'ping', 'force_refresh', and 'refresh' do not require verification
+ * @param string $extra
  * @returns string json encoded zot packet
  */
-
-function zot_build_packet($channel,$type = 'notify',$recipients = null, $remote_key = null, $secret = null, $extra = null) {
+function zot_build_packet($channel, $type = 'notify', $recipients = null, $remote_key = null, $secret = null, $extra = null) {
 
 	$data = array(
 		'type' => $type,
@@ -118,84 +121,76 @@ function zot_build_packet($channel,$type = 'notify',$recipients = null, $remote_
 		'version' => ZOT_REVISION
 	);
 
-	if($recipients) {
-		for($x = 0; $x < count($recipients); $x ++)
+	if ($recipients) {
+		for ($x = 0; $x < count($recipients); $x ++)
 			unset($recipients[$x]['hash']);
 		$data['recipients'] = $recipients;
 	}
 
-	if($secret) {
+	if ($secret) {
 		$data['secret'] = $secret; 
 		$data['secret_sig'] = base64url_encode(rsa_sign($secret,$channel['channel_prvkey']));
 	}
 
-	if($extra) {
-		foreach($extra as $k => $v)
+	if ($extra) {
+		foreach ($extra as $k => $v)
 			$data[$k] = $v;
 	}
 
-
 	logger('zot_build_packet: ' . print_r($data,true), LOGGER_DATA);
 
 	// Hush-hush ultra top-secret mode
 
-	if($remote_key) {
+	if ($remote_key) {
 		$data = crypto_encapsulate(json_encode($data),$remote_key);
 	}
 
 	return json_encode($data);
 }
 
-
 /**
- * @function: zot_zot
- * @param: string $url
- * @param: array $data
+ * @brief
+ *
+ * @see z_post_url()
  *
- * @returns: array => see z_post_url for returned data format
+ * @param string $url
+ * @param array $data
+ * @return array see z_post_url() for returned data format
  */
- 
-
-
-function zot_zot($url,$data) {
-	return z_post_url($url,array('data' => $data));
+function zot_zot($url, $data) {
+	return z_post_url($url, array('data' => $data));
 }
 
 /**
- * @function: zot_finger
+ * @brief Look up information about channel.
  *
- * Look up information about channel
- * @param: string $webbie
- *   does not have to be host qualified e.g. 'foo' is treated as 'foo@thishub'
- * @param: array $channel
+ * @param string $webbie
+ *   does not have to be host qualified e.g. 'foo' is treated as 'foo\@thishub'
+ * @param array $channel
  *   (optional), if supplied permissions will be enumerated specifically for $channel
- * @param: boolean $autofallback
+ * @param boolean $autofallback
  *   fallback/failover to http if https connection cannot be established. Default is true.
  *
- * @returns: array => see z_post_url and mod/zfinger.php
+ * @return array see z_post_url() and \ref mod/zfinger.php
  */
+function zot_finger($webbie, $channel = null, $autofallback = true) {
 
-
-function zot_finger($webbie,$channel = null,$autofallback = true) {
-
-
-	if(strpos($webbie,'@') === false) {
+	if (strpos($webbie,'@') === false) {
 		$address = $webbie;
 		$host = get_app()->get_hostname();
-	}
-	else {
+	} else {
 		$address = substr($webbie,0,strpos($webbie,'@'));
 		$host = substr($webbie,strpos($webbie,'@')+1);
 	}
 
 	$xchan_addr = $address . '@' . $host;
 
-	if((! $address) || (! $xchan_addr)) {
+	if ((! $address) || (! $xchan_addr)) {
 		logger('zot_finger: no address :' . $webbie);
 		return array('success' => false);
-	}		
+	}
 	logger('using xchan_addr: ' . $xchan_addr, LOGGER_DATA);
-	
+
 	// potential issue here; the xchan_addr points to the primary hub.
 	// The webbie we were called with may not, so it might not be found
 	// unless we query for hubloc_addr instead of xchan_addr
@@ -207,26 +202,24 @@ function zot_finger($webbie,$channel = null,$autofallback = true) {
 		intval(HUBLOC_FLAGS_PRIMARY)
 	);
 
-	if($r) {
+	if ($r) {
 		$url = $r[0]['hubloc_url'];
 
-		if($r[0]['hubloc_network'] && $r[0]['hubloc_network'] !== 'zot') {
+		if ($r[0]['hubloc_network'] && $r[0]['hubloc_network'] !== 'zot') {
 			logger('zot_finger: alternate network: ' . $webbie);
 			logger('url: '.$url.', net: '.var_export($r[0]['hubloc_network'],true), LOGGER_DATA);
 			return array('success' => false);
-		}		
-	}
-	else {
+		}
+	} else {
 		$url = 'https://' . $host;
 	}
 
-			
 	$rhs = '/.well-known/zot-info';
 	$https = ((strpos($url,'https://') === 0) ? true : false);
 
 	logger('zot_finger: ' . $address . ' at ' . $url, LOGGER_DEBUG);
 
-	if($channel) {
+	if ($channel) {
 		$postvars = array(
 			'address'    => $address,
 			'target'     => $channel['channel_guid'],
@@ -236,88 +229,85 @@ function zot_finger($webbie,$channel = null,$autofallback = true) {
 
 		$result = z_post_url($url . $rhs,$postvars);
 
-
-		if((! $result['success']) && ($autofallback)) {
-			if($https) {
+		if ((! $result['success']) && ($autofallback)) {
+			if ($https) {
 				logger('zot_finger: https failed. falling back to http');
 				$result = z_post_url('http://' . $host . $rhs,$postvars);
 			}
 		}
-	}		
-	else {
+	} else {
 		$rhs .= '?f=&address=' . urlencode($address);
 
 		$result =  z_fetch_url($url . $rhs);
-		if((! $result['success']) && ($autofallback)) {
-			if($https) {
+		if ((! $result['success']) && ($autofallback)) {
+			if ($https) {
 				logger('zot_finger: https failed. falling back to http');
 				$result = z_fetch_url('http://' . $host . $rhs);
 			}
 		}
 	}
-	
-	if(! $result['success'])
-		logger('zot_finger: no results');
 
-	return $result;	 
+	if (! $result['success'])
+		logger('zot_finger: no results');
 
+	return $result;
 }
 
 /**
- * @function: zot_refresh($them, $channel = null, $force = false)
+ * @brief Refreshes after permission changed or friending, etc.
+ *
+ * zot_refresh is typically invoked when somebody has changed permissions of a channel and they are notified
+ * to fetch new permissions via a finger/discovery operation. This may result in a new connection 
+ * (abook entry) being added to a local channel and it may result in auto-permissions being granted. 
+ *
+ * Friending in zot is accomplished by sending a refresh packet to a specific channel which indicates a
+ * permission change has been made by the sender which affects the target channel. The hub controlling
+ * the target channel does targetted discovery (a zot-finger request requesting permissions for the local
+ * channel). These are decoded here, and if necessary and abook structure (addressbook) is created to store
+ * the permissions assigned to this channel. 
+ *
+ * Initially these abook structures are created with a 'pending' flag, so that no reverse permissions are 
+ * implied until this is approved by the owner channel. A channel can also auto-populate permissions in 
+ * return and send back a refresh packet of its own. This is used by forum and group communication channels
+ * so that friending and membership in the channel's "club" is automatic. 
  *
- *   zot_refresh is typically invoked when somebody has changed permissions of a channel and they are notified
- *   to fetch new permissions via a finger/discovery operation. This may result in a new connection 
- *   (abook entry) being added to a local channel and it may result in auto-permissions being granted. 
- * 
- *   Friending in zot is accomplished by sending a refresh packet to a specific channel which indicates a
- *   permission change has been made by the sender which affects the target channel. The hub controlling
- *   the target channel does targetted discovery (a zot-finger request requesting permissions for the local
- *   channel). These are decoded here, and if necessary and abook structure (addressbook) is created to store
- *   the permissions assigned to this channel. 
- *   
- *   Initially these abook structures are created with a 'pending' flag, so that no reverse permissions are 
- *   implied until this is approved by the owner channel. A channel can also auto-populate permissions in 
- *   return and send back a refresh packet of its own. This is used by forum and group communication channels
- *   so that friending and membership in the channel's "club" is automatic. 
- * 
  * @param array $them => xchan structure of sender
  * @param array $channel => local channel structure of target recipient, required for "friending" operations
+ * @param array $force default false
  *
- * @returns boolean true if successful, else false 
+ * @returns boolean true if successful, else false
  */
+function zot_refresh($them, $channel = null, $force = false) {
 
-function zot_refresh($them,$channel = null, $force = false) {
-
-	if(array_key_exists('xchan_network',$them) && ($them['xchan_network'] !== 'zot')) {
+	if (array_key_exists('xchan_network', $them) && ($them['xchan_network'] !== 'zot')) {
 		logger('zot_refresh: not got zot. ' . $them['xchan_name']);
 		return true;
 	}
 
 	logger('zot_refresh: them: ' . print_r($them,true), LOGGER_DATA);
-	if($channel)
+	if ($channel)
 		logger('zot_refresh: channel: ' . print_r($channel,true), LOGGER_DATA);
 
 	$url = null;
 
-	if($them['hubloc_url'])
+	if ($them['hubloc_url']) {
 		$url = $them['hubloc_url'];
-	else {
+	} else {
 		$r = q("select hubloc_url, hubloc_flags from hubloc where hubloc_hash = '%s'",
 			dbesc($them['xchan_hash'])
 		);
-		if($r) {
-			foreach($r as $rr) {
-				if($rr['hubloc_flags'] & HUBLOC_FLAGS_PRIMARY) {
+		if ($r) {
+			foreach ($r as $rr) {
+				if ($rr['hubloc_flags'] & HUBLOC_FLAGS_PRIMARY) {
 					$url = $rr['hubloc_url'];
 					break;
 				}
 			}
-			if(! $url)			
+			if (! $url)
 				$url = $r[0]['hubloc_url'];
 		}
 	}
-	if(! $url) {
+	if (! $url) {
 		logger('zot_refresh: no url');
 		return false;
 	}
@@ -330,12 +320,13 @@ function zot_refresh($them,$channel = null, $force = false) {
 		$postvars['key']        = $channel['channel_pubkey'];
 	}
 
-	if(array_key_exists('xchan_addr',$them) && $them['xchan_addr'])
+	if (array_key_exists('xchan_addr',$them) && $them['xchan_addr'])
 		$postvars['address'] = $them['xchan_addr'];
-	if(array_key_exists('xchan_hash',$them) && $them['xchan_hash'])
+	if (array_key_exists('xchan_hash',$them) && $them['xchan_hash'])
 		$postvars['guid_hash'] = $them['xchan_hash'];
-	if(array_key_exists('xchan_guid',$them) && $them['xchan_guid'] 
+	if (array_key_exists('xchan_guid',$them) && $them['xchan_guid']
 		&& array_key_exists('xchan_guid_sig',$them) && $them['xchan_guid_sig']) {
+
 		$postvars['guid'] = $them['xchan_guid'];
 		$postvars['guid_sig'] = $them['xchan_guid_sig'];
 	}
@@ -343,19 +334,19 @@ function zot_refresh($them,$channel = null, $force = false) {
 	$rhs = '/.well-known/zot-info';
 
 	$result = z_post_url($url . $rhs,$postvars);
-	
+
 	logger('zot_refresh: zot-info: ' . print_r($result,true), LOGGER_DATA);
 
-	if($result['success']) {
+	if ($result['success']) {
 
 		$j = json_decode($result['body'],true);
 
-		if(! (($j) && ($j['success']))) {
+		if (! (($j) && ($j['success']))) {
 			logger('zot_refresh: result not decodable');
 			return false;
 		}
 
-		$x = import_xchan($j,(($force) ? UPDATE_FLAGS_FORCED : UPDATE_FLAGS_UPDATED));
+		$x = import_xchan($j, (($force) ? UPDATE_FLAGS_FORCED : UPDATE_FLAGS_UPDATED));
 
 		if(! $x['success'])
 			return false;
@@ -415,7 +406,7 @@ function zot_refresh($them,$channel = null, $force = false) {
 					$next_birthday = $r[0]['abook_dob'];
 
 				$current_abook_connected = (($r[0]['abook_flags'] & ABOOK_FLAG_UNCONNECTED) ? 0 : 1);
-		
+
 				$y = q("update abook set abook_their_perms = %d, abook_dob = '%s'
 					where abook_xchan = '%s' and abook_channel = %d 
 					and not (abook_flags & %d) > 0 ",
@@ -430,8 +421,8 @@ function zot_refresh($them,$channel = null, $force = false) {
 
 					// if they are in your address book but you aren't in theirs, and/or this does not
 					// match your current connected state setting, toggle it. 
-					// FIXME: uncoverted to postgres
-					// FIXME: when this was enabled, all contacts became unconnected. Currently disabled intentionally
+					/** @FIXME uncoverted to postgres */
+					/** @FIXME when this was enabled, all contacts became unconnected. Currently disabled intentionally */
 //					$y1 = q("update abook set abook_flags = (abook_flags ^ %d)
 //						where abook_xchan = '%s' and abook_channel = %d 
 //						and not (abook_flags & %d) limit 1",
@@ -505,7 +496,7 @@ function zot_refresh($them,$channel = null, $force = false) {
 							'type'         => NOTIFY_INTRO,
 							'from_xchan'   => $x['hash'],
 							'to_xchan'     => $channel['channel_hash'],
-							'link'		   => z_root() . '/connedit/' . $new_connection[0]['abook_id'],
+							'link'         => z_root() . '/connedit/' . $new_connection[0]['abook_id'],
 						));
 					}
 
@@ -514,7 +505,6 @@ function zot_refresh($them,$channel = null, $force = false) {
 							|| (! ($new_connection[0]['abook_flags'] & ABOOK_FLAG_PENDING)) )
 							proc_run('php','include/onepoll.php',$new_connection[0]['abook_id']); 
 					}
-
 				}
 			}
 		}
@@ -524,25 +514,22 @@ function zot_refresh($them,$channel = null, $force = false) {
 }
 
 /**
- * @function: zot_gethub
+ * @brief Look up if channel is known and previously verified.
  *
- * A guid and a url, both signed by the sender, distinguish a known sender at a known location
- * This function looks these up to see if the channel is known and therefore previously verified. 
- * If not, we will need to verify it.
+ * A guid and a url, both signed by the sender, distinguish a known sender at a
+ * known location.
+ * This function looks these up to see if the channel is known and therefore
+ * previously verified. If not, we will need to verify it.
  *
- * @param array $arr
- *    $arr must contain: 
- *       string $arr['guid'] => guid of conversant
- *       string $arr['guid_sig'] => guid signed with conversant's private key
- *       string $arr['url'] => URL of the origination hub of this communication
- *       string $arr['url_sig'] => URL signed with conversant's private key
- *  
+ * @param array $arr an assoziative array which must contain:
+ *  * \e string \b guid => guid of conversant
+ *  * \e string \b guid_sig => guid signed with conversant's private key
+ *  * \e string \b url => URL of the origination hub of this communication
+ *  * \e string \b url_sig => URL signed with conversant's private key
  *
- * @returns: array => hubloc record
+ * @returns array|null null if site is blacklisted or not found, otherwise an
+ *  array with an hubloc record
  */
-
-
-		
 function zot_gethub($arr) {
 
 	if($arr['guid'] && $arr['guid_sig'] && $arr['url'] && $arr['url_sig']) {
@@ -581,26 +568,23 @@ function zot_gethub($arr) {
 }
 
 /**
- * @function zot_register_hub($arr)
+ * @brief Registers an unknown hup.
  *
- *   A communication has been received which has an unknown (to us) sender. 
- *   Perform discovery based on our calculated hash of the sender at the origination address.
- *   This will fetch the discovery packet of the sender, which contains the public key we 
- *   need to verify our guid and url signatures.
+ * A communication has been received which has an unknown (to us) sender. 
+ * Perform discovery based on our calculated hash of the sender at the
+ * origination address. This will fetch the discovery packet of the sender,
+ * which contains the public key we need to verify our guid and url signatures.
  *
- * @param array $arr
- *    $arr must contain: 
- *       string $arr['guid'] => guid of conversant
- *       string $arr['guid_sig'] => guid signed with conversant's private key
- *       string $arr['url'] => URL of the origination hub of this communication
- *       string $arr['url_sig'] => URL signed with conversant's private key
- *  
+ * @param array $arr an assoziative array which must contain:
+ *  * \e string \b guid => guid of conversant
+ *  * \e string \b guid_sig => guid signed with conversant's private key
+ *  * \e string \b url => URL of the origination hub of this communication
+ *  * \e string \b url_sig => URL signed with conversant's private key
  *
- * @returns array => 'success' (boolean true or false)
- *                   'message' (optional error string only if success is false)
+ * @returns array an assoziative array with:
+ *  * \b success boolean true or false
+ *  * \b message (optional) error string only if success is false
  */
-
-
 function zot_register_hub($arr) {
 
 	$result = array('success' => false);
@@ -640,15 +624,14 @@ function zot_register_hub($arr) {
 			}			
 		}
 	}
+
 	return $result;
 }
 
-
 /**
- * @function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED)
- *   Takes an associative array of a fetched discovery packet and updates
+ * @brief Takes an associative array of a fetched discovery packet and updates
  *   all internal data structures which need to be updated as a result.
- * 
+ *
  * @param array $arr => json_decoded discovery packet
  * @param int $ud_flags
  *    Determines whether to create a directory update record if any changes occur, default is UPDATE_FLAGS_UPDATED
@@ -659,13 +642,12 @@ function zot_register_hub($arr) {
  *    If set [typically by update_directory_entry()] indicates a specific update table row and more particularly 
  *    contains a particular address (ud_addr) which needs to be updated in that table.
  *
- * @returns array =>  'success' (boolean true or false)
- *                    'message' (optional error string only if success is false)
+ * @return associative array
+ *   * \e boolean \b success boolean true or false
+ *   * \e string \b message (optional) error string only if success is false
  */
-
 function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 
-
 	call_hooks('import_xchan', $arr);
 
 	$ret = array('success' => false);
@@ -700,11 +682,11 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 
 	$r = q("select * from xchan where xchan_hash = '%s' limit 1",
 		dbesc($xchan_hash)
-	);	
+	);
 
 	if(! array_key_exists('connect_url', $arr))
-		$arr['connect_url'] = '';		
-			
+		$arr['connect_url'] = '';
+
 	if(strpos($arr['address'],'/') !== false)
 		$arr['address'] = substr($arr['address'],0,strpos($arr['address'],'/'));
 
@@ -713,14 +695,13 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 			$import_photos = true;
 
 		// if we import an entry from a site that's not ours and either or both of us is off the grid - hide the entry.
-		// TODO: check if we're the same directory realm, which would mean we are allowed to see it
+		/** @TODO: check if we're the same directory realm, which would mean we are allowed to see it */
 
 		$dirmode = get_config('system','directory_mode'); 
 
 		if((($arr['site']['directory_mode'] === 'standalone') || ($dirmode & DIRECTORY_MODE_STANDALONE)) && ($arr['site']['url'] != z_root()))
 			$arr['searchable'] = false;
 
-
 		$hidden = (1 - intval($arr['searchable']));
 
 		// Be careful - XCHAN_FLAGS_HIDDEN should evaluate to 1
@@ -770,11 +751,9 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 			$what .= 'xchan ';
 			$changed = true;
 		}
-	}
-	else {
+	} else {
 		$import_photos = true;
 
-
 		if((($arr['site']['directory_mode'] === 'standalone') || ($dirmode & DIRECTORY_MODE_STANDALONE))
 && ($arr['site']['url'] != z_root()))
 			$arr['searchable'] = false;
@@ -789,7 +768,7 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 			$new_flags |= XCHAN_FLAGS_SELFCENSORED;
 		if(array_key_exists('deleted',$arr) && $arr['deleted'])
 			$new_flags |= XCHAN_FLAGS_DELETED;
-		
+
 		$x = q("insert into xchan ( xchan_hash, xchan_guid, xchan_guid_sig, xchan_pubkey, xchan_photo_mimetype,
 				xchan_photo_l, xchan_addr, xchan_url, xchan_connurl, xchan_follow, xchan_connpage, xchan_name, xchan_network, xchan_photo_date, xchan_name_date, xchan_flags)
 				values ( '%s', '%s', '%s', '%s' , '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', %d) ",
@@ -813,11 +792,9 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 
 		$what .= 'new_xchan';
 		$changed = true;
+	}
 
-	}				
-
-
-	if($import_photos) {
+	if ($import_photos) {
 
 		require_once('include/photo/photo_driver.php');
 
@@ -826,9 +803,9 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 		$local = q("select channel_account_id, channel_id from channel where channel_hash = '%s' limit 1",
 			dbesc($xchan_hash)
 		);
-		if($local) {
-			$ph = z_fetch_url($arr['photo'],true);
-			if($ph['success']) {
+		if ($local) {
+			$ph = z_fetch_url($arr['photo'], true);
+			if ($ph['success']) {
 				import_channel_photo($ph['body'], $arr['photo_mimetype'], $local[0]['channel_account_id'],$local[0]['channel_id']);
 				// reset the names in case they got messed up when we had a bug in this function
 				$photos = array(
@@ -839,12 +816,11 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 					false
 				);
 			}
+		} else {
+			$photos = import_profile_photo($arr['photo'], $xchan_hash);
 		}
-		else {
-			$photos = import_profile_photo($arr['photo'],$xchan_hash);
-		}
-		if($photos) {
-			if($photos[4]) {
+		if ($photos) {
+			if ($photos[4]) {
 				// importing the photo failed somehow. Leave the photo_date alone so we can try again at a later date.
 				// This often happens when somebody joins the matrix with a bad cert. 
 				$r = q("update xchan set xchan_photo_l = '%s', xchan_photo_m = '%s', xchan_photo_s = '%s', xchan_photo_mimetype = '%s'
@@ -855,8 +831,7 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 					dbesc($photos[3]),
 					dbesc($xchan_hash)
 				);
-			}
-			else {
+			} else {
 				$r = q("update xchan set xchan_photo_date = '%s', xchan_photo_l = '%s', xchan_photo_m = '%s', xchan_photo_s = '%s', xchan_photo_mimetype = '%s'
 					where xchan_hash = '%s'",
 					dbescdate(datetime_convert('UTC','UTC',$arr['photo_updated'])),
@@ -875,8 +850,7 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 	// what we are missing for true hub independence is for any changes in the primary hub to 
 	// get reflected not only in the hublocs, but also to update the URLs and addr in the appropriate xchan
 
-
-	$s = sync_locations($arr,$arr);
+	$s = sync_locations($arr, $arr);
 
 	if($s) {
 		if($s['change_message'])
@@ -915,8 +889,7 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 				$what .= 'profile ';
 				$changed = true;
 			}
-		}
-		else {
+		} else {
 			logger('import_xchan: profile not available - hiding');
 			// they may have made it private
 			$r = q("delete from xprof where xprof_hash = '%s'",
@@ -935,7 +908,6 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 			$changed = true;
 		}
 	}
-	
 
 	if(($changed) || ($ud_flags == UPDATE_FLAGS_FORCED)) {
 		$guid = random_string() . '@' . get_app()->get_hostname();		
@@ -956,60 +928,52 @@ function import_xchan($arr,$ud_flags = UPDATE_FLAGS_UPDATED, $ud_arr = null) {
 		$ret['hash'] = $xchan_hash;
 	}
 
-
-
 	logger('import_xchan: result: ' . print_r($ret,true), LOGGER_DATA);
 	return $ret;
 }
 
 /**
- * @function zot_process_response($hub,$arr,$outq) {
- *    Called immediately after sending a zot message which is using queue processing
- *    Updates the queue item according to the response result and logs any information
- *    returned to aid communications troubleshooting.
+ * @brief Called immediately after sending a zot message which is using queue processing.
+ *
+ * Updates the queue item according to the response result and logs any information
+ * returned to aid communications troubleshooting.
  *
  * @param string $hub - url of site we just contacted
  * @param array $arr - output of z_post_url()
  * @param array $outq - The queue structure attached to this request
- *
- * @returns nothing
  */
+function zot_process_response($hub, $arr, $outq) {
 
-
-function zot_process_response($hub,$arr,$outq) {
-
-	if(! $arr['success']) {
+	if (! $arr['success']) {
 		logger('zot_process_response: failed: ' . $hub);
 		return;
 	}
 
-	$x = json_decode($arr['body'],true);
+	$x = json_decode($arr['body'], true);
 
-	if(! $x) {
+	if (! $x) {
 		logger('zot_process_response: No json from ' . $hub);
 		logger('zot_process_response: headers: ' . print_r($arr['header'],true), LOGGER_DATA);
 	}
 
 	// update the timestamp for this site
 
-	$r = q("update site set site_update = '%s' where site_url = '%s'",
+	q("update site set site_update = '%s' where site_url = '%s'",
 		dbesc(datetime_convert()),
 		dbesc(dirname($hub))
 	);
 
-
 	// synchronous message types are handled immediately
 	// async messages remain in the queue until processed.
 
-	if(intval($outq['outq_async'])) {
-		$r = q("update outq set outq_delivered = 1, outq_updated = '%s' where outq_hash = '%s' and outq_channel = %d",
+	if (intval($outq['outq_async'])) {
+		q("update outq set outq_delivered = 1, outq_updated = '%s' where outq_hash = '%s' and outq_channel = %d",
 			dbesc(datetime_convert()),
 			dbesc($outq['outq_hash']),
 			intval($outq['outq_channel'])
 		);
-	}
-	else {
-		$r = q("delete from outq where outq_hash = '%s' and outq_channel = %d",
+	} else {
+		q("delete from outq where outq_hash = '%s' and outq_channel = %d",
 			dbesc($outq['outq_hash']),
 			intval($outq['outq_channel'])
 		);
@@ -1019,19 +983,20 @@ function zot_process_response($hub,$arr,$outq) {
 }
 
 /**
- * @function zot_fetch($arr)
+ * @brief
+ *
+ * We received a notification packet (in mod/post.php) that a message is waiting for us, and we've verified the sender.
+ * Now send back a pickup message, using our message tracking ID ($arr['secret']), which we will sign with our site private key.
+ * The entire pickup message is encrypted with the remote site's public key. 
+ * If everything checks out on the remote end, we will receive back a packet containing one or more messages,
+ * which will be processed and delivered before this function ultimately returns.
+ *
+ * @see zot_import()
  *
- *     We received a notification packet (in mod/post.php) that a message is waiting for us, and we've verified the sender.
- *     Now send back a pickup message, using our message tracking ID ($arr['secret']), which we will sign with our site private key.
- *     The entire pickup message is encrypted with the remote site's public key. 
- *     If everything checks out on the remote end, we will receive back a packet containing one or more messages,
- *     which will be processed and delivered before this function ultimately returns.
- *   
  * @param array $arr
  *     decrypted and json decoded notify packet from remote site
+ * @return array from zot_import()
  */
- 
-
 function zot_fetch($arr) {
 
 	logger('zot_fetch: ' . print_r($arr,true), LOGGER_DATA);
@@ -1054,31 +1019,36 @@ function zot_fetch($arr) {
 	);
 
 	$datatosend = json_encode(crypto_encapsulate(json_encode($data),$ret_hub['hubloc_sitekey']));
-	
+
 	$fetch = zot_zot($url,$datatosend);
 	$result = zot_import($fetch, $arr['sender']['url']);
+
 	return $result;
 }
 
 /**
- * @function zot_import
+ * @brief Process incoming array of messages.
  * 
  * Process an incoming array of messages which were obtained via pickup, and 
  * import, update, delete as directed.
- * 
- * @param array $arr => 'pickup' structure returned from remote site
- * @param string $sender_url => the url specified by the sender in the initial communication
- *       we will verify the sender and url in each returned message structure and also verify
- *       that all the messages returned match the site url that we are currently processing.
- * 
- * The message types handled here are 'activity' (e.g. posts), 'mail' , 'profile', 'location', 
- * and 'channel_sync'
- * 
- * @returns array => array ( [0] => string $channel_hash, [1] => string $delivery_status, [2] => string $address )
- *    suitable for logging remotely, enumerating the processing results of each message/recipient combination.
- * 
+ *
+ * The message types handled here are 'activity' (e.g. posts), 'mail' ,
+ * 'profile', 'location' and 'channel_sync'.
+ *
+ * @param array $arr
+ *  'pickup' structure returned from remote site
+ * @param string $sender_url
+ *  the url specified by the sender in the initial communication.
+ *  We will verify the sender and url in each returned message structure and
+ *  also verify that all the messages returned match the site url that we are
+ *  currently processing.
+ *
+ * @returns array
+ * suitable for logging remotely, enumerating the processing results of each message/recipient combination
+ *  * [0] => \e string $channel_hash
+ *  * [1] => \e string $delivery_status
+ *  * [2] => \e string $address
  */
-
 function zot_import($arr, $sender_url) {
 
 	$data = json_decode($arr['body'],true);
@@ -1168,7 +1138,7 @@ function zot_import($arr, $sender_url) {
 					}
 				}
 
-				logger('public post');				
+				logger('public post');
 
 				// Public post. look for any site members who are or may be accepting posts from this sender
 				// and who are allowed to see them based on the sender's permissions
@@ -1190,7 +1160,6 @@ function zot_import($arr, $sender_url) {
 						$i['message']['flags'] = array();
 					if(! in_array('private',$i['message']['flags']))
 						$i['message']['flags'][] = 'private';
-
 				}
 			}
 
@@ -1215,8 +1184,8 @@ function zot_import($arr, $sender_url) {
 				logger('zot_import: no deliveries on this site');
 				continue;
 			}
-							
-			if($i['message']) { 
+
+			if($i['message']) {
 				if($i['message']['type'] === 'activity') {
 					$arr = get_item_elements($i['message']);
 
@@ -1230,7 +1199,6 @@ function zot_import($arr, $sender_url) {
 
 					$relay = ((array_key_exists('flags',$i['message']) && in_array('relay',$i['message']['flags'])) ? true : false);
 					$result = process_delivery($i['notify']['sender'],$arr,$deliveries,$relay,false,$message_request);
-
 				}
 				elseif($i['message']['type'] === 'mail') {
 					$arr = get_mail_elements($i['message']);
@@ -1238,9 +1206,7 @@ function zot_import($arr, $sender_url) {
 					logger('Mail received: ' . print_r($arr,true), LOGGER_DATA);
 					logger('Mail recipients: ' . print_r($deliveries,true), LOGGER_DATA);
 
-
 					$result = process_mail_delivery($i['notify']['sender'],$arr,$deliveries);
-
 				}
 				elseif($i['message']['type'] === 'profile') {
 					$arr = get_profile_elements($i['message']);
@@ -1249,9 +1215,7 @@ function zot_import($arr, $sender_url) {
 					logger('Profile recipients: ' . print_r($deliveries,true), LOGGER_DATA);
 
 					$result = process_profile_delivery($i['notify']['sender'],$arr,$deliveries);
-
 				}
-
 				elseif($i['message']['type'] === 'channel_sync') {
 					// $arr = get_channelsync_elements($i['message']);
 
@@ -1270,31 +1234,34 @@ function zot_import($arr, $sender_url) {
 					
 					$result = process_location_delivery($i['notify']['sender'],$arr,$deliveries);
 				}
-
 			}
 			if($result){
-				$return = array_merge($return,$result);
+				$return = array_merge($return, $result);
 			}
 		}
 	}
 
 	return $return;
-
 }
 
 
 // A public message with no listed recipients can be delivered to anybody who
-// has PERMS_NETWORK for that type of post, PERMS_AUTHED (in-network senders are 
+// has PERMS_NETWORK for that type of post, PERMS_AUTHED (in-network senders are
 // by definition authenticated) or PERMS_SITE and is one the same
 // site, or PERMS_SPECIFIC and the sender is a contact who is granted 
 // permissions via their connection permissions in the address book.
 // Here we take a given message and construct a list of hashes of everybody
-// on the site that we should try and deliver to.  
+// on the site that we should try and deliver to.
 // Some of these will be rejected, but this gives us a place to start.
 
+/**
+ * @brief
+ *
+ * @param array $msg
+ * @return NULL|array
+ */
 function public_recips($msg) {
 
-
 	require_once('include/identity.php');
 
 	$check_mentions = false;
@@ -1363,7 +1330,6 @@ function public_recips($msg) {
 					or (  " . $col . " & " . intval(PERMS_PUBLIC) . ") > 0 
 					or (  " . $col . " & " . intval(PERMS_AUTHED) . ") > 0 ) ";
 
-
 	$r = q("select channel_hash as hash from channel $sql or channel_hash = '%s' 
 		and ( channel_pageflags & " . intval(PAGE_REMOVED) . " ) = 0 ",
 		dbesc($msg['notify']['sender']['hash'])
@@ -1514,7 +1480,6 @@ function allowed_public_recips($msg) {
 		return $results;
 	}
 
-
 	return array();
 }
 
@@ -1544,7 +1509,6 @@ function process_delivery($sender,$arr,$deliveries,$relay,$public = false,$reque
 			continue;
 		}
 
-
 		$channel = $r[0];
 
 		// allow public postings to the sys channel regardless of permissions, but not
@@ -1763,7 +1727,6 @@ function remove_community_tag($sender,$arr,$uid) {
 		return;
 
 	logger('remove_community_tag: invoked');
- 
 
 	if(! get_pconfig($uid,'system','blocktags')) {
 		logger('remove_community tag: permission denied.');
@@ -1806,8 +1769,8 @@ function remove_community_tag($sender,$arr,$uid) {
 		logger('remove_community_tag: no parent message');
 		return;
 	}
-	
-	$x = q("delete from term where uid = %d and oid = %d and otype = %d and type = %d and term = '%s' and url = '%s'",
+
+	q("delete from term where uid = %d and oid = %d and otype = %d and type = %d and term = '%s' and url = '%s'",
 		intval($uid),
 		intval($r[0]['id']),
 		intval(TERM_OBJ_POST),
@@ -1815,8 +1778,6 @@ function remove_community_tag($sender,$arr,$uid) {
 		dbesc($i['object']['title']),
 		dbesc(get_rel_link($i['object']['link'],'alternate'))
 	);
-
-	return;
 }
 
 function update_imported_item($sender,$item,$uid) {
@@ -1826,12 +1787,20 @@ function update_imported_item($sender,$item,$uid) {
 		logger('update_imported_item: failed: ' . $x['message']);
 	else
 		logger('update_imported_item');
-
 }
 
-function delete_imported_item($sender,$item,$uid,$relay) {
+/**
+ * @brief Deletes an imported item.
+ *
+ * @param array $sender
+ * @param array $item
+ * @param int $uid
+ * @param unknown $relay
+ * @return boolean|int post_id
+ */
+function delete_imported_item($sender, $item, $uid, $relay) {
 
-	logger('delete_imported_item invoked',LOGGER_DEBUG);
+	logger('delete_imported_item invoked', LOGGER_DEBUG);
 
 	$ownership_valid = false;
 	$item_found = false;
@@ -1841,13 +1810,13 @@ function delete_imported_item($sender,$item,$uid,$relay) {
 		dbesc($item['mid']),
 		intval($uid)
 	);
-	if($r) {
-		if($r[0]['author_xchan'] === $sender['hash'] || $r[0]['owner_xchan'] === $sender['hash'] || $r[0]['source_xchan'] === $sender['hash'])
+	if ($r) {
+		if ($r[0]['author_xchan'] === $sender['hash'] || $r[0]['owner_xchan'] === $sender['hash'] || $r[0]['source_xchan'] === $sender['hash'])
 			$ownership_valid = true;
+
 		$post_id = $r[0]['id'];
 		$item_found = true;
-	}
-	else {
+	} else {
 
 		// perhaps the item is still in transit and the delete notification got here before the actual item did. Store it with the deleted flag set.
 		// item_store() won't try to deliver any notifications or start delivery chains if this flag is set. 
@@ -1855,22 +1824,24 @@ function delete_imported_item($sender,$item,$uid,$relay) {
 		// But this will ensure that if the (undeleted) original post comes in at a later date, we'll reject it because it will have an older timestamp.  
 
 		logger('delete received for non-existent item - storing item data.');
-		if($arr['author_xchan'] === $sender['hash'] || $arr['owner_xchan'] === $sender['hash'] || $arr['source_xchan'] === $sender['hash']) {
+
+		/** @BUG $arr is undefined here, so this is dead code */
+		if ($arr['author_xchan'] === $sender['hash'] || $arr['owner_xchan'] === $sender['hash'] || $arr['source_xchan'] === $sender['hash']) {
 			$ownership_valid = true;
 			$item_result = item_store($arr);
 			$post_id = $item_result['item_id'];
 		}
 	}
 
-	if($ownership_valid == false) {
+	if ($ownership_valid === false) {
 		logger('delete_imported_item: failed: ownership issue');
 		return false;
 	}
 
-	if($item_found) {
-		if($r[0]['item_restrict'] & ITEM_DELETED) {
+	if ($item_found) {
+		if ($r[0]['item_restrict'] & ITEM_DELETED) {
 			logger('delete_imported_item: item was already deleted');
-			if(! $relay)
+			if (! $relay)
 				return false;
 
 			// This is a bit hackish, but may have to suffice until the notification/delivery loop is optimised
@@ -1879,9 +1850,9 @@ function delete_imported_item($sender,$item,$uid,$relay) {
 			// code path downstream can relay it again (causing a loop). Since it's already gone it's not coming
 			// back, and we aren't going to (or shouldn't at any rate) delete it again in the future - so losing
 			// this information from the metadata should have no other discernible impact. 
-			
-			if(($r[0]['id'] != $r[0]['parent']) && ($r[0]['item_flags'] & ITEM_ORIGIN)) {
-				$x = q("update item set item_flags = %d where id = %d and uid = %d",
+
+			if (($r[0]['id'] != $r[0]['parent']) && ($r[0]['item_flags'] & ITEM_ORIGIN)) {
+				q("update item set item_flags = %d where id = %d and uid = %d",
 					intval($r[0]['item_flags'] ^ ITEM_ORIGIN),
 					intval($r[0]['id']),
 					intval($r[0]['uid'])
@@ -1889,14 +1860,13 @@ function delete_imported_item($sender,$item,$uid,$relay) {
 			}
 		} 
 
-		
 		require_once('include/items.php');
 
 		// Use phased deletion to set the deleted flag, call both tag_deliver and the notifier to notify downstream channels
 		// and then clean up after ourselves with a cron job after several days to do the delete_item_lowlevel() (DROPITEM_PHASE2).
 
-		drop_item($post_id,false, DROPITEM_PHASE1);
-		tag_deliver($uid,$post_id);
+		drop_item($post_id, false, DROPITEM_PHASE1);
+		tag_deliver($uid, $post_id);
 	}
 
 	return $post_id;
@@ -1904,17 +1874,13 @@ function delete_imported_item($sender,$item,$uid,$relay) {
 
 function process_mail_delivery($sender,$arr,$deliveries) {
 
-
 	$result = array();
 
-
 	if($sender['hash'] != $arr['from_xchan']) {
 		logger('process_mail_delivery: sender is not mail author');
 		return;
 	}
 
-
-	
 	foreach($deliveries as $d) {
 		$r = q("select * from channel where channel_hash = '%s' limit 1",
 			dbesc($d['hash'])
@@ -1946,7 +1912,7 @@ function process_mail_delivery($sender,$arr,$deliveries) {
 				$result[] = array($d['hash'],'mail recalled',$channel['channel_name'],$arr['mid']);
 				logger('mail_recalled');
 			}
-			else {				
+			else {
 				$result[] = array($d['hash'],'duplicate mail received',$channel['channel_name'],$arr['mid']);
 				logger('duplicate mail received');
 			}
@@ -1974,7 +1940,6 @@ function process_rating_delivery($sender,$arr) {
 		dbesc($sender['hash'])
 	);
 
-
 	if((! $z) || (! rsa_verify($arr['target'] . '.' . $arr['rating'] . '.' . $arr['rating_text'], base64url_decode($arr['signature']),$z[0]['xchan_pubkey']))) {
 		logger('failed to verify rating');
 		return;
@@ -2012,7 +1977,6 @@ function process_rating_delivery($sender,$arr) {
 		);
 		logger('rating created');
 	}
-	return;
 }
 
 
@@ -2080,7 +2044,6 @@ function sync_locations($sender,$arr,$absolute = false) {
 				continue;
 			}
 
-
 			for($x = 0; $x < count($xisting); $x ++) {
 				if(($xisting[$x]['hubloc_url'] === $location['url']) 
 					&& ($xisting[$x]['hubloc_sitekey'] === $location['sitekey'])) {
@@ -2250,7 +2213,7 @@ function sync_locations($sender,$arr,$absolute = false) {
 				);
 				if($r)
 					hubloc_change_primary($r[0]);
-			}		
+			}
 		}
 
 		// get rid of any hubs we have for this channel which weren't reported.
@@ -2275,17 +2238,23 @@ function sync_locations($sender,$arr,$absolute = false) {
 	$ret['changed'] = $changed;
 
 	return $ret;
-
 }
 
-
+/**
+ * @brief Returns an array with all known distinct hubs for this channel.
+ *
+ * @see zot_get_hublocs()
+ * @param array $channel an assoziative array which must contain
+ *  * \e string \b channel_hash the hash of the channel
+ * @return array an array with assoziated arrays
+ */
 function zot_encode_locations($channel) {
 	$ret = array();
 
 	$x = zot_get_hublocs($channel['channel_hash']);
-	if($x && count($x)) {
-		foreach($x as $hub) {
-			if(! ($hub['hubloc_flags'] & HUBLOC_FLAGS_UNVERIFIED)) {
+	if ($x && count($x)) {
+		foreach ($x as $hub) {
+			if (! ($hub['hubloc_flags'] & HUBLOC_FLAGS_UNVERIFIED)) {
 				$ret[] = array(
 					'host'     => $hub['hubloc_host'],
 					'address'  => $hub['hubloc_addr'],
@@ -2299,24 +2268,25 @@ function zot_encode_locations($channel) {
 			}
 		}
 	}
+
 	return $ret;
 }
 
 
-
-
-
-/*
- * @function import_directory_profile
+/**
+ * @brief Imports a directory profile.
  * 
- * @returns boolean $updated if something changed
- *
+ * @param string $hash
+ * @param array $profile
+ * @param string $addr
+ * @param number $ud_flags
+ * @param number $suppress_update default 0
+ * @return boolean $updated if something changed
  */
-
-function import_directory_profile($hash,$profile,$addr,$ud_flags = UPDATE_FLAGS_UPDATED, $suppress_update = 0) {
+function import_directory_profile($hash, $profile, $addr, $ud_flags = UPDATE_FLAGS_UPDATED, $suppress_update = 0) {
 
 	logger('import_directory_profile', LOGGER_DEBUG);
-	if(! $hash)
+	if (! $hash)
 		return false;
 
 	$arr = array();
@@ -2337,11 +2307,11 @@ function import_directory_profile($hash,$profile,$addr,$ud_flags = UPDATE_FLAGS_
 	$arr['xprof_hometown']     = (($profile['hometown'])    ? htmlspecialchars($profile['hometown'],    ENT_COMPAT,'UTF-8',false) : '');
 
 	$clean = array();
-	if(array_key_exists('keywords',$profile) and is_array($profile['keywords'])) {
+	if (array_key_exists('keywords', $profile) and is_array($profile['keywords'])) {
 		import_directory_keywords($hash,$profile['keywords']);
-		foreach($profile['keywords'] as $kw) {
-			$kw = trim(htmlspecialchars($kw,ENT_COMPAT,'UTF-8',false));
-			$kw = trim($kw,',');
+		foreach ($profile['keywords'] as $kw) {
+			$kw = trim(htmlspecialchars($kw,ENT_COMPAT, 'UTF-8', false));
+			$kw = trim($kw, ',');
 			$clean[] = $kw;
 		}
 	}
@@ -2352,48 +2322,47 @@ function import_directory_profile($hash,$profile,$addr,$ud_flags = UPDATE_FLAGS_
 	// These are not translated, so the German "erwachsenen" keyword will not censor the directory profile. Only the English form - "adult".   
 
 
-	if(in_arrayi('nsfw',$clean) || in_arrayi('adult',$clean)) {
+	if (in_arrayi('nsfw', $clean) || in_arrayi('adult', $clean)) {
 		q("update xchan set xchan_flags = (xchan_flags | %d) where xchan_hash = '%s'",
 			intval(XCHAN_FLAGS_SELFCENSORED),
 			dbesc($hash)
 		);
 	}
 
-
 	$r = q("select * from xprof where xprof_hash = '%s' limit 1",
 		dbesc($hash)
 	);
-	
-	if($arr['xprof_age'] > 150) 
+
+	if ($arr['xprof_age'] > 150) 
 		$arr['xprof_age'] = 150;
-	if($arr['xprof_age'] < 0)
+	if ($arr['xprof_age'] < 0)
 		$arr['xprof_age'] = 0;
-	
-	if($r) {
+
+	if ($r) {
 		$update = false;
-		foreach($r[0] as $k => $v) {
-			if((array_key_exists($k,$arr)) && ($arr[$k] != $v)) {
+		foreach ($r[0] as $k => $v) {
+			if ((array_key_exists($k,$arr)) && ($arr[$k] != $v)) {
 				logger('import_directory_profile: update ' . $k . ' => ' . $arr[$k]);
 				$update = true;
 				break;
 			}
 		}
-		if($update) {
-			$x = q("update xprof set 
+		if ($update) {
+			q("update xprof set 
 				xprof_desc = '%s', 
 				xprof_dob = '%s', 
-				xprof_age = %d,
+				xprof_age = %d, 
 				xprof_gender = '%s', 
 				xprof_marital = '%s', 
 				xprof_sexual = '%s', 
 				xprof_locale = '%s', 
 				xprof_region = '%s', 
 				xprof_postcode = '%s', 
-				xprof_country = '%s',
-				xprof_about = '%s',
-				xprof_homepage = '%s',
-				xprof_hometown = '%s',
-				xprof_keywords = '%s'
+				xprof_country = '%s', 
+				xprof_about = '%s', 
+				xprof_homepage = '%s', 
+				xprof_hometown = '%s', 
+				xprof_keywords = '%s' 
 				where xprof_hash = '%s'",
 				dbesc($arr['xprof_desc']),
 				dbesc($arr['xprof_dob']),
@@ -2412,11 +2381,10 @@ function import_directory_profile($hash,$profile,$addr,$ud_flags = UPDATE_FLAGS_
 				dbesc($arr['xprof_hash'])
 			);
 		}
-	}
-	else {
+	} else {
 		$update = true;
 		logger('import_directory_profile: new profile ');
-		$x = q("insert into xprof (xprof_hash, xprof_desc, xprof_dob, xprof_age, xprof_gender, xprof_marital, xprof_sexual, xprof_locale, xprof_region, xprof_postcode, xprof_country, xprof_about, xprof_homepage, xprof_hometown, xprof_keywords) values ('%s', '%s', '%s', %d, '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s') ",
+		q("insert into xprof (xprof_hash, xprof_desc, xprof_dob, xprof_age, xprof_gender, xprof_marital, xprof_sexual, xprof_locale, xprof_region, xprof_postcode, xprof_country, xprof_about, xprof_homepage, xprof_hometown, xprof_keywords) values ('%s', '%s', '%s', %d, '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s') ",
 			dbesc($arr['xprof_hash']),
 			dbesc($arr['xprof_desc']),
 			dbesc($arr['xprof_dob']),
@@ -2438,8 +2406,9 @@ function import_directory_profile($hash,$profile,$addr,$ud_flags = UPDATE_FLAGS_
 	$d = array('xprof' => $arr, 'profile' => $profile, 'update' => $update);
 	call_hooks('import_directory_profile', $d);
 
-	if(($d['update']) && (! $suppress_update))
+	if (($d['update']) && (! $suppress_update))
 		update_modtime($arr['xprof_hash'],random_string() . '@' . get_app()->get_hostname(), $addr, $ud_flags);
+
 	return $d['update'];
 }
 
@@ -2528,7 +2497,6 @@ function import_site($arr,$pubkey) {
 	$site_directory = 0;
 	if($arr['directory_mode'] == 'normal')
 		$site_directory = DIRECTORY_MODE_NORMAL;
-
 	if($arr['directory_mode'] == 'primary')
 		$site_directory = DIRECTORY_MODE_PRIMARY;
 	if($arr['directory_mode'] == 'secondary')
@@ -2536,9 +2504,6 @@ function import_site($arr,$pubkey) {
 	if($arr['directory_mode'] == 'standalone')
 		$site_directory = DIRECTORY_MODE_STANDALONE;
 
-
-
-
 	$register_policy = 0;
 	if($arr['register_policy'] == 'closed')
 		$register_policy = REGISTER_CLOSED;
@@ -2569,16 +2534,16 @@ function import_site($arr,$pubkey) {
 		if(! $x['success'])
 			$access_policy = ACCESS_PRIVATE;
 	}
-	
+
 	$directory_url = htmlspecialchars($arr['directory_url'],ENT_COMPAT,'UTF-8',false);
 	$url = htmlspecialchars(strtolower($arr['url']),ENT_COMPAT,'UTF-8',false);
 	$sellpage = htmlspecialchars($arr['sellpage'],ENT_COMPAT,'UTF-8',false);
 	$site_location = htmlspecialchars($arr['location'],ENT_COMPAT,'UTF-8',false);
 	$site_realm = htmlspecialchars($arr['realm'],ENT_COMPAT,'UTF-8',false);
 
-	// You can have one and only one primary directory per realm. 
+	// You can have one and only one primary directory per realm.
 	// Downgrade any others claiming to be primary. As they have
-	// flubbed up this badly already, don't let them be directory servers at all. 
+	// flubbed up this badly already, don't let them be directory servers at all.
 
 	if(($site_directory === DIRECTORY_MODE_PRIMARY) 
 		&& ($site_realm === get_directory_realm()) 
@@ -2586,7 +2551,6 @@ function import_site($arr,$pubkey) {
 		$site_directory = DIRECTORY_MODE_NORMAL;
 	} 
 
-
 	if($exists) {
 		if(($siterecord['site_flags'] != $site_directory)
 			|| ($siterecord['site_access'] != $access_policy)
@@ -2644,11 +2608,9 @@ function import_site($arr,$pubkey) {
 	}
 
 	return $update;
-
 }
 
 
-
 /**
  * Send a zot packet to all hubs where this channel is duplicated, refreshing
  * such things as personal settings, channel permissions, address book updates, etc.
@@ -2714,7 +2676,7 @@ function build_sync_packet($uid = 0, $packet = null, $groups_changed = false) {
 			$info['config'] = $settings;
 		}
 	}
-	
+
 	if($channel) {
 		$info['channel'] = array();
 		foreach($channel as $k => $v) {
@@ -2775,23 +2737,20 @@ function build_sync_packet($uid = 0, $packet = null, $groups_changed = false) {
 		if($interval)
 			@time_sleep_until(microtime(true) + (float) $interval);
 	}
-
-
 }
 
 function process_channel_sync_delivery($sender,$arr,$deliveries) {
 
-// FIXME - this will sync red structures (channel, pconfig and abook). Eventually we need to make this application agnostic.
-
+	/** @FIXME this will sync red structures (channel, pconfig and abook). Eventually we need to make this application agnostic. */
 
 	$result = array();
-	
-	foreach($deliveries as $d) {
+
+	foreach ($deliveries as $d) {
 		$r = q("select * from channel where channel_hash = '%s' limit 1",
 			dbesc($d['hash'])
 		);
 
-		if(! $r) {
+		if (! $r) {
 			$result[] = array($d['hash'],'not found');
 			continue;
 		}
@@ -2801,7 +2760,6 @@ function process_channel_sync_delivery($sender,$arr,$deliveries) {
 		$max_friends = service_class_fetch($channel['channel_id'],'total_channels');
 		$max_feeds = account_service_class_fetch($channel['channel_account_id'],'total_feeds');
 
-
 		if($channel['channel_hash'] != $sender['hash']) {
 			logger('process_channel_sync_delivery: possible forgery. Sender ' . $sender['hash'] . ' is not ' . $channel['channel_hash']);
 			$result[] = array($d['hash'],'channel mismatch',$channel['channel_name'],'');
@@ -2832,8 +2790,6 @@ function process_channel_sync_delivery($sender,$arr,$deliveries) {
 			}
 		}
 
-
-
 		if(array_key_exists('abook',$arr) && is_array($arr['abook']) && count($arr['abook'])) {
 			$total_friends = 0;
 			$total_feeds = 0;
@@ -2922,7 +2878,7 @@ function process_channel_sync_delivery($sender,$arr,$deliveries) {
 					}
 					if($max_feeds !== false && ($clean['abook_flags'] & ABOOK_FLAG_FEED) && $total_feeds > $max_feeds) {
 						logger('process_channel_sync_delivery: total_feeds service class limit exceeded');
-						continue; 
+						continue;
 					}
 					q("insert into abook ( abook_xchan, abook_channel ) values ('%s', %d ) ",
 						dbesc($clean['abook_xchan']),
@@ -2931,7 +2887,7 @@ function process_channel_sync_delivery($sender,$arr,$deliveries) {
 					$total_friends ++;
 					if($clean['abook_flags'] & ABOOK_FLAG_FEED)
 						$total_feeds ++;
-				} 
+				}
 
 				if(count($clean)) {
 					foreach($clean as $k => $v) {
@@ -2975,7 +2931,7 @@ function process_channel_sync_delivery($sender,$arr,$deliveries) {
 						if(intval($cl['deleted']) && (! intval($y['deleted']))) {
 							q("delete from group_member where gid = %d",
 								intval($y['id'])
-							);  
+							);
 						}
 					}
 				}
@@ -3095,7 +3051,7 @@ function process_channel_sync_delivery($sender,$arr,$deliveries) {
 				if(! $x) {
 					q("insert into profile ( profile_guid, aid, uid ) values ('%s', %d, %d)",
 						dbesc($profile['profile_guid']),
-						intval($channel['channel_account_id']),		
+						intval($channel['channel_account_id']),
 						intval($channel['channel_id'])
 					);
 					$x = q("select * from profile where profile_guid = '%s' and uid = %d limit 1",
@@ -3109,9 +3065,12 @@ function process_channel_sync_delivery($sender,$arr,$deliveries) {
 				foreach($profile as $k => $v) {
 					if(in_array($k,$disallowed))
 						continue;
+
 					$clean[$k] = $v;
-					// TODO - check if these are allowed, otherwise we'll error
-					// We also need to import local photos if a custom photo is selected
+					/**
+					 * @TODO check if these are allowed, otherwise we'll error
+					 * We also need to import local photos if a custom photo is selected
+					 */
 				}
 				if(count($clean)) {
 					foreach($clean as $k => $v) {
@@ -3121,49 +3080,58 @@ function process_channel_sync_delivery($sender,$arr,$deliveries) {
 				}
 			}
 		}
-		
-		$result[] = array($d['hash'],'channel sync updated',$channel['channel_name'],'');
-
 
+		$result[] = array($d['hash'],'channel sync updated',$channel['channel_name'],'');
 	}
+
 	return $result;
 }
 
 // We probably should make rpost discoverable.
- 
+
 function get_rpost_path($observer) {
 	if(! $observer)
 		return '';
+
 	$parsed = parse_url($observer['xchan_url']);
-	return $parsed['scheme'] . '://' . $parsed['host'] . (($parsed['port']) ? ':' . $parsed['port'] : '') . '/rpost?f=';
 
+	return $parsed['scheme'] . '://' . $parsed['host'] . (($parsed['port']) ? ':' . $parsed['port'] : '') . '/rpost?f=';
 }
 
+
+/**
+ * @brief
+ *
+ * @param array $x
+ * @return boolean|string return false or a hash
+ */
 function import_author_zot($x) {
-	$hash = make_xchan_hash($x['guid'],$x['guid_sig']);
+	$hash = make_xchan_hash($x['guid'], $x['guid_sig']);
 	$r = q("select hubloc_url from hubloc where hubloc_guid = '%s' and hubloc_guid_sig = '%s' and (hubloc_flags & %d)>0 limit 1",
 		dbesc($x['guid']),
 		dbesc($x['guid_sig']),
 		intval(HUBLOC_FLAGS_PRIMARY)
 	);
 
-	if($r) {
+	if ($r) {
 		logger('import_author_zot: in cache', LOGGER_DEBUG);
 		return $hash;
 	}
 
 	logger('import_author_zot: entry not in cache - probing: ' . print_r($x,true), LOGGER_DEBUG);
-	
-	$them = array('hubloc_url' => $x['url'],'xchan_guid' => $x['guid'], 'xchan_guid_sig' => $x['guid_sig']);
-	if(zot_refresh($them))
+
+	$them = array('hubloc_url' => $x['url'], 'xchan_guid' => $x['guid'], 'xchan_guid_sig' => $x['guid_sig']);
+	if (zot_refresh($them))
 		return $hash;
+
 	return false;
 }
 
 
 /**
- * @function zot_process_message_request($data)
- *    If a site receives a comment to a post but finds they have no parent to attach it with, they
+ * @brief Process a message request.
+ *
+ * If a site receives a comment to a post but finds they have no parent to attach it with, they
  * may send a 'request' packet containing the message_id of the missing parent. This is the handler
  * for that packet. We will create a message_list array of the entire conversation starting with
  * the missing parent and invoke delivery to the sender of the packet.
@@ -3173,20 +3141,21 @@ function import_author_zot($x) {
  * processed/delivered in order.  
  *  
  * Called from mod/post.php
- */  
-
-
+ *
+ * @param array $data
+ * @return array
+ */
 function zot_process_message_request($data) {
 	$ret = array('success' => false);
 
-	if(! $data['message_id']) {
+	if (! $data['message_id']) {
 		$ret['message'] = 'no message_id';
 		logger('no message_id');
 		return $ret;
 	}
 
 	$sender = $data['sender'];
-	$sender_hash = make_xchan_hash($sender['guid'],$sender['guid_sig']);
+	$sender_hash = make_xchan_hash($sender['guid'], $sender['guid_sig']);
 
 	/*
 	 * Find the local channel in charge of this post (the first and only recipient of the request packet)
@@ -3197,7 +3166,7 @@ function zot_process_message_request($data) {
 	$c = q("select * from channel left join xchan on channel_hash = xchan_hash where channel_hash = '%s' limit 1",
 		dbesc($recip_hash)
 	);
-	if(! $c) {
+	if (! $c) {
 		logger('recipient channel not found.');
 		$ret['message'] .= 'recipient not found.' . EOL;
 		return $ret;
@@ -3209,7 +3178,7 @@ function zot_process_message_request($data) {
 
 	$messages = zot_feed($c[0]['channel_id'],$sender_hash,array('message_id' => $data['message_id']));
 
-	if($messages) {
+	if ($messages) {
 		$env_recips = null;
 
 		$r = q("select hubloc_guid, hubloc_url, hubloc_sitekey, hubloc_network, hubloc_flags, hubloc_callback, hubloc_host 
@@ -3219,20 +3188,18 @@ function zot_process_message_request($data) {
 			intval(HUBLOC_FLAGS_DELETED),
 			intval(HUBLOC_OFFLINE)
 		);
-		if(! $r) {
+		if (! $r) {
 			logger('no hubs');
 			return $ret;
 		}
 		$hubs = $r;
-		$hublist = array();
-		$keys = array();
 
-		$private = ((array_key_exists('flags',$messages[0]) && in_array('private',$messages[0]['flags'])) ? true : false);
+		$private = ((array_key_exists('flags', $messages[0]) && in_array('private',$messages[0]['flags'])) ? true : false);
 		if($private)
-			$env_recips = array('guid' => $sender['guid'],'guid_sig' => $sender['guid_sig'],'hash' => $sender_hash);
+			$env_recips = array('guid' => $sender['guid'], 'guid_sig' => $sender['guid_sig'], 'hash' => $sender_hash);
 
 		$data_packet = json_encode(array('message_list' => $messages));
-		
+
 		foreach($hubs as $hub) {
 			$hash = random_string();
 
@@ -3260,10 +3227,10 @@ function zot_process_message_request($data) {
 			 * invoke delivery to send out the notify packet
 			 */
 
-			proc_run('php','include/deliver.php',$hash);
+			proc_run('php', 'include/deliver.php', $hash);
 		}
-
 	}
 	$ret['success'] = true;
+
 	return $ret;
 }
diff --git a/mod/admin.php b/mod/admin.php
index 7182bb9e5..fd2ba510b 100644
--- a/mod/admin.php
+++ b/mod/admin.php
@@ -73,7 +73,7 @@ function admin_post(&$a){
 }
 
 /**
- * @param App $$a
+ * @param App &$a
  * @return string
  */
 function admin_content(&$a) {
@@ -84,7 +84,7 @@ function admin_content(&$a) {
 		return login(false);
 	}
 
-	/**
+	/*
 	 * Side bar links
 	 */
 
@@ -125,7 +125,7 @@ function admin_content(&$a) {
 	));
 
 
-	/**
+	/*
 	 * Page content
 	 */
 	$o = '';
@@ -183,7 +183,7 @@ function admin_content(&$a) {
 /**
  * @brief Returns content for Admin Summary Page.
  *
- * @param App $$a
+ * @param App &$a
  * @return string HTML from parsed admin_summary.tpl
  */
 function admin_page_summary(&$a) {
@@ -252,8 +252,9 @@ function admin_page_summary(&$a) {
 
 
 /**
- * Admin Site Page
- *  @param App $a
+ * @brief POST handler for Admin Site Page.
+ *
+ * @param App &$a
  */
 function admin_page_site_post(&$a){
 	if (!x($_POST, 'page_site')){
@@ -277,15 +278,15 @@ function admin_page_site_post(&$a){
 
 	$register_text		=	((x($_POST,'register_text'))	? notags(trim($_POST['register_text']))		: '');
 
-	$allowed_sites        =	((x($_POST,'allowed_sites'))	? notags(trim($_POST['allowed_sites']))		: '');
-	$allowed_email        =	((x($_POST,'allowed_email'))	? notags(trim($_POST['allowed_email']))		: '');
-	$not_allowed_email    =	((x($_POST,'not_allowed_email'))	? notags(trim($_POST['not_allowed_email']))		: '');
-	$block_public		  =	((x($_POST,'block_public'))		? True	: False);
-	$force_publish		  =	((x($_POST,'publish_all'))		? True	: False);
-	$disable_discover_tab =	((x($_POST,'disable_discover_tab'))		? True	:	False);
-	$no_login_on_homepage =	((x($_POST,'no_login_on_homepage'))		? True	:	False);
-	$global_directory	  = ((x($_POST,'directory_submit_url'))	? notags(trim($_POST['directory_submit_url']))	: '');
-	$no_community_page	  = !((x($_POST,'no_community_page'))	? True	:	False);
+	$allowed_sites        = ((x($_POST,'allowed_sites'))	? notags(trim($_POST['allowed_sites']))		: '');
+	$allowed_email        = ((x($_POST,'allowed_email'))	? notags(trim($_POST['allowed_email']))		: '');
+	$not_allowed_email    = ((x($_POST,'not_allowed_email'))	? notags(trim($_POST['not_allowed_email']))		: '');
+	$block_public         = ((x($_POST,'block_public'))		? True	: False);
+	$force_publish        = ((x($_POST,'publish_all'))		? True	: False);
+	$disable_discover_tab = ((x($_POST,'disable_discover_tab'))		? True	:	False);
+	$no_login_on_homepage = ((x($_POST,'no_login_on_homepage'))		? True	:	False);
+	$global_directory     = ((x($_POST,'directory_submit_url'))	? notags(trim($_POST['directory_submit_url']))	: '');
+	$no_community_page    = !((x($_POST,'no_community_page'))	? True	:	False);
 	$default_expire_days  = ((array_key_exists('default_expire_days',$_POST)) ? intval($_POST['default_expire_days']) : 0);
 
 	$verifyssl         = ((x($_POST,'verifyssl'))        ? True : False);
@@ -307,7 +308,7 @@ function admin_page_site_post(&$a){
 	set_config('system', 'sitename', $sitename);
 	set_config('system', 'no_login_on_homepage', $no_login_on_homepage);
 	set_config('system', 'verify_email', $verify_email);
-	set_config('system','default_expire_days', $default_expire_days);
+	set_config('system', 'default_expire_days', $default_expire_days);
 
 	if ($banner == '') {
 		del_config('system', 'banner');
@@ -360,6 +361,8 @@ function admin_page_site_post(&$a){
 }
 
 /**
+ * @brief Admin page site.
+ *
  * @param  App $a
  * @return string
  */
@@ -480,8 +483,8 @@ function admin_page_site(&$a) {
 		'$default_expire_days' => array('default_expire_days', t('Expiration period in days for imported (matrix/network) content'), intval(get_config('system','default_expire_days')), t('0 for no expiration of imported content')),
 		'$form_security_token' => get_form_security_token("admin_site"),
 	));
-
 }
+
 function admin_page_hubloc_post(&$a){
 	check_form_security_token_redirectOnErr('/admin/hubloc', 'admin_hubloc');
 	require_once('include/zot.php');
@@ -617,7 +620,6 @@ function admin_page_queue($a) {
 		);
 	}
 
-
 	$r = q("select count(outq_posturl) as total, max(outq_priority) as priority, outq_posturl from outq 
 		where outq_delivered = 0 group by outq_posturl order by total desc");
 
@@ -626,7 +628,6 @@ function admin_page_queue($a) {
 		$r[$x]['connected'] = datetime_convert('UTC',date_default_timezone_get(),$r[$x]['connected'],'Y-m-d');
 	}
 
-
 	$o = replace_macros(get_markup_template('admin_queue.tpl'), array(
 		'$banner' => t('Queue Statistics'),
 		'$numentries' => t('Total Entries'),
@@ -763,13 +764,11 @@ function admin_page_users(&$a){
 	}
 
 
-//	WEe'll still need to link email addresses to admin/users/channels or some such, but this bit doesn't exist yet.
+//	We'll still need to link email addresses to admin/users/channels or some such, but this bit doesn't exist yet.
 //	That's where we need to be doing last post/channel flags/etc, not here.
 
-
 	$serviceclass = (($_REQUEST['class']) ? " and account_service_class = '" . dbesc($_REQUEST['class']) . "' " : '');
 
-
 	$order = " order by account_email asc ";
 	if($_REQUEST['order'] === 'expires')
 		$order = " order by account_expires desc ";
@@ -803,7 +802,6 @@ function admin_page_users(&$a){
 //	}
 //	$users = array_map("_setup_users", $users);
 
-
 	$t = get_markup_template('admin_users.tpl');
 	$o = replace_macros($t, array(
 		// strings //
@@ -841,9 +839,9 @@ function admin_page_users(&$a){
 
 
 /**
- * Channels admin page
+ * @brief Channels admin page.
  *
- * @param App $a
+ * @param App &$a
  */
 function admin_page_channels_post(&$a) {
 	$channels = ( x($_POST, 'channel') ? $_POST['channel'] : Array() );
@@ -872,7 +870,9 @@ function admin_page_channels_post(&$a) {
 }
 
 /**
- * @param App $a
+ * @brief
+ *
+ * @param App &$a
  * @return string
  */
 function admin_page_channels(&$a){
@@ -975,7 +975,7 @@ function admin_page_channels(&$a){
  */
 function admin_page_plugins(&$a){
 
-	/**
+	/*
 	 * Single plugin
 	 */
 	if ($a->argc == 3){
@@ -1055,7 +1055,7 @@ function admin_page_plugins(&$a){
 	}
 
 
-	/**
+	/*
 	 * List plugins
 	 */
 	$plugins = array();
@@ -1087,7 +1087,7 @@ function admin_page_plugins(&$a){
  * @param string $th
  * @param int $result
  */
-function toggle_theme(&$themes,$th,&$result) {
+function toggle_theme(&$themes, $th, &$result) {
 	for($x = 0; $x < count($themes); $x ++) {
 		if($themes[$x]['name'] === $th) {
 			if($themes[$x]['allowed']) {
@@ -1142,9 +1142,9 @@ function rebuild_theme_table($themes) {
 
 
 /**
- * Themes admin page
+ * @brief Themes admin page.
  *
- * @param App $a
+ * @param App &$a
  * @return string
  */
 function admin_page_themes(&$a){
@@ -1174,7 +1174,7 @@ function admin_page_themes(&$a){
 		return '';
 	}
 
-	/**
+	/*
 	 * Single theme
 	 */
 
@@ -1253,8 +1253,7 @@ function admin_page_themes(&$a){
 		));
 	}
 
-
-	/**
+	/*
 	 * List themes
 	 */
 
@@ -1281,9 +1280,9 @@ function admin_page_themes(&$a){
 
 
 /**
- * Logs admin page
+ * @brief POST handler for logs admin page.
  *
- * @param App $a
+ * @param App &$a
  */
 function admin_page_logs_post(&$a) {
 	if (x($_POST, 'page_logs')) {
@@ -1303,6 +1302,8 @@ function admin_page_logs_post(&$a) {
 }
 
 /**
+ * @brief Logs admin page.
+ *
  * @param App $a
  * @return string
  */
@@ -1435,5 +1436,4 @@ function admin_page_profs(&$a) {
 			'$submit' => t('Save')
 		));
 	}
-
 }
\ No newline at end of file
diff --git a/mod/id.php b/mod/id.php
index 05a2f3dc5..bd4c1fa89 100644
--- a/mod/id.php
+++ b/mod/id.php
@@ -1,45 +1,51 @@
 <?php
-
-	require 'library/openid/provider/provider.php';
-
-
-
-	$attrMap = array(
-        'namePerson/first'       => t('First Name'),
-        'namePerson/last'        => t('Last Name'),
-        'namePerson/friendly'    => t('Nickname'),
-		'namePerson'             => t('Full Name'),
-		'contact/internet/email' => t('Email'),
-		'contact/email'          => t('Email'),
-		'media/image/aspect11'   => t('Profile Photo'),
-		'media/image'            => t('Profile Photo'),
-		'media/image/default'    => t('Profile Photo'),
-		'media/image/16x16'      => t('Profile Photo 16px'),
-		'media/image/32x32'      => t('Profile Photo 32px'),
-		'media/image/48x48'      => t('Profile Photo 48px'),
-		'media/image/64x64'      => t('Profile Photo 64px'),
-		'media/image/80x80'      => t('Profile Photo 80px'),
-		'media/image/128x128'    => t('Profile Photo 128px'),
-		'timezone'               => t('Timezone'),
-		'contact/web/default'    => t('Homepage URL'),
-		'language/pref'          => t('Language'),
-		'birthDate/birthYear'    => t('Birth Year'),
-		'birthDate/birthMonth'   => t('Birth Month'),
-		'birthDate/birthday'     => t('Birth Day'),
-		'birthDate'              => t('Birthdate'),
-		'gender'                 => t('Gender'),
-	);
-
-
-
+/**
+ * @file mod/id.php
+ * @brief OpenID implementation
+ */
+
+require 'library/openid/provider/provider.php';
+
+
+$attrMap = array(
+	'namePerson/first'       => t('First Name'),
+	'namePerson/last'        => t('Last Name'),
+	'namePerson/friendly'    => t('Nickname'),
+	'namePerson'             => t('Full Name'),
+	'contact/internet/email' => t('Email'),
+	'contact/email'          => t('Email'),
+	'media/image/aspect11'   => t('Profile Photo'),
+	'media/image'            => t('Profile Photo'),
+	'media/image/default'    => t('Profile Photo'),
+	'media/image/16x16'      => t('Profile Photo 16px'),
+	'media/image/32x32'      => t('Profile Photo 32px'),
+	'media/image/48x48'      => t('Profile Photo 48px'),
+	'media/image/64x64'      => t('Profile Photo 64px'),
+	'media/image/80x80'      => t('Profile Photo 80px'),
+	'media/image/128x128'    => t('Profile Photo 128px'),
+	'timezone'               => t('Timezone'),
+	'contact/web/default'    => t('Homepage URL'),
+	'language/pref'          => t('Language'),
+	'birthDate/birthYear'    => t('Birth Year'),
+	'birthDate/birthMonth'   => t('Birth Month'),
+	'birthDate/birthday'     => t('Birth Day'),
+	'birthDate'              => t('Birthdate'),
+	'gender'                 => t('Gender'),
+);
+
+
+/**
+ * @brief Entrypoint for the OpenID implementation.
+ *
+ * @param App &$a
+ */
 function id_init(&$a) {
 
-	logger('id: ' . print_r($_REQUEST,true));
-
+	logger('id: ' . print_r($_REQUEST, true));
 
-	if(argc() > 1)
+	if(argc() > 1) {
 		$which = argv(1);
-	else {
+	} else {
 		$a->error = 404;
 		return;
 	}
@@ -48,41 +54,45 @@ function id_init(&$a) {
 	$channel = $a->get_channel();
 	profile_load($a,$which,$profile);
 
-
-
 	$op = new MysqlProvider;
 	$op->server();
-
 }
 
-
-function getUserData($handle=null) {
-	if(! local_channel()) {
+/**
+ * @brief Returns user data needed for OpenID.
+ *
+ * If no $handle is provided we will use local_channel() by default.
+ *
+ * @param string $handle (default null)
+ * @return boolean|array
+ */
+function getUserData($handle = null) {
+	if (! local_channel()) {
 		notice( t('Permission denied.') . EOL);
 		get_app()->page['content'] =  login();
+
 		return false;
 	}
 
 //	logger('handle: ' . $handle);
 
-	if($handle) {
+	if ($handle) {
 		$r = q("select * from channel left join xchan on channel_hash = xchan_hash where channel_address = '%s' limit 1",
 			dbesc($handle)
 		);
-	}
-	else {
+	} else {
 		$r = q("select * from channel left join xchan on channel_hash = xchan_hash where channel_id = %d",
 			intval(local_channel())
 		);
 	}
 
-	if(! r)
+	if (! r)
 		return false;
 
 	$x = q("select * from account where account_id = %d limit 1", 
 		intval($r[0]['channel_account_id'])
 	);
-	if($x)
+	if ($x)
 		$r[0]['email'] = $x[0]['account_email'];
 
 	$p = q("select * from profile where is_default = 1 and uid = %d limit 1",
@@ -90,11 +100,11 @@ function getUserData($handle=null) {
 	);
 
 	$gender = '';
-	if($p[0]['gender'] == t('Male'))
+	if ($p[0]['gender'] == t('Male'))
 		$gender = 'M';
-	if($p[0]['gender'] == t('Female'))
+	if ($p[0]['gender'] == t('Female'))
 		$gender = 'F';
-		
+
 	$r[0]['firstName'] = ((strpos($r[0]['channel_name'],' ')) ? substr($r[0]['channel_name'],0,strpos($r[0]['channel_name'],' ')) : $r[0]['channel_name']);
 	$r[0]['lastName'] = ((strpos($r[0]['channel_name'],' ')) ? substr($r[0]['channel_name'],strpos($r[0]['channel_name'],' ')+1) : '');
 	$r[0]['namePerson'] = $r[0]['channel_name'];
@@ -113,7 +123,7 @@ function getUserData($handle=null) {
 	$r[0]['birthday'] = ((intval(substr($p[0]['dob'],8,2))) ? intval(substr($p[0]['dob'],8,2)) : '');
 	$r[0]['birthdate'] = (($r[0]['birthyear'] && $r[0]['birthmonth'] && $r[0]['birthday']) ? $p[0]['dob'] : '');
 	$r[0]['gender'] = $gender;
-	
+
 	return $r[0];
 
 /*
@@ -144,20 +154,20 @@ function getUserData($handle=null) {
 }
 
 
-
-
-class MysqlProvider extends LightOpenIDProvider
-{
-
+/**
+ * @brief MySQL provider for OpenID implementation.
+ *
+ */
+class MysqlProvider extends LightOpenIDProvider {
 
 	// See http://openid.net/specs/openid-attribute-properties-list-1_0-01.html
 	// This list contains a few variations of these attributes to maintain 
 	// compatibility with legacy clients
 
-    private $attrFieldMap = array(
-        'namePerson/first'       => 'firstName',
-        'namePerson/last'        => 'lastName',
-        'namePerson/friendly'    => 'channel_address',
+	private $attrFieldMap = array(
+		'namePerson/first'       => 'firstName',
+		'namePerson/last'        => 'lastName',
+		'namePerson/friendly'    => 'channel_address',
 		'namePerson'             => 'namePerson',
 		'contact/internet/email' => 'email',
 		'contact/email'          => 'email',
@@ -178,11 +188,9 @@ class MysqlProvider extends LightOpenIDProvider
 		'birthDate/birthday'     => 'birthday',
 		'birthDate'              => 'birthdate',
 		'gender'                 => 'gender',
-        );
-  
-  
-    function setup($identity, $realm, $assoc_handle, $attributes)
-    {
+	);
+
+	function setup($identity, $realm, $assoc_handle, $attributes) {
 		global $attrMap;
 
 //		logger('identity: ' . $identity);
@@ -190,10 +198,10 @@ class MysqlProvider extends LightOpenIDProvider
 //		logger('assoc_handle: ' . $assoc_handle);
 //		logger('attributes: ' . print_r($attributes,true));
 
-        $data = getUserData($assoc_handle);
+		$data = getUserData($assoc_handle);
 
 
-// FIXME this needs to be a template with localised strings
+/** @FIXME this needs to be a template with localised strings */
 
         $o .= '<form action="" method="post">'
            . '<input type="hidden" name="openid.assoc_handle" value="' . $assoc_handle . '">'
@@ -203,7 +211,7 @@ class MysqlProvider extends LightOpenIDProvider
         if($attributes['required'] || $attributes['optional']) {
             $o .= " It also requests following information (required fields marked with *):"
                . '<ul>';
-            
+
             foreach($attributes['required'] as $attr) {
                 if(isset($this->attrMap[$attr])) {
                     $o .= '<li>'
@@ -211,7 +219,7 @@ class MysqlProvider extends LightOpenIDProvider
                        . $this->attrMap[$attr] . ' <span class="required">*</span></li>';
                 }
             }
-            
+
             foreach($attributes['optional'] as $attr) {
                 if(isset($this->attrMap[$attr])) {
                     $o .= '<li>'
@@ -228,27 +236,23 @@ class MysqlProvider extends LightOpenIDProvider
            . '</form>';
 
 		get_app()->page['content'] .= $o;
+	}
 
-    }
-    
-    function checkid($realm, &$attributes)
-    {
+	function checkid($realm, &$attributes) {
 
 		logger('checkid: ' . $realm);
-
 		logger('checkid attrs: ' . print_r($attributes,true));
 
+		if(isset($_POST['cancel'])) {
+			$this->cancel();
+		}
 
-        if(isset($_POST['cancel'])) {
-            $this->cancel();
-        }
-        
-        $data = getUserData();
-        if(! $data) {
-            return false;
-        }
+		$data = getUserData();
+		if(! $data) {
+			return false;
+		}
 
-		$q = get_pconfig(local_channel(),'openid',$realm);
+		$q = get_pconfig(local_channel(), 'openid', $realm);
 
 		$attrs = array();
 		if($q) {
@@ -265,57 +269,42 @@ class MysqlProvider extends LightOpenIDProvider
                 $attributes[$attr] = $data[$this->attrFieldMap[$attr]];
             }
         }
-        
-        if(isset($_POST['always'])) {
+
+		if(isset($_POST['always'])) {
 			set_pconfig(local_channel(),'openid',$realm,array_keys($attributes));
-        }
-  
-		return z_root() . '/id/' . $data['channel_address'];      
-    }
-    
-    function assoc_handle()
-    {
-	logger('assoc_handle');
+		}
+
+		return z_root() . '/id/' . $data['channel_address'];
+	}
+
+	function assoc_handle() {
+		logger('assoc_handle');
 		$channel = get_app()->get_channel();
+
 		return z_root() . '/channel/' . $channel['channel_address']; 
+	}
 
-    }
-    
-    function setAssoc($handle, $data)
-    {
+	function setAssoc($handle, $data) {
 		logger('setAssoc');
 		$channel = channelx_by_nick(basename($handle));
 		if($channel)
 			set_pconfig($channel['channel_id'],'openid','associate',$data);
-    }
-    
-    function getAssoc($handle)
-    {
+	}
+
+	function getAssoc($handle) {
 		logger('getAssoc: ' . $handle);
 
 		$channel = channelx_by_nick(basename($handle));
 		if($channel)
-			return get_pconfig($channel['channel_id'],'openid','associate');
+			return get_pconfig($channel['channel_id'], 'openid', 'associate');
+
 		return false;
-    }
-    
-    function delAssoc($handle)
-    {
+	}
+
+	function delAssoc($handle) {
 		logger('delAssoc');
 		$channel = channelx_by_nick(basename($handle));
 		if($channel)
-			return del_pconfig($channel['channel_id'],'openid','associate');
-    }
-    
+			return del_pconfig($channel['channel_id'], 'openid', 'associate');
+	}
 }
-
-
-
-
-
-
-
-
-
-
-
diff --git a/mod/match.php b/mod/match.php
index 5a01ba645..fd739ba2c 100644
--- a/mod/match.php
+++ b/mod/match.php
@@ -1,14 +1,20 @@
 <?php
 
-// FIXME - this has never been properly ported from Friendica
-// It takes keywords from your profile and queries the directory server for 
-// matching keywords from other profiles.
-
-
+/**
+ * @brief Controller for /match.
+ *
+ * It takes keywords from your profile and queries the directory server for
+ * matching keywords from other profiles.
+ *
+ * @FIXME this has never been properly ported from Friendica.
+ *
+ * @param App &$a
+ * @return void|string
+ */
 function match_content(&$a) {
 
 	$o = '';
-	if(! local_channel())
+	if (! local_channel())
 		return;
 
 	$_SESSION['return_url'] = $a->get_baseurl() . '/' . $a->cmd;
@@ -18,22 +24,22 @@ function match_content(&$a) {
 	$r = q("SELECT `keywords` FROM `profile` WHERE `is_default` = 1 AND `uid` = %d LIMIT 1",
 		intval(local_channel())
 	);
-	if(! count($r))
-		return; 
-	if(! $r[0]['keywords']) {
-		notice( t('No keywords to match. Please add keywords to your default profile.') . EOL);
+	if (! count($r))
 		return;
 
+	if (! $r[0]['keywords']) {
+		notice( t('No keywords to match. Please add keywords to your default profile.') . EOL);
+		return;
 	}
 
 	$params = array();
 	$tags = trim($r[0]['keywords']);
-	
-	if($tags) {
+
+	if ($tags) {
 		$params['s'] = $tags;
-		if($a->pager['page'] != 1)
+		if ($a->pager['page'] != 1)
 			$params['p'] = $a->pager['page'];
-			
+
 //		if(strlen(get_config('system','directory_submit_url')))
 //			$x = post_url('http://dir.friendica.com/msearch', $params);
 //		else
@@ -41,18 +47,14 @@ function match_content(&$a) {
 
 		$j = json_decode($x);
 
-		if($j->total) {
+		if ($j->total) {
 			$a->set_pager_total($j->total);
 			$a->set_pager_itemspage($j->items_page);
 		}
 
-		if(count($j->results)) {
-
-
-			
+		if (count($j->results)) {
 			$tpl = get_markup_template('match.tpl');
-			foreach($j->results as $jj) {
-				
+			foreach ($j->results as $jj) {
 				$connlnk = $a->get_baseurl() . '/follow/?url=' . $jj->url;
 				$o .= replace_macros($tpl,array(
 					'$url' => zid($jj->url),
@@ -64,14 +66,13 @@ function match_content(&$a) {
 					'$tags' => $jj->tags
 				));
 			}
-		}
-		else {
+		} else {
 			info( t('No matches') . EOL);
-		}		
-
+		}
 	}
 
 	$o .= cleardiv();
 	$o .= paginate($a);
+
 	return $o;
 }
diff --git a/mod/post.php b/mod/post.php
index 31b688221..37002b249 100644
--- a/mod/post.php
+++ b/mod/post.php
@@ -1,20 +1,21 @@
-<?php /** @file */
+<?php
 
 /**
- * Zot endpoint
+ * @file mod/post.php
+ *
+ * @brief Zot endpoint.
+ *
  */
 
-
 require_once('include/zot.php');
 
-
-function post_init(&$a) {
-
-	// Most access to this endpoint is via the post method.
-	// Here we will pick out the magic auth params which arrive
-	// as a get request, and the only communications to arrive this way.
-
 /**
+ * @brief HTTP POST entry point for Zot.
+ *
+ * Most access to this endpoint is via the post method.
+ * Here we will pick out the magic auth params which arrive as a get request,
+ * and the only communications to arrive this way.
+ *
  * Magic Auth
  * ==========
  *
@@ -24,67 +25,68 @@ function post_init(&$a) {
  * The endpoint is typically  https://$remotesite/post - or whatever was specified as the callback url in prior communications
  * (we will bootstrap an address and fetch a zot info packet if possible where no prior communications exist)
  *
- * Four GET parameters are supplied:
- *
- ** auth => the urlencoded webbie (channel@host.domain) of the channel requesting access
- ** dest => the desired destination URL (urlencoded)
- ** sec  => a random string which is also stored on $mysite for use during the verification phase. 
- ** version => the zot revision
- ** delegate => optional urlencoded webbie of a local channel to invoke delegation rights for
+ * Five GET parameters are supplied:
+ * * auth => the urlencoded webbie (channel@host.domain) of the channel requesting access
+ * * dest => the desired destination URL (urlencoded)
+ * * sec  => a random string which is also stored on $mysite for use during the verification phase. 
+ * * version => the zot revision
+ * * delegate => optional urlencoded webbie of a local channel to invoke delegation rights for
  *
  * When this packet is received, an "auth-check" zot message is sent to $mysite.
  * (e.g. if $_GET['auth'] is foobar@podunk.edu, a zot packet is sent to the podunk.edu zot endpoint, which is typically /post)
  * If no information has been recorded about the requesting identity a zot information packet will be retrieved before
  * continuing.
- * 
+ *
  * The sender of this packet is an arbitrary/random site channel. The recipients will be a single recipient corresponding
  * to the guid and guid_sig we have associated with the requesting auth identity
  *
- *
- *    {
- *      "type":"auth_check",
- *      "sender":{
- *        "guid":"kgVFf_...",
- *        "guid_sig":"PT9-TApz...",
- *        "url":"http:\/\/podunk.edu",
- *        "url_sig":"T8Bp7j..."
- *      },
- *      "recipients":{
- *        {
- *        "guid":"ZHSqb...",
- *        "guid_sig":"JsAAXi..."
- *        }
- *      }
- *      "callback":"\/post",
- *      "version":1,
- *      "secret":"1eaa661",
- *      "secret_sig":"eKV968b1..."
- *    }
- *
+ * \code{.json}
+ * {
+ *   "type":"auth_check",
+ *   "sender":{
+ *     "guid":"kgVFf_...",
+ *     "guid_sig":"PT9-TApz...",
+ *     "url":"http:\/\/podunk.edu",
+ *     "url_sig":"T8Bp7j..."
+ *   },
+ *   "recipients":{
+ *     {
+ *       "guid":"ZHSqb...",
+ *       "guid_sig":"JsAAXi..."
+ *     }
+ *   }
+ *   "callback":"\/post",
+ *   "version":1,
+ *   "secret":"1eaa661",
+ *   "secret_sig":"eKV968b1..."
+ * }
+ * \endcode
  *
  * auth_check messages MUST use encapsulated encryption. This message is sent to the origination site, which checks the 'secret' to see 
  * if it is the same as the 'sec' which it passed originally. It also checks the secret_sig which is the secret signed by the 
  * destination channel's private key and base64url encoded. If everything checks out, a json packet is returned:
  *
- *    { 
- *      "success":1, 
- *      "confirm":"q0Ysovd1u..."
- *      "service_class":(optional)
- *      "level":(optional)
- *    }
+ * \code{.json}
+ * {
+ *   "success":1,
+ *   "confirm":"q0Ysovd1u...",
+ *   "service_class":(optional)
+ *   "level":(optional)
+ * }
+ * \endcode
  *
  * 'confirm' in this case is the base64url encoded RSA signature of the concatenation of 'secret' with the
  * base64url encoded whirlpool hash of the requestor's guid and guid_sig; signed with the source channel private key. 
  * This prevents a man-in-the-middle from inserting a rogue success packet. Upon receipt and successful 
  * verification of this packet, the destination site will redirect to the original destination URL and indicate a successful remote login. 
  * Service_class can be used by cooperating sites to provide different access rights based on account rights and subscription plans. It is 
- * a string whose contents are not defined by protocol. Example: "basic" or "gold". 
- *
- *
+ * a string whose contents are not defined by protocol. Example: "basic" or "gold".
  *
+ * @param[in,out] App &$a
  */
-	
-	if(array_key_exists('auth',$_REQUEST)) {
+function post_init(&$a) {
+
+	if (array_key_exists('auth', $_REQUEST)) {
 
 		$ret = array('success' => false, 'message' => '');
 
@@ -95,7 +97,7 @@ function post_init(&$a) {
 		$version  = $_REQUEST['version'];
 		$delegate = $_REQUEST['delegate'];
 
-		$test    = ((x($_REQUEST,'test')) ? intval($_REQUEST['test']) : 0);
+		$test     = ((x($_REQUEST, 'test')) ? intval($_REQUEST['test']) : 0);
 
 		// They are authenticating ultimately to the site and not to a particular channel.
 		// Any channel will do, providing it's currently active. We just need to have an 
@@ -105,10 +107,10 @@ function post_init(&$a) {
 			intval(PAGE_REMOVED)
 		);
 
-		if(! $c) {
+		if (! $c) {
 			// nobody here
 			logger('mod_zot: auth: unable to find a response channel');
-			if($test) {
+			if ($test) {
 				$ret['message'] .= 'no local channels found.' . EOL;
 				json_return_and_die($ret);
 			}
@@ -121,12 +123,12 @@ function post_init(&$a) {
 			dbesc($address)
 		);
 
-		if(! $x) {
+		if (! $x) {
 			// finger them if they can't be found. 
-			$ret = zot_finger($address,null);
-			if($ret['success']) {
-				$j = json_decode($ret['body'],true);
-				if($j)
+			$ret = zot_finger($address, null);
+			if ($ret['success']) {
+				$j = json_decode($ret['body'], true);
+				if ($j)
 					import_xchan($j);
 				$x = q("select * from hubloc left join xchan on xchan_hash = hubloc_hash where hubloc_addr = '%s' order by hubloc_id desc limit 1",
 					dbesc($address)
@@ -166,61 +168,60 @@ function post_init(&$a) {
 
 		$j = array();
 
-		if(! $already_authed) {
+		if (! $already_authed) {
 
 			// Auth packets MUST use ultra top-secret hush-hush mode - e.g. the entire packet is encrypted using the site private key
 			// The actual channel sending the packet ($c[0]) is not important, but this provides a generic zot packet with a sender
 			// which can be verified
  
 			$p = zot_build_packet($c[0],$type = 'auth_check', array(array('guid' => $x[0]['hubloc_guid'],'guid_sig' => $x[0]['hubloc_guid_sig'])), $x[0]['hubloc_sitekey'], $sec);
-			if($test) {
+			if ($test) {
 				$ret['message'] .= 'auth check packet created using sitekey ' . $x[0]['hubloc_sitekey'] . EOL;
 				$ret['message'] .= 'packet contents: ' . $p . EOL;
 			}
 
 			$result = zot_zot($x[0]['hubloc_callback'],$p);
 
-
-			if(! $result['success']) {
+			if (! $result['success']) {
 				logger('mod_zot: auth_check callback failed.');
-				if($test) {
+				if ($test) {
 					$ret['message'] .= 'auth check request to your site returned .' . print_r($result, true) . EOL;
 					json_return_and_die($ret);
 				}
 
 				goaway($desturl);
 			}
-			$j = json_decode($result['body'],true);
-			if(! $j) {
+			$j = json_decode($result['body'], true);
+			if (! $j) {
 				logger('mod_zot: auth_check json data malformed.');
 				if($test) {
 					$ret['message'] .= 'json malformed: ' . $result['body'] . EOL;
 					json_return_and_die($ret);
 				}
-			}				
+			}
 		}
 
-		if($test) {
+		if ($test) {
 			$ret['message'] .= 'auth check request returned .' . print_r($j, true) . EOL;
-		}	
+		}
 
-		if($already_authed || $j['success']) {
-			if($j['success']) {
+		if ($already_authed || $j['success']) {
+			if ($j['success']) {
 				// legit response, but we do need to check that this wasn't answered by a man-in-middle
-				if(! rsa_verify($sec . $x[0]['xchan_hash'],base64url_decode($j['confirm']),$x[0]['xchan_pubkey'])) {
+				if (! rsa_verify($sec . $x[0]['xchan_hash'],base64url_decode($j['confirm']),$x[0]['xchan_pubkey'])) {
 					logger('mod_zot: auth: final confirmation failed.');
-					if($test) {
+					if ($test) {
 						$ret['message'] .= 'final confirmation failed. ' . $sec . print_r($j,true) . print_r($x[0],true);
 						json_return_and_die($ret);
 					}
-						
+
 					goaway($desturl);
 				}
-				if(array_key_exists('service_class',$j))
+				if (array_key_exists('service_class',$j))
 					$remote_service_class = $j['service_class'];
-				if(array_key_exists('level',$j))
+				if (array_key_exists('level',$j))
 					$remote_level = $j['level'];
-				if(array_key_exists('DNT',$j))
+				if (array_key_exists('DNT',$j))
 					$DNT = $j['DNT'];
 			}
 			// everything is good... maybe
@@ -229,35 +230,33 @@ function post_init(&$a) {
 				// tell them to logout if they're logged in locally as anything but the target remote account
 				// in which case just shut up because they don't need to be doing this at all.
 
-				if($a->channel['channel_hash'] != $x[0]['xchan_hash']) {
+				if ($a->channel['channel_hash'] != $x[0]['xchan_hash']) {
 					logger('mod_zot: auth: already authenticated locally as somebody else.');
 					notice( t('Remote authentication blocked. You are logged into this site locally. Please logout and retry.') . EOL);
-					if($test) {
+					if ($test) {
 						$ret['message'] .= 'already logged in locally with a conflicting identity.' . EOL;
 						json_return_and_die($ret);
 					}
-
 				}
 				goaway($desturl);
 			}
-			
 
 			// log them in
 
-			if($test) {
+			if ($test) {
 				$ret['success'] = true;
 				$ret['message'] .= 'Authentication Success!' . EOL;
 				json_return_and_die($ret);
 			}
 
 			$delegation_success = false;
-			if($delegate) {
+			if ($delegate) {
 				$r = q("select * from channel left join xchan on channel_hash = xchan_hash where xchan_addr = '%s' limit 1",
 					dbesc($delegate)
 				);
-				if($r && intval($r[0]['channel_id'])) {
+				if ($r && intval($r[0]['channel_id'])) {
 					$allowed = perm_is_allowed($r[0]['channel_id'],$x[0]['xchan_hash'],'delegate');
-					if($allowed) {
+					if ($allowed) {
 						$_SESSION['delegate_channel'] = $r[0]['channel_id'];
 						$_SESSION['delegate'] = $x[0]['xchan_hash'];
 						$_SESSION['account_id'] = intval($r[0]['channel_account_id']);
@@ -267,12 +266,9 @@ function post_init(&$a) {
 					}
 				}
 			}
-			
-
-
 
 			$_SESSION['authenticated'] = 1;
-			if(! $delegation_success) {
+			if (! $delegation_success) {
 				$_SESSION['visitor_id'] = $x[0]['xchan_hash'];
 				$_SESSION['my_url'] = $x[0]['xchan_url'];
 				$_SESSION['my_address'] = $address;
@@ -289,18 +285,15 @@ function post_init(&$a) {
 			$a->set_groups(init_groups_visitor($_SESSION['visitor_id']));
 			info(sprintf( t('Welcome %s. Remote authentication successful.'),$x[0]['xchan_name']));
 			logger('mod_zot: auth success from ' . $x[0]['xchan_addr']); 
-			 q("update hubloc set hubloc_status =  (hubloc_status | %d ) where hubloc_id = %d ",
-                                intval(HUBLOC_WORKS),
-                                intval($x[0]['hubloc_id'])
-                        );
-
-
+			q("update hubloc set hubloc_status =  (hubloc_status | %d ) where hubloc_id = %d ",
+					intval(HUBLOC_WORKS),
+					intval($x[0]['hubloc_id'])
+			);
 		} else {
-			if($test) {
+			if ($test) {
 				$ret['message'] .= 'auth failure. ' . print_r($_REQUEST,true) . print_r($j,true) . EOL;
 				json_return_and_die($ret);
 			}
-
 			logger('mod_zot: magic-auth failure - not authenticated: ' . $x[0]['xchan_addr']);
 			q("update hubloc set hubloc_status =  (hubloc_status | %d ) where hubloc_id = %d ",
 				intval(HUBLOC_RECEIVE_ERROR),
@@ -308,11 +301,14 @@ function post_init(&$a) {
 			);
 		}
 
-		// FIXME - we really want to save the return_url in the session before we visit rmagic.
-		// This does however prevent a recursion if you visit rmagic directly, as it would otherwise send you back here again. 
-		// But z_root() probably isn't where you really want to go. 
+		/**
+		 * @FIXME we really want to save the return_url in the session before we
+		 * visit rmagic. This does however prevent a recursion if you visit
+		 * rmagic directly, as it would otherwise send you back here again.
+		 * But z_root() probably isn't where you really want to go.
+		 */
 
-		if($test) {
+		if ($test) {
 			$ret['message'] .= 'auth failure fallthrough ' . print_r($_REQUEST,true) . print_r($j,true) . EOL;
 			json_return_and_die($ret);
 		}
@@ -322,41 +318,40 @@ function post_init(&$a) {
 
 		goaway($desturl);
 	}
-	return;
 }
 
 
 /**
- * @function post_post(&$a)
- *     zot communications and messaging
+ * @brief zot communications and messaging.
  *
- *     Sender HTTP posts to this endpoint ($site/post typically) with 'data' parameter set to json zot message packet.
- *     This packet is optionally encrypted, which we will discover if the json has an 'iv' element.
- *     $contents => array( 'alg' => 'aes256cbc', 'iv' => initialisation vector, 'key' => decryption key, 'data' => encrypted data);
- *     $contents->iv and $contents->key are random strings encrypted with this site's RSA public key and then base64url encoded.
- *     Currently only 'aes256cbc' is used, but this is extensible should that algorithm prove inadequate.
+ * Sender HTTP posts to this endpoint ($site/post typically) with 'data' parameter set to json zot message packet.
+ * This packet is optionally encrypted, which we will discover if the json has an 'iv' element.
+ * $contents => array( 'alg' => 'aes256cbc', 'iv' => initialisation vector, 'key' => decryption key, 'data' => encrypted data);
+ * $contents->iv and $contents->key are random strings encrypted with this site's RSA public key and then base64url encoded.
+ * Currently only 'aes256cbc' is used, but this is extensible should that algorithm prove inadequate.
  *
- *     Once decrypted, one will find the normal json_encoded zot message packet. 
+ * Once decrypted, one will find the normal json_encoded zot message packet.
  * 
  * Defined packet types are: notify, purge, refresh, force_refresh, auth_check, ping, and pickup 
  *
  * Standard packet: (used by notify, purge, refresh, force_refresh, and auth_check)
- *
+ * \code{.json}
  * {
- *  "type": "notify",
- *  "sender":{
- *       "guid":"kgVFf_1...",
- *       "guid_sig":"PT9-TApzp...",
- *       "url":"http:\/\/podunk.edu",
- *       "url_sig":"T8Bp7j5...",
- *    },
- *  "recipients": { optional recipient array },
- *  "callback":"\/post",
- *  "version":1,
- *  "secret":"1eaa...",
- *  "secret_sig": "df89025470fac8..."
+ *   "type": "notify",
+ *   "sender":{
+ *     "guid":"kgVFf_1...",
+ *     "guid_sig":"PT9-TApzp...",
+ *     "url":"http:\/\/podunk.edu",
+ *     "url_sig":"T8Bp7j5...",
+ *   },
+ *   "recipients": { optional recipient array },
+ *   "callback":"\/post",
+ *   "version":1,
+ *   "secret":"1eaa...",
+ *   "secret_sig": "df89025470fac8..."
  * }
- * 
+ * \endcode
+ *
  * Signature fields are all signed with the sender channel private key and base64url encoded.
  * Recipients are arrays of guid and guid_sig, which were previously signed with the recipients private 
  * key and base64url encoded and later obtained via channel discovery. Absence of recipients indicates
@@ -364,108 +359,116 @@ function post_init(&$a) {
  *
  * "pickup" packet:
  * The pickup packet is sent in response to a notify packet from another site
- * 
+ * \code{.json}
  * {
- *  "type":"pickup",
- *  "url":"http:\/\/example.com",
- *  "callback":"http:\/\/example.com\/post",
- *  "callback_sig":"teE1_fLI...",
- *  "secret":"1eaa...",
- *  "secret_sig":"O7nB4_..."
+ *   "type":"pickup",
+ *   "url":"http:\/\/example.com",
+ *   "callback":"http:\/\/example.com\/post",
+ *   "callback_sig":"teE1_fLI...",
+ *   "secret":"1eaa...",
+ *   "secret_sig":"O7nB4_..."
  * }
+ * \endcode
  *
- * In the pickup packet, the sig fields correspond to the respective data element signed with this site's system 
- * private key and then base64url encoded.
+ * In the pickup packet, the sig fields correspond to the respective data
+ * element signed with this site's system private key and then base64url encoded.
  * The "secret" is the same as the original secret from the notify packet. 
  *
- * If verification is successful, a json structure is returned
- * containing a success indicator and an array of type 'pickup'.
- * Each pickup element contains the original notify request and a message field whose contents are 
- * dependent on the message type
+ * If verification is successful, a json structure is returned containing a
+ * success indicator and an array of type 'pickup'.
+ * Each pickup element contains the original notify request and a message field
+ * whose contents are dependent on the message type.
  *
- * This JSON array is AES encapsulated using the site public key of the site that sent the initial zot pickup packet.
+ * This JSON array is AES encapsulated using the site public key of the site
+ * that sent the initial zot pickup packet.
  * Using the above example, this would be example.com.
- * 
- * 
+ *
+ * \code{.json}
  * {
- * "success":1,
- * "pickup":{
- *   "notify":{
- *     "type":"notify",
- *     "sender":{
- *       "guid":"kgVFf_...",
- *       "guid_sig":"PT9-TApz...",
- *       "url":"http:\/\/z.podunk.edu",
- *       "url_sig":"T8Bp7j5D..."
- *     },
- *     "callback":"\/post",
- *     "version":1,
- *     "secret":"1eaa661..."
- *   },
- *   "message":{
- *     "type":"activity",
- *     "message_id":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
- *     "message_top":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
- *     "message_parent":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
- *     "created":"2012-11-20 04:04:16",
- *     "edited":"2012-11-20 04:04:16",
- *     "title":"",
- *     "body":"Hi Nickordo",
- *     "app":"",
- *     "verb":"post",
- *     "object_type":"",
- *     "target_type":"",
- *     "permalink":"",
- *     "location":"",
- *     "longlat":"",
- *     "owner":{
- *       "name":"Indigo",
- *       "address":"indigo@podunk.edu",
- *       "url":"http:\/\/podunk.edu",
- *       "photo":{
- *         "mimetype":"image\/jpeg",
- *         "src":"http:\/\/podunk.edu\/photo\/profile\/m\/5"
+ *   "success":1,
+ *   "pickup":{
+ *     "notify":{
+ *       "type":"notify",
+ *       "sender":{
+ *         "guid":"kgVFf_...",
+ *         "guid_sig":"PT9-TApz...",
+ *         "url":"http:\/\/z.podunk.edu",
+ *         "url_sig":"T8Bp7j5D..."
  *       },
- *       "guid":"kgVFf_...",
- *       "guid_sig":"PT9-TAp...",
+ *       "callback":"\/post",
+ *       "version":1,
+ *       "secret":"1eaa661..."
  *     },
- *     "author":{
- *       "name":"Indigo",
- *       "address":"indigo@podunk.edu",
- *       "url":"http:\/\/podunk.edu",
- *       "photo":{
- *         "mimetype":"image\/jpeg",
- *         "src":"http:\/\/podunk.edu\/photo\/profile\/m\/5"
+ *     "message":{
+ *       "type":"activity",
+ *       "message_id":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
+ *       "message_top":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
+ *       "message_parent":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu",
+ *       "created":"2012-11-20 04:04:16",
+ *       "edited":"2012-11-20 04:04:16",
+ *       "title":"",
+ *       "body":"Hi Nickordo",
+ *       "app":"",
+ *       "verb":"post",
+ *       "object_type":"",
+ *       "target_type":"",
+ *       "permalink":"",
+ *       "location":"",
+ *       "longlat":"",
+ *       "owner":{
+ *         "name":"Indigo",
+ *         "address":"indigo@podunk.edu",
+ *         "url":"http:\/\/podunk.edu",
+ *         "photo":{
+ *           "mimetype":"image\/jpeg",
+ *           "src":"http:\/\/podunk.edu\/photo\/profile\/m\/5"
+ *         },
+ *         "guid":"kgVFf_...",
+ *         "guid_sig":"PT9-TAp...",
  *       },
- *       "guid":"kgVFf_...",
- *       "guid_sig":"PT9-TAp..."
+ *       "author":{
+ *         "name":"Indigo",
+ *         "address":"indigo@podunk.edu",
+ *         "url":"http:\/\/podunk.edu",
+ *         "photo":{
+ *           "mimetype":"image\/jpeg",
+ *           "src":"http:\/\/podunk.edu\/photo\/profile\/m\/5"
+ *         },
+ *         "guid":"kgVFf_...",
+ *         "guid_sig":"PT9-TAp..."
+ *       }
  *     }
  *   }
  * }
- *} 
+ * \endcode
  *
- * Currently defined message types are 'activity', 'mail', 'profile', 'location' and 'channel_sync', 
- * which each have different content schemas.
+ * Currently defined message types are 'activity', 'mail', 'profile', 'location'
+ * and 'channel_sync', which each have different content schemas.
  *
  * Ping packet:
- * A ping packet does not require any parameters except the type. It may or may not be encrypted.
- * 
+ * A ping packet does not require any parameters except the type. It may or may
+ * not be encrypted.
+ *
+ * \code{.json}
  * {
- *  "type": "ping"
+ *   "type": "ping"
  * }
- * 
+ * \endcode
+ *
  * On receipt of a ping packet a ping response will be returned:
  *
+ * \code{.json}
  * {
  *   "success" : 1,
  *   "site" {
- *       "url":"http:\/\/podunk.edu",
- *       "url_sig":"T8Bp7j5...",
- *       "sitekey": "-----BEGIN PUBLIC KEY-----
- *                  MIICIjANBgkqhkiG9w0BAQE..."
- *    }
+ *     "url": "http:\/\/podunk.edu",
+ *     "url_sig": "T8Bp7j5...",
+ *     "sitekey": "-----BEGIN PUBLIC KEY-----
+ *                 MIICIjANBgkqhkiG9w0BAQE..."
+ *   }
  * }
- * 
+ * \endcode
+ *
  * The ping packet can be used to verify that a site has not been re-installed, and to 
  * initiate corrective action if it has. The url_sig is signed with the site private key
  * and base64url encoded - and this should verify with the enclosed sitekey. Failure to
@@ -479,21 +482,19 @@ function post_init(&$a) {
  * If you have no records which match this url_sig and key - no corrective action should
  * be taken as this packet may have been returned by an imposter.  
  *
+ * @param[in,out] App &$a
  */
-
-	
 function post_post(&$a) {
 
-
 	$encrypted_packet = false;
 	$ret = array('success' => false);
 
 	$data = json_decode($_REQUEST['data'],true);
 
-
-	/**
-	 * Many message packets will arrive encrypted. The existence of an 'iv' element 
-	 * tells us we need to unencapsulate the AES-256-CBC content using the site private key
+	/*
+	 * Many message packets will arrive encrypted. The existence of an 'iv'
+	 * element tells us we need to unencapsulate the AES-256-CBC content using
+	 * the site private key.
 	 */
 
 	if($data && array_key_exists('iv',$data)) {
@@ -539,12 +540,11 @@ function post_post(&$a) {
 
 	if($msgtype === 'pickup') {
 
-		/**
+		/*
 		 * The 'pickup' message arrives with a tracking ID which is associated with a particular outq_hash
 		 * First verify that that the returned signatures verify, then check that we have an outbound queue item
 		 * with the correct hash.
 		 * If everything verifies, find any/all outbound messages in the queue for this hubloc and send them back
-		 *
 		 */
 
 		if((! $data['secret']) || (! $data['secret_sig'])) {
@@ -597,7 +597,7 @@ function post_post(&$a) {
 			json_return_and_die($ret);
 		}
 
-		/**
+		/*
 		 * If we made it to here, the signatures verify, but we still don't know if the tracking ID is valid.
 		 * It wouldn't be an error if the tracking ID isn't found, because we may have sent this particular
 		 * queue item with another pickup (after the tracking ID for the other pickup  was verified). 
@@ -613,7 +613,7 @@ function post_post(&$a) {
 			json_return_and_die($ret);
 		}
 
-		/**
+		/*
 		 * Everything is good if we made it here, so find all messages that are going to this location
 		 * and send them all.
 		 */
@@ -651,33 +651,31 @@ function post_post(&$a) {
 		$encrypted = crypto_encapsulate(json_encode($ret),$sitekey);
 		json_return_and_die($encrypted);
 
-		/** pickup: end */
+		/* pickup: end */
 	}
 
 
-
-
-	/**
+	/*
 	 * All other message types require us to verify the sender. This is a generic check, so we 
 	 * will do it once here and bail if anything goes wrong.
 	 */
 
-	if(array_key_exists('sender',$data)) {
+	if (array_key_exists('sender',$data)) {
 		$sender = $data['sender'];
-	}	
+	}
 
-	/** Check if the sender is already verified here */
+	/* Check if the sender is already verified here */
 
 	$hub = zot_gethub($sender);
 
-	if(! $hub) {
+	if (! $hub) {
 
-		/** Have never seen this guid or this guid coming from this location. Check it and register it. */
+		/* Have never seen this guid or this guid coming from this location. Check it and register it. */
 
 		// (!!) this will validate the sender
 		$result = zot_register_hub($sender);
 
-		if((! $result['success']) || (! ($hub = zot_gethub($sender)))) {
+		if ((! $result['success']) || (! ($hub = zot_gethub($sender)))) {
 			$ret['message'] = 'Hub not available.';
 			logger('mod_zot: no hub');
 			json_return_and_die($ret);
@@ -695,12 +693,12 @@ function post_post(&$a) {
 
 	// a dead hub came back to life - reset any tombstones we might have
 
-	if($hub['hubloc_status'] & HUBLOC_OFFLINE) {
+	if ($hub['hubloc_status'] & HUBLOC_OFFLINE) {
 		q("update hubloc set hubloc_status = (hubloc_status & ~%d) where hubloc_id = %d",
 			intval(HUBLOC_OFFLINE),
 			intval($hub['hubloc_id'])		
 		);
-		if($r[0]['hubloc_flags'] & HUBLOC_FLAGS_ORPHANCHECK) {
+		if ($r[0]['hubloc_flags'] & HUBLOC_FLAGS_ORPHANCHECK) {
 			q("update hubloc set hubloc_flags = (hubloc_flags & ~%d) where hubloc_id = %d",
 				intval(HUBLOC_FLAGS_ORPHANCHECK),
 				intval($hub['hubloc_id'])
@@ -711,15 +709,13 @@ function post_post(&$a) {
 			intval(XCHAN_FLAGS_ORPHAN),
 			dbesc($hub['hubloc_hash'])
 		);
-	} 
-
+	}
 
 
-	/** 
+	/*
 	 * This hub has now been proven to be valid.
 	 * Any hub with the same URL and a different sitekey cannot be valid.
 	 * Get rid of them (mark them deleted). There's a good chance they were re-installs.
-	 *
 	 */
 
 	q("update hubloc set hubloc_flags = ( hubloc_flags | %d ) where hubloc_url = '%s' and hubloc_sitekey != '%s' ",
@@ -728,15 +724,15 @@ function post_post(&$a) {
 		dbesc($hub['hubloc_sitekey'])
 	);
 
-	// TODO: check which hub is primary and take action if mismatched
+	/** @TODO check which hub is primary and take action if mismatched */
 
-	if(array_key_exists('recipients',$data))
+	if (array_key_exists('recipients', $data))
 		$recipients = $data['recipients'];
 
 
-	if($msgtype === 'auth_check') {
+	if ($msgtype === 'auth_check') {
 
-		/**
+		/*
 		 * Requestor visits /magic/?dest=somewhere on their own site with a browser
 		 * magic redirects them to $destsite/post [with auth args....]
 		 * $destsite sends an auth_check packet to originator site
@@ -751,12 +747,12 @@ function post_post(&$a) {
 		 */
 		logger('mod_zot: auth_check', LOGGER_DEBUG);
 
-		if(! $encrypted_packet) {
+		if (! $encrypted_packet) {
 			logger('mod_zot: auth_check packet was not encrypted.');
 			$ret['message'] .= 'no packet encryption' . EOL;
 			json_return_and_die($ret);
 		}
-		
+
 		$arr = $data['sender'];
 		$sender_hash = make_xchan_hash($arr['guid'],$arr['guid_sig']);
 
@@ -774,7 +770,7 @@ function post_post(&$a) {
 		// First verify their signature. We will have obtained a zot-info packet from them as part of the sender
 		// verification. 
 
-		if((! $y) || (! rsa_verify($data['secret'],base64url_decode($data['secret_sig']),$y[0]['xchan_pubkey']))) {
+		if ((! $y) || (! rsa_verify($data['secret'], base64url_decode($data['secret_sig']),$y[0]['xchan_pubkey']))) {
 			logger('mod_zot: auth_check: sender not found or secret_sig invalid.');
 			$ret['message'] .= 'sender not found or sig invalid ' . print_r($y,true) . EOL;
 			json_return_and_die($ret);
@@ -784,14 +780,14 @@ function post_post(&$a) {
 
 		$ret['message'] .= 'recipients ' . print_r($recipients,true) . EOL;
 
-		if($data['recipients']) {
+		if ($data['recipients']) {
 
 			$arr = $data['recipients'][0];
-			$recip_hash = make_xchan_hash($arr['guid'],$arr['guid_sig']);
+			$recip_hash = make_xchan_hash($arr['guid'], $arr['guid_sig']);
 			$c = q("select channel_id, channel_account_id, channel_prvkey from channel where channel_hash = '%s' limit 1",
 				dbesc($recip_hash)
 			);
-			if(! $c) {
+			if (! $c) {
 				logger('mod_zot: auth_check: recipient channel not found.');
 				$ret['message'] .= 'recipient not found.' . EOL;
 				json_return_and_die($ret);
@@ -807,7 +803,7 @@ function post_post(&$a) {
 				dbesc($data['secret']),
 				dbesc($data['sender']['url'])
 			);
-			if(! $z) {
+			if (! $z) {
 				logger('mod_zot: auth_check: verification key not found.');
 				$ret['message'] .= 'verification key not found' . EOL;
 				json_return_and_die($ret);
@@ -823,70 +819,66 @@ function post_post(&$a) {
 			logger('mod_zot: auth_check: success', LOGGER_DEBUG);
 			$ret['success'] = true;
 			$ret['confirm'] = $confirm;
-			if($u && $u[0]['account_service_class'])
+			if ($u && $u[0]['account_service_class'])
 				$ret['service_class'] = $u[0]['account_service_class'];
 
 			// Set "do not track" flag if this site or this channel's profile is restricted
 			// in some way
 
-			if(intval(get_config('system','block_public')))
+			if (intval(get_config('system','block_public')))
 				$ret['DNT'] = true;
-			if(! perm_is_allowed($c[0]['channel_id'],'','view_profile'))
+			if (! perm_is_allowed($c[0]['channel_id'],'','view_profile'))
 				$ret['DNT'] = true;
-			if(get_pconfig($c[0]['channel_id'],'system','do_not_track'))
+			if (get_pconfig($c[0]['channel_id'],'system','do_not_track'))
 				$ret['DNT'] = true;
-			if(get_pconfig($c[0]['channel_id'],'system','hide_online_status'))
+			if (get_pconfig($c[0]['channel_id'],'system','hide_online_status'))
 				$ret['DNT'] = true;
 
 			json_return_and_die($ret);
-
 		}
 		json_return_and_die($ret);
 	}
 
-	if($msgtype === 'request') {
+	if ($msgtype === 'request') {
 		// request a particular post/conversation by message_id
 		$x = zot_process_message_request($data);
 		json_return_and_die($x);		
 	}
 
-
-	if($msgtype === 'purge') {
-		if($recipients) {
+	if ($msgtype === 'purge') {
+		if ($recipients) {
 			// basically this means "unfriend"
-			foreach($recipients as $recip) {
+			foreach ($recipients as $recip) {
 				$r = q("select channel.*,xchan.* from channel 
 					left join xchan on channel_hash = xchan_hash
 					where channel_guid = '%s' and channel_guid_sig = '%s' limit 1",
 					dbesc($recip['guid']),
 					dbesc($recip['guid_sig'])
 				);
-				if($r) {
+				if ($r) {
 					$r = q("select abook_id from abook where uid = %d and abook_xchan = '%s' limit 1",
 						intval($r[0]['channel_id']),
 						dbesc(make_xchan_hash($sender['guid'],$sender['guid_sig']))
 					);
-					if($r) {
+					if ($r) {
 						contact_remove($r[0]['channel_id'],$r[0]['abook_id']);
 					}
 				}
 			}
-		}
-		else {
+		} else {
 			// Unfriend everybody - basically this means the channel has committed suicide
 			$arr = $data['sender'];
 			$sender_hash = make_xchan_hash($arr['guid'],$arr['guid_sig']);
-		
+
 			require_once('include/Contact.php');
 			remove_all_xchan_resources($sender_hash);	
 
 			$ret['success'] = true;
 			json_return_and_die($ret);
-
 		}
 	}
 
-	if(($msgtype === 'refresh') || ($msgtype === 'force_refresh')) {
+	if (($msgtype === 'refresh') || ($msgtype === 'force_refresh')) {
 
 		// remote channel info (such as permissions or photo or something)
 		// has been updated. Grab a fresh copy and sync it.
@@ -894,11 +886,11 @@ function post_post(&$a) {
 		// force_refresh unconditionally creates a directory update record,
 		// even if no changes were detected upon processing.
 
-		if($recipients) {
+		if ($recipients) {
 
 			// This would be a permissions update, typically for one connection
 
-			foreach($recipients as $recip) {	
+			foreach ($recipients as $recip) {
 				$r = q("select channel.*,xchan.* from channel 
 					left join xchan on channel_hash = xchan_hash
 					where channel_guid = '%s' and channel_guid_sig = '%s' limit 1",
@@ -910,44 +902,37 @@ function post_post(&$a) {
 						'xchan_guid'     => $sender['guid'], 
 						'xchan_guid_sig' => $sender['guid_sig'],
 						'hubloc_url'     => $sender['url']
-				),$r[0], (($msgtype === 'force_refresh') ? true : false));
+				), $r[0], (($msgtype === 'force_refresh') ? true : false));
 			}
-		}
-		else {
+		} else {
 
 			// system wide refresh
-				
+
 			$x = zot_refresh(array(
 				'xchan_guid'     => $sender['guid'], 
 				'xchan_guid_sig' => $sender['guid_sig'],
 				'hubloc_url'     => $sender['url']
-			),null,(($msgtype === 'force_refresh') ? true : false));
+			), null, (($msgtype === 'force_refresh') ? true : false));
 		}
 		$ret['success'] = true;
 		json_return_and_die($ret);
 	}
 
-	if($msgtype === 'notify') {
+	if ($msgtype === 'notify') {
 		$async = get_config('system','queued_fetch');
 
-		if($async) {
+		if ($async) {
 			// add to receive queue
 			// qreceive_add($data);
-		}
-		else {
+		} else {
 			$x = zot_fetch($data);
 			$ret['delivery_report'] = $x;
 		}
 
 		$ret['success'] = true;
 		json_return_and_die($ret);
-
 	}
 
-
 	// catchall
 	json_return_and_die($ret);
-
-
 }
-
diff --git a/mod/randprof.php b/mod/randprof.php
index bddb3251a..9817685c8 100644
--- a/mod/randprof.php
+++ b/mod/randprof.php
@@ -6,6 +6,7 @@ function randprof_init(&$a) {
 	$x = random_profile();
 	if($x)
 		goaway(chanlink_url($x));
-	// FIXME this doesn't work at the moment as a fallback
+
+	/** FIXME this doesn't work at the moment as a fallback */
 	goaway($a->get_baseurl() . '/profile');
 }
diff --git a/mod/regdir.php b/mod/regdir.php
index 5331c1dd4..025be220b 100644
--- a/mod/regdir.php
+++ b/mod/regdir.php
@@ -1,18 +1,17 @@
 <?php
 
-
 /**
- * With args, register a directory server for this realm
- * With no args, return a JSON array of directory servers for this realm
-
- * FIXME: Not yet implemented: Some realms may require authentication to join their realm.
- * The RED_GLOBAL realm does not require authentication.  
+ * With args, register a directory server for this realm.
+ * With no args, return a JSON array of directory servers for this realm.
+ *
+ * @FIXME Not yet implemented: Some realms may require authentication to join their realm.
+ * The RED_GLOBAL realm does not require authentication.
  * We would then need a flag in the site table to indicate that they've been
  * validated by the PRIMARY directory for that realm. Sites claiming to be PRIMARY
- * but are not the realm PRIMARY will be marked invalid. 
+ * but are not the realm PRIMARY will be marked invalid.
+ * 
+ * @param App &$a
  */
-
-
 function regdir_init(&$a) {
 
 	$result = array('success' => false);
@@ -31,8 +30,7 @@ function regdir_init(&$a) {
 
 	if($realm === DIRECTORY_REALM) {
 		$valid = 1;
-	}
-	else {
+	} else {
 		$token = get_config('system','realm_token');
 		if($token && $access_token != $token) {
 			$result['message'] = 'This realm requires an access token';
@@ -40,19 +38,19 @@ function regdir_init(&$a) {
 		}
 		$valid = 1;
 	}
-	
+
 	$dirmode = intval(get_config('system','directory_mode'));
 
-	if($dirmode == DIRECTORY_MODE_NORMAL) {
+	if ($dirmode == DIRECTORY_MODE_NORMAL) {
 		$ret['message'] = t('This site is not a directory server');
 		json_return_and_die($ret);
 	}
 
 	$m = null;
-	if($url) {
+	if ($url) {
 		$m = parse_url($url);
 
-		if((! $m) || (! @dns_get_record($m['host'], DNS_A + DNS_CNAME + DNS_PTR)) || (! filter_var($m['host'], FILTER_VALIDATE_IP) )) {
+		if ((! $m) || (! @dns_get_record($m['host'], DNS_A + DNS_CNAME + DNS_PTR)) || (! filter_var($m['host'], FILTER_VALIDATE_IP) )) {
 			$result['message'] = 'unparseable url';
 			json_return_and_die($result);
 		}
@@ -75,31 +73,28 @@ function regdir_init(&$a) {
 		);
 
 		json_return_and_die($result);
-	}
-	else {
+	} else {
 
 		// We can put this in the sql without the condition after 31 april 2015 assuming
 		// most directory servers will have updated by then
 		// This just makes sure it happens if I forget
 
 		$sql_extra = ((datetime_convert() > datetime_convert('UTC','UTC','2015-04-31')) ? ' and site_valid = 1 ' : '' );
-		if($dirmode == DIRECTORY_MODE_STANDALONE) {
+		if ($dirmode == DIRECTORY_MODE_STANDALONE) {
 			$r = array(array('site_url' => z_root()));
-		}
-		else {
+		} else {
 			$r = q("select site_url from site where site_flags in ( 1, 2 ) and site_realm = '%s' $sql_extra ",
 				dbesc(get_directory_realm())
 			);
 		}
-		if($r) {
+		if ($r) {
 			$result['success'] = true;
 			$result['directories'] = array();
-			foreach($r as $rr)
+			foreach ($r as $rr)
 				$result['directories'][] = $rr['site_url'];
+
 			json_return_and_die($result);
 		}
 	}
 	json_return_and_die($result);
-		
-
-}			
\ No newline at end of file
+}
\ No newline at end of file
diff --git a/mod/share.php b/mod/share.php
index 923971694..d5a389bdf 100644
--- a/mod/share.php
+++ b/mod/share.php
@@ -13,7 +13,6 @@ function share_init(&$a) {
 	if(! (local_channel() || remote_channel()))
 		killme();
 
-
 	$r = q("SELECT * from item left join xchan on author_xchan = xchan_hash WHERE id = %d  LIMIT 1",
 		intval($post_id)
 	);
@@ -30,13 +29,12 @@ function share_init(&$a) {
 	if(! $r)
 		killme();
 
-	// FIXME - we only share bbcode
+	/** @FIXME we only share bbcode */
 
 	if($r[0]['mimetype'] !== 'text/bbcode')
 		killme();
 
-	// FIXME - eventually we want to post remotely via rpost
-	// on your home site.
+	/** @FIXME eventually we want to post remotely via rpost on your home site */
 	// When that works remove this next bit:
 
 	if(! local_channel())
@@ -64,20 +62,20 @@ function share_init(&$a) {
 		echo $o;
 		killme();
 	}
-	
+
 	$observer = $a->get_observer();
 	$parsed = $observer['xchan_url'];
 	if($parsed) {
 		$post_url = $parsed['scheme'] . ':' . $parsed['host'] . (($parsed['port']) ? ':' . $parsed['port'] : '')
 			. '/rpost';
-		// FIXME - we were probably called from JS
-		// so we don't know the return page.
-		// in fact we won't be able to load the remote page.
-		// we might need an iframe
+
+		/**
+		 * @FIXME we were probably called from JS so we don't know the return page.
+		 * In fact we won't be able to load the remote page.
+		 * we might need an iframe
+		 */
 
 		$x = z_post_url($post_url, array('f' => '', 'body' => $o ));
 		killme();
 	}
-	
-
 }
diff --git a/mod/thing.php b/mod/thing.php
index 4ec10f5a6..c6b70fbb4 100644
--- a/mod/thing.php
+++ b/mod/thing.php
@@ -1,4 +1,8 @@
-<?php /** @file */
+<?php
+/**
+ * @file mod/thing.php
+ * @brief
+ */
 
 require_once('include/items.php');
 require_once('include/contact_selectors.php');
@@ -9,9 +13,6 @@ function thing_init(&$a) {
 	if(! local_channel())
 		return;
 
-
-
-
 	$account_id = $a->get_account();
 	$channel    = $a->get_channel();
 
@@ -26,19 +27,18 @@ function thing_init(&$a) {
 
 	$hash = random_string();
 
-
 	$verbs = obj_verbs();
 
-	/** 
+	/**
 	 * verbs: [0] = first person singular, e.g. "I want", [1] = 3rd person singular, e.g. "Bill wants" 
 	 * We use the first person form when creating an activity, but the third person for use in activities
-	 * FIXME: There is no accounting for verb gender for languages where this is significant. We may eventually
+	 * @FIXME There is no accounting for verb gender for languages where this is significant. We may eventually
 	 * require obj_verbs() to provide full conjugations and specify which form to use in the $_REQUEST params to this module.
 	 */
 
 	$translated_verb = $verbs[$verb][1];
 
-	/** 
+	/*
 	 * The site administrator can do things that normals cannot.
 	 * This is restricted because it will likely cause
 	 * an activitystreams protocol violation and the activity might
@@ -50,14 +50,14 @@ function thing_init(&$a) {
 	if(! $translated_verb) {
 		if(is_site_admin())
 			$translated_verb = $verb;
-	} 
-	
-	/**
+	}
+
+	/*
 	 * Things, objects: We do not provide definite (a, an) or indefinite (the) articles or singular/plural designators
 	 * That needs to be specified in your thing. e.g. Mike has "a carrot", Greg wants "balls", Bob likes "the Boston Red Sox".  
 	 */
 
-	/**
+	/*
 	 * Future work on this module might produce more complex activities with targets, e.g. Phillip likes Karen's moustache
 	 * and to describe other non-thing objects like channels, such as Karl wants Susan - where Susan represents a channel profile.
 	 */
@@ -65,8 +65,6 @@ function thing_init(&$a) {
 	if((! $name) || (! $translated_verb))
 		return;
 
-
-
 	if($term_hash) {
 		$t = q("select * from obj left join term on obj_obj = term_hash where term_hash != '' and obj_type = %d and term_hash = '%s' limit 1",
 			intval(TERM_OBJ_THING),
@@ -115,7 +113,6 @@ function thing_init(&$a) {
 		$local_photo_type = $arr[3];
 	}
 
-
 	$r = q("select * from term where uid = %d and otype = %d and type = %d and term = '%s' limit 1",
 		intval(local_channel()),
 		intval(TERM_OBJ_THING),
@@ -159,14 +156,12 @@ function thing_init(&$a) {
 
 	info( t('Thing added'));
 
-
 	if($activity) {
 		$arr = array();
 		$links = array(array('rel' => 'alternate','type' => 'text/html', 'href' => $term['url']));
 		if($local_photo)
 			$links[] = array('rel' => 'photo', 'type' => $local_photo_type, 'href' => $local_photo);
 
-
 		$objtype = ACTIVITY_OBJ_THING;
 
 		$obj = json_encode(array(
@@ -182,9 +177,8 @@ function thing_init(&$a) {
 		$arr['owner_xchan']  = $channel['channel_hash'];
 		$arr['author_xchan'] = $channel['channel_hash'];
 
-
 		$arr['item_flags'] = ITEM_ORIGIN|ITEM_WALL|ITEM_THREAD_TOP;
-	
+
 		$ulink = '[zrl=' . $channel['xchan_url'] . ']' . $channel['channel_name'] . '[/zrl]';
 		$plink = '[zrl=' . $term['url'] . ']' . $term['term'] . '[/zrl]';
 
@@ -212,14 +206,14 @@ function thing_init(&$a) {
 			else
 				$arr['allow_cid'] = '<' . get_observer_hash() . '>';
 		}
-	
+
 		$ret = post_activity_item($arr);
 	}
 }
 
 
 function thing_content(&$a) {
-	
+
 	if(argc() == 2) {
 
 		$r = q("select * from obj left join term on obj_obj = term_hash where term_hash != '' and obj_type = %d and term_hash = '%s' limit 1",
@@ -249,12 +243,10 @@ function thing_content(&$a) {
 	}
 
 	$thing_hash = '';
-	
 
 	if(argc() == 3 && argv(1) === 'edit') {
 		$thing_hash = argv(2);
 
-
 		$r = q("select * from obj left join term on obj_obj = term_hash where term_hash != '' and obj_type = %d and term_hash = '%s' limit 1",
 			intval(TERM_OBJ_THING),
 			dbesc($thing_hash)
@@ -265,7 +257,6 @@ function thing_content(&$a) {
 			return '';
 		}
 
-
 		$o .= replace_macros(get_markup_template('thing_edit.tpl'),array(
 			'$thing_hdr' => t('Edit Thing'),
 			'$multiprof' => feature_enabled(local_channel(),'multi_profiles'),
@@ -300,7 +291,6 @@ function thing_content(&$a) {
 			return '';
 		}
 
-
 		$x = q("delete from obj where obj_obj = '%s' and obj_type = %d and obj_channel = %d",
 			dbesc($thing_hash),
 			intval(TERM_OBJ_THING),
@@ -310,6 +300,7 @@ function thing_content(&$a) {
 			dbesc($thing_hash),
 			intval(local_channel())
 		);
+
 		return $o;
 	}
 
@@ -328,6 +319,4 @@ function thing_content(&$a) {
 	));
 
 	return $o;
-
-
 }
diff --git a/util/Doxyfile b/util/Doxyfile
index 44fef3838..f700c2abe 100644
--- a/util/Doxyfile
+++ b/util/Doxyfile
@@ -1,4 +1,4 @@
-INPUT = index.php boot.php mod/ include/ setup/ util/ view/
+INPUT = README.md index.php boot.php mod/ include/ util/ view/ version.inc
 RECURSIVE = YES
 PROJECT_NAME = "The RedMatrix"
 PROJECT_LOGO = images/rm-64.png
@@ -12,9 +12,12 @@ GENERATE_LATEX = NO
 EXTRACT_ALL = YES
 EXTRACT_PRIVATE = YES
 GENERATE_TODOLIST = YES
-USE_MDFILE_AS_MAINPAGE = README
+USE_MDFILE_AS_MAINPAGE = README.md
 REFERENCED_BY_RELATION = YES
 GENERATE_TREEVIEW = YES
 HTML_FOOTER = util/Doxygen.footer
 ALIASES += "license=@par License:\n"
 ALIASES += "fixme=\xrefitem fixme \"Fixme\" \"Fixme List\""
+ALIASES += "FIXME=\fixme"
+ALIASES += "TODO=\todo"
+ALIASES += "BUG=\bug"