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.

8 files changed, 477 insertions, 519 deletions

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;
-
-
 }