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.

1 files changed, 257 insertions, 272 deletions

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