Merge pull request #547 from dawnbreak/docu

[TASK] Update Doxyfile and fix Doxygen errors.

Zotlabs/Module/Admin.php

@@ -1,21 +1,20 @@
 <?php
-namespace Zotlabs\Module;
-
-
 /**
- * @file mod/admin.php
+ * @file Zotlabs/Module/Admin.php
  * @brief Hubzilla's admin controller.
  *
  * Controller for the /admin/ area.
  */
 
+namespace Zotlabs\Module;
+
 require_once('include/queue_fn.php');
 require_once('include/account.php');
 
 /**
- * @param App &$a
+ * @brief Admin area.
+ *
  */
-
 class Admin extends \Zotlabs\Web\Controller {
 
 	private $sm = null;
@@ -49,7 +48,6 @@ class Admin extends \Zotlabs\Web\Controller {
 			return login(false);
 		}
 
-	
 		/*
 		 * Page content
 		 */
@@ -80,7 +78,6 @@ class Admin extends \Zotlabs\Web\Controller {
 	/**
 	 * @brief Returns content for Admin Summary Page.
 	 *
-	 * @param App &$a
 	 * @return string HTML from parsed admin_summary.tpl
 	 */
 	function admin_page_summary() {
@@ -135,7 +132,6 @@ class Admin extends \Zotlabs\Web\Controller {
 
 		$upgrade = ((version_compare(STD_VERSION,$vmaster) < 0) ? t('Your software should be updated') : '');
 
-
 		$t = get_markup_template('admin_summary.tpl');
 		return replace_macros($t, array(
 			'$title' => t('Administration'),
@@ -154,6 +150,4 @@ class Admin extends \Zotlabs\Web\Controller {
 		));
 	}
 
-	
-	
 }

Zotlabs/Module/Admin/Channels.php

@@ -2,14 +2,15 @@
 
 namespace Zotlabs\Module\Admin;
 
-
+/**
+ * @brief Admin Module for Channels.
+ *
+ */
 class Channels {
 
-	
 	/**
-	 * @brief Channels admin page.
+	 * @brief Handle POST actions on channels admin page.
 	 *
-	 * @param App &$a
 	 */
 	function post() {
 
@@ -48,13 +49,11 @@ class Channels {
 		goaway(z_root() . '/admin/channels' );
 	}
 
-
 	/**
-	 * @brief
+	 * @brief Generate channels admin page and handle single item operations.
 	 *
-	 * @return string
+	 * @return string with parsed HTML
 	 */
-
 	function get() {
 		if(argc() > 2) {
 			$uid = argv(3);
@@ -105,7 +104,6 @@ class Channels {
 			goaway(z_root() . '/admin/channels' );
 		}
 
-
 		$key = (($_REQUEST['key']) ? dbesc($_REQUEST['key']) : 'channel_id');
 		$dir = 'asc';
 		if(array_key_exists('dir',$_REQUEST))
@@ -114,8 +112,6 @@ class Channels {
 		$base = z_root() . '/admin/channels?f=';
 		$odir = (($dir === 'asc') ? '0' : '1');
 
-
-	
 		/* get channels */
 
 		$total = q("SELECT count(*) as total FROM channel where channel_removed = 0 and channel_system = 0");
@@ -143,7 +139,7 @@ class Channels {
 			}
 		}
 
-		$t = get_markup_template("admin_channels.tpl");
+		$t = get_markup_template('admin_channels.tpl');
 		$o = replace_macros($t, array(
 			// strings //
 			'$title' => t('Administration'),
@@ -166,7 +162,7 @@ class Channels {
 			'$confirm_delete_multi' => t('Selected channels will be deleted!\n\nEverything that was posted in these channels on this site will be permanently deleted!\n\nAre you sure?'),
 			'$confirm_delete' => t('The channel {0} will be deleted!\n\nEverything that was posted in this channel on this site will be permanently deleted!\n\nAre you sure?'),
 
-			'$form_security_token' => get_form_security_token("admin_channels"),
+			'$form_security_token' => get_form_security_token('admin_channels'),
 
 			// values //
 			'$baseurl' => z_root(),
@@ -177,10 +173,4 @@ class Channels {
 		return $o;
 	}
 
-
-
-
-
-
-
 }

Zotlabs/Module/Admin/Site.php

@@ -5,11 +5,9 @@ namespace Zotlabs\Module\Admin;
 
 class Site {
 
-	
 	/**
 	 * @brief POST handler for Admin Site Page.
 	 *
-	 * @param App &$a
 	 */
 	function post(){
 		if (!x($_POST, 'page_site')) {
@@ -65,8 +63,6 @@ class Site {
 		if(array_key_exists('techlevel', $_POST))
 			$techlevel = intval($_POST['techlevel']);
 
-	
-
 		set_config('system', 'server_role', $server_role);
 		set_config('system', 'feed_contacts', $feed_contacts);
 		set_config('system', 'delivery_interval', $delivery_interval);
@@ -139,9 +135,8 @@ class Site {
 	/**
 	 * @brief Admin page site.
 	 *
-	 * @return string
+	 * @return string with HTML
 	 */
-
 	function get() {
 
 		/* Installed langs */
@@ -244,7 +239,6 @@ class Site {
 			'pro'      => t('Professional')
 		];
 
-
 		$techlevels = [
 			'0' => t('Beginner/Basic'),
 			'1' => t('Novice - not skilled but willing to learn'),
@@ -254,9 +248,6 @@ class Site {
 			'5' => t('Wizard - I probably know more than you do')
 		];
 
-
-
-	
 		$homelogin = get_config('system','login_on_homepage');
 		$enable_context_help = get_config('system','enable_context_help');
 
@@ -280,7 +271,6 @@ class Site {
 
 			'$techlock' => [ 'techlock', t('Lock the technical skill level setting'), get_config('system','techlevel_lock'), t('Members can set their own technical comfort level by default') ],
 
-
 			'$banner'			=> array('banner', t("Banner/Logo"), $banner, ""),
 			'$admininfo'		=> array('admininfo', t("Administrator Information"), $admininfo, t("Contact information for site administrators.  Displayed on siteinfo page.  BBCode can be used here")),
 			'$language' 		=> array('language', t("System language"), get_config('system','language'), "", $lang_choices),
@@ -317,7 +307,4 @@ class Site {
 		));
 	}
 
-
-
-
 }

Zotlabs/Module/Channel.php

@@ -1,6 +1,6 @@
 <?php
-namespace Zotlabs\Module;
 
+namespace Zotlabs\Module;
 
 require_once('include/contact_widgets.php');
 require_once('include/items.php');
@@ -10,6 +10,10 @@ require_once('include/conversation.php');
 require_once('include/acl_selectors.php');
 require_once('include/permissions.php');
 
+/**
+ * @brief Channel Controller
+ *
+ */
 class Channel extends \Zotlabs\Web\Controller {
 
 	function init() {
@@ -48,12 +52,10 @@ class Channel extends \Zotlabs\Web\Controller {
 		// we start loading content
 
 		profile_load($which,$profile);
-
 	}
 
 	function get($update = 0, $load = false) {
 
-
 		if($load)
 			$_SESSION['loadtime'] = datetime_convert();
 
@@ -228,7 +230,6 @@ class Channel extends \Zotlabs\Web\Controller {
 					if (! $r) {
 						notice( t('Permission denied.') . EOL);
 					}
-
 				}
 				else {
 					$r = q("SELECT distinct id AS item_id, created FROM item
@@ -270,8 +271,7 @@ class Channel extends \Zotlabs\Web\Controller {
 				notice( t('Permission denied.') . EOL);
 			}
 
-		} 
+		} else {
-		else {
 			$items = array();
 		}
 
@@ -317,7 +317,6 @@ class Channel extends \Zotlabs\Web\Controller {
 				'$dbegin' => $datequery2
 			));
 
-
 		}
 
 		$update_unseen = '';

Zotlabs/Module/Cloud.php

@@ -1,7 +1,7 @@
 <?php
 namespace Zotlabs\Module;
 /**
- * @file mod/cloud.php
+ * @file Zotlabs/Module/Cloud.php
  * @brief Initialize Hubzilla's cloud (SabreDAV).
  *
  * Module for accessing the DAV storage area.
@@ -17,14 +17,15 @@ require_once('include/attach.php');
 
 
 /**
- * @brief Fires up the SabreDAV server.
+ * @brief Cloud Module.
  *
- * @param App &$a
  */
-
-
 class Cloud extends \Zotlabs\Web\Controller {
 
+	/**
+	 * @brief Fires up the SabreDAV server.
+	 *
+	 */
 	function init() {
 
 		if (! is_dir('store'))

Zotlabs/Module/Dav.php

@@ -1,13 +1,13 @@
 <?php
-
-namespace Zotlabs\Module;
 /**
- * @file mod/dav.php
+ * @file Zotlabs/Module/Dav.php
  * @brief Initialize Hubzilla's cloud (SabreDAV).
  *
  * Module for accessing the DAV storage area from a DAV client.
  */
 
+namespace Zotlabs\Module;
+
 use \Sabre\DAV as SDAV;
 use \Zotlabs\Storage;
 
@@ -16,14 +16,12 @@ require_once('vendor/autoload.php');
 
 require_once('include/attach.php');
 
+class Dav extends \Zotlabs\Web\Controller {
+
 	/**
 	 * @brief Fires up the SabreDAV server.
 	 *
- * @param App &$a
 	 */
-
-class Dav extends \Zotlabs\Web\Controller {
-
 	function init() {
 
 		// workaround for HTTP-auth in CGI mode

Zotlabs/Module/Embedphotos.php

@@ -1,21 +1,23 @@
 <?php
+
 namespace Zotlabs\Module;
 
 /**
- *
+ * @brief
- * This is the POST destination for the embedphotos button
  *
  */
-
-
 class Embedphotos extends \Zotlabs\Web\Controller {
 
 	function get() {
 
 	}
 
+	/**
+	 *
+	 * This is the POST destination for the embedphotos button
+	 *
+	 */
 	function post() {
-		
 		if (argc() > 1 && argv(1) === 'album') {
 			// API: /embedphotos/album
 			$name = (x($_POST,'name') ? $_POST['name'] : null );
@@ -24,13 +26,11 @@ class Embedphotos extends \Zotlabs\Web\Controller {
 			}
 			$album = $this->embedphotos_widget_album(array('channel' => \App::get_channel(), 'album' => $name));
 			json_return_and_die(array('status' => true, 'content' => $album));
-
 		}
 		if(argc() > 1 && argv(1) === 'albumlist') {
 			// API: /embedphotos/albumlist
 			$album_list = $this->embedphotos_album_list($a);
 			json_return_and_die(array('status' => true, 'albumlist' => $album_list));
-
 		}
 		if(argc() > 1 && argv(1) === 'photolink') {
 			// API: /embedphotos/photolink
@@ -54,16 +54,15 @@ class Embedphotos extends \Zotlabs\Web\Controller {
 				json_return_and_die(array('errormsg' => 'Error retrieving resource ' . $resource_id, 'status' => false));
 			}
 			json_return_and_die(array('status' => true, 'photolink' => $photolink));
-
 		}
 	}
 
-	
 	/**
 	 * Copied from include/widgets.php::widget_album() with a modification to get the profile_uid from
 	 * the input array as in widget_item()
- * @param type $name
+	 *
- * @return string
+	 * @param array $args
+	 * @return string with HTML
 	 */
 	function embedphotos_widget_album($args) {
 
@@ -75,6 +74,7 @@ function embedphotos_widget_album($args) {
 			$channel_id = \App::$profile_uid;
 		if(! $channel_id)
 			return '';
+
 		$owner_uid = $channel_id;
 		require_once('include/security.php');
 		$sql_extra = permissions_sql($channel_id);
@@ -91,7 +91,6 @@ function embedphotos_widget_album($args) {
 		 * This may return incorrect permissions if you have multiple directories of the same name.
 		 * It is a limitation of the photo table using a name for a photo album instead of a folder hash
 		 */
-
 		if($album) {
 			$x = q("select hash from attach where filename = '%s' and uid = %d limit 1",
 				dbesc($album),
@@ -120,7 +119,6 @@ function embedphotos_widget_album($args) {
 		if(count($r)) {
 			$twist = 'rotright';
 			foreach($r as $rr) {
-	
 				if($twist == 'rotright')
 					$twist = 'rotleft';
 				else
@@ -165,9 +163,7 @@ function embedphotos_widget_album($args) {
 		return $o;
 	}
 
-
 	function embedphotos_album_list($a) {
-    $o = '';
 		require_once('include/photos.php');
 		$p = photos_albums_list(\App::get_channel(), \App::get_observer());
 		if($p['success']) {

Zotlabs/Module/Filestorage.php

@@ -1,7 +1,7 @@
 <?php
 namespace Zotlabs\Module;
 /**
- * @file mod/filestorage.php
+ * @file Zotlabs/Module/Filestorage.php
  *
  */
 

Zotlabs/Module/Help.php

@@ -1,27 +1,23 @@
 <?php
 namespace Zotlabs\Module;
 
-
 require_once('include/help.php');
 
 /**
  * You can create local site resources in doc/Site.md and either link to doc/Home.md for the standard resources
  * or use our include mechanism to include it on your local page.
- *
+ *@code
  * #include doc/Home.md;
+ *@endcode
  *
  * The syntax is somewhat strict.
- *
  */
-
 class Help extends \Zotlabs\Web\Controller {
 
 	function get() {
-
 		nav_set_selected('help');
 
 		if($_REQUEST['search']) {
-		
 			$o .= '<div id="help-content" class="generic-content-wrapper">';
 			$o .= '<div class="section-title-wrapper">';
 			$o .= '<h2>' . t('Documentation Search') . ' - ' . htmlspecialchars($_REQUEST['search']) . '</h2>';
@@ -37,30 +33,24 @@ class Help extends \Zotlabs\Web\Controller {
 					$fname = substr($fname, 0, strrpos($fname, '.'));
 					$path = trim(substr($dirname, 4), '/');
 
-					$o .= '<li><a href="help/' . (($path) ? $path . '/' : '') . $fname . '" >' . ucwords(str_replace('_',' ',notags($fname))) . '</a><br />'
+					$o .= '<li><a href="help/' . (($path) ? $path . '/' : '') . $fname . '" >' . ucwords(str_replace('_',' ',notags($fname))) . '</a><br>'
-						. '<b><i>' . 'help/' . (($path) ? $path . '/' : '') . $fname . '</i></b><br />' .
+						. '<b><i>' . 'help/' . (($path) ? $path . '/' : '') . $fname . '</i></b><br>'
-					'...' . str_replace('$Projectname',\Zotlabs\Lib\System::get_platform_name(),$rr['text']) . '...<br /><br /></li>';
+						. '...' . str_replace('$Projectname', \Zotlabs\Lib\System::get_platform_name(), $rr['text']) . '...<br><br></li>';
-	
 				}
 				$o .= '</ul>';
 				$o .= '</div>';
 				$o .= '</div>';
 			}
+
 			return $o;
 		}
 
-
 		$content =  get_help_content();
 
-
+		return replace_macros(get_markup_template('help.tpl'), array(
-		return replace_macros(get_markup_template("help.tpl"), array(
 			'$title' => t('$Projectname Documentation'),
 			'$content' => $content
 		));
-	
 	}
 
-	
-	
-	
 }

Zotlabs/Module/Ping.php

@@ -1,13 +1,14 @@
 <?php
-namespace Zotlabs\Module;
 
-/**
+namespace Zotlabs\Module;
- * @file mod/ping.php
- *
- */
 
 require_once('include/bbcode.php');
 
+/**
+ * @brief Ping Controller.
+ *
+ */
+class Ping extends \Zotlabs\Web\Controller {
 
 	/**
 	 * @brief do several updates when pinged.
@@ -15,15 +16,9 @@ require_once('include/bbcode.php');
 	 * This function does several tasks. Whenever called it checks for new messages,
 	 * introductions, notifications, etc. and returns a json with the results.
 	 *
- * @param App &$a
 	 * @result JSON
 	 */
-
-
-class Ping extends \Zotlabs\Web\Controller {
-
 	function init() {
-	
 		$result = array();
 		$notifs = array();
 
@@ -97,7 +92,6 @@ class Ping extends \Zotlabs\Web\Controller {
 		if(! ($vnotify & VNOTIFY_ALERT))
 			$result['notice'] = array();
 
-	
 		if(\App::$install) {
 			echo json_encode($result);
 			killme();
@@ -149,7 +143,6 @@ class Ping extends \Zotlabs\Web\Controller {
 		 * Everything following is only permitted under the context of a locally authenticated site member.
 		 */
 
-	
 		/**
 		 * Handle "mark all xyz notifications read" requests.
 		 */
@@ -196,13 +189,10 @@ class Ping extends \Zotlabs\Web\Controller {
 			);
 		}
 
-	
-	
 		/**
 		 * URL ping/something will return detail for "something", e.g. a json list with which to populate a notification
 		 * dropdown menu.
 		 */
-	
 		if(argc() > 1 && argv(1) === 'notify') {
 			$t = q("select count(*) as total from notify where uid = %d and seen = 0",
 				intval(local_channel())
@@ -212,8 +202,7 @@ class Ping extends \Zotlabs\Web\Controller {
 					and seen = 0 order by created desc limit 50",
 					intval(local_channel())
 				);
-			}
+			} else {
-			else {
 				$z1 = q("select * from notify where uid = %d
 					and seen = 0 order by created desc limit 50",
 					intval(local_channel())
@@ -342,11 +331,10 @@ class Ping extends \Zotlabs\Web\Controller {
 
 					$strt = datetime_convert('UTC', (($rr['adjust']) ? date_default_timezone_get() : 'UTC'), $rr['dtstart']);
 					$today = ((substr($strt, 0, 10) === datetime_convert('UTC', date_default_timezone_get(), 'now', 'Y-m-d')) ? true : false);
-					
 					$when = day_translate(datetime_convert('UTC', (($rr['adjust']) ? date_default_timezone_get() : 'UTC'), $rr['dtstart'], $bd_format)) . (($today) ?  ' ' . t('[today]') : '');
 
 					$result[] = array(
-						'notify_link' => z_root() . '/events', // FIXME this takes you to an edit page and it may not be yours, we really want to just view the single event  --> '/events/event/' . $rr['event_hash'],
+						'notify_link' => z_root() . '/events', /// @FIXME this takes you to an edit page and it may not be yours, we really want to just view the single event  --> '/events/event/' . $rr['event_hash'],
 						'name'        => $rr['xchan_name'],
 						'url'         => $rr['xchan_url'],
 						'photo'       => $rr['xchan_photo_s'],
@@ -361,12 +349,9 @@ class Ping extends \Zotlabs\Web\Controller {
 			killme();
 		}
 
-	
-	
 		/**
 		 * Normal ping - just the counts, no detail
 		 */
-	
 		if($vnotify & VNOTIFY_SYSTEM) {
 			$t = q("select count(*) as total from notify where uid = %d and seen = 0",
 				intval(local_channel())
@@ -403,7 +388,6 @@ class Ping extends \Zotlabs\Web\Controller {
 		if(! ($vnotify & VNOTIFY_CHANNEL))
 			$result['home'] = 0;
 
-	
 		$t2 = dba_timer();
 
 		if($vnotify & VNOTIFY_INTRO) {
@@ -484,7 +468,6 @@ class Ping extends \Zotlabs\Web\Controller {
 		if(! ($vnotify & VNOTIFY_BIRTHDAY))
 			$result['birthdays'] = 0;
 
-	
 		$x = json_encode($result);
 
 		$t6 = dba_timer();

Zotlabs/Module/Post.php

@@ -1,36 +1,34 @@
 <?php
-namespace Zotlabs\Module;
-
 /**
- * @file mod/post.php
+ * @file Zotlabs/Module/Post.php
  *
  * @brief Zot endpoint.
  *
  */
 
+namespace Zotlabs\Module;
+
 require_once('include/zot.php');
 
-
+/**
+ * @brief Post module.
+ *
+ */
 class Post extends \Zotlabs\Web\Controller {
 
 	function init() {
-	
 		if(array_key_exists('auth', $_REQUEST)) {
 			$x = new \Zotlabs\Zot\Auth($_REQUEST);
+
 			exit;
 		}
-	
 	}
 
-	
 	function post() {
-	
 		$z = new \Zotlabs\Zot\Receiver($_REQUEST['data'], get_config('system', 'prvkey'), new \Zotlabs\Zot\ZotHandler());
 
 		// notreached;
-	
 		exit;
-	
 	}
 
 }

Zotlabs/Module/Setup.php

@@ -1,9 +1,9 @@
 <?php
 namespace Zotlabs\Module;
 /**
- * @file mod/setup.php
+ * @file Zotlabs/Module/Setup.php
  *
- * Controller for the initial setup/installation.
+ * @brief Controller for the initial setup/installation.
  *
  * @todo This setup module could need some love and improvements.
  */
@@ -13,14 +13,15 @@ namespace Zotlabs\Module;
  * @brief Initialisation for the setup module.
  *
  */
-
 class Setup extends \Zotlabs\Web\Controller {
 
 	private static $install_wizard_pass = 1;
 
-
+	/**
+	 * {@inheritDoc}
+	 * @see \\Zotlabs\\Web\\Controller::init()
+	 */
 	function init() {
-	
 		// Ensure that if somebody hasn't read the install documentation and doesn't have all
 		// the required modules or has a totally borked shared hosting provider and they can't
 		// figure out what the hell is going on - that we at least spit out an error message which
@@ -45,8 +46,7 @@ class Setup extends \Zotlabs\Web\Controller {
 
 		if (x($_POST, 'pass')) {
 			$this->install_wizard_pass = intval($_POST['pass']);
-		}
+		} else {
-		else {
 			$this->install_wizard_pass = 1;
 		}
 	}
@@ -55,7 +55,6 @@ class Setup extends \Zotlabs\Web\Controller {
 	 * @brief Handle the actions of the different setup steps.
 	 *
 	 */
-
 	function post() {
 
 		switch($this->install_wizard_pass) {
@@ -176,7 +175,6 @@ class Setup extends \Zotlabs\Web\Controller {
 	 *
 	 * @return string parsed HTML output
 	 */
-
 	function get() {
 
 		$o = '';
@@ -376,7 +374,7 @@ class Setup extends \Zotlabs\Web\Controller {
 	 * @param string $title a title for the check
 	 * @param boolean $status
 	 * @param boolean $required
-	 * @param[optional] string $help optional help string
+	 * @param string $help optional help string
 	 */
 	function check_add(&$checks, $title, $status, $required, $help = '') {
 		$checks[] = array(
@@ -649,7 +647,6 @@ class Setup extends \Zotlabs\Web\Controller {
 
 					$help .= t('If you are confident that the certificate is valid and signed by a trusted authority, check to see if you have failed to install an intermediate cert. These are not normally required by browsers, but are required for server-to-server communications.') . EOL;
 
-	
 					$this->check_add($checks, t('SSL certificate validation'), false, true, $help);
 				}
 			}
@@ -665,7 +662,12 @@ class Setup extends \Zotlabs\Web\Controller {
 		}
 	}
 
-	
+	/**
+	 * @brief
+	 *
+	 * @param App &$a
+	 * @return string with paresed HTML
+	 */
 	function manual_config(&$a) {
 		$data = htmlspecialchars(\App::$data['txt'], ENT_COMPAT, 'UTF-8');
 		$o = t('The database configuration file ".htconfig.php" could not be written. Please use the enclosed text to create a configuration file in your web server root.');
@@ -700,12 +702,16 @@ class Setup extends \Zotlabs\Web\Controller {
 		return $errors;
 	}
 
+	/**
+	 * @brief
+	 *
+	 * @return string with parsed HTML
+	 */
 	function what_next() {
 		$a = get_app();
 		// install the standard theme
 		set_config('system', 'allowed_themes', 'redbasic');
 
-
 		// Set a lenient list of ciphers if using openssl. Other ssl engines
 		// (e.g. NSS used in RedHat) require different syntax, so hopefully
 		// the default curl cipher list will work for most sites. If not,
@@ -737,7 +743,13 @@ class Setup extends \Zotlabs\Web\Controller {
 			."</p>";
 	}
 
-
+	/**
+	 * @brief
+	 *
+	 * @param unknown $v
+	 * @param array $c
+	 * @return array
+	 */
 	static private function check_passed($v, $c) {
 		if ($c['required'])
 			$v = $v && $c['status'];
@@ -745,5 +757,4 @@ class Setup extends \Zotlabs\Web\Controller {
 		return $v;
 	}
 
-	
 }

Zotlabs/Module/Thing.php

@@ -1,10 +1,10 @@
 <?php
-namespace Zotlabs\Module;
 /**
- * @file mod/thing.php
+ * @file Zotlabs/Module/Thing.php
- * @brief
  */
 
+namespace Zotlabs\Module;
+
 require_once('include/items.php');
 require_once('include/security.php');
 require_once('include/selectors.php');

Zotlabs/Storage/BasicAuth.php

@@ -12,7 +12,7 @@ use Sabre\HTTP\ResponseInterface;
  * This class also contains some data which is not necessary for authentication
  * like timezone settings.
  *
- * @extends Sabre\DAV\Auth\Backend\AbstractBasic
+ * @extends \\Sabre\\DAV\\Auth\\Backend\\AbstractBasic
  *
  * @link http://github.com/friendica/red
  * @license http://opensource.org/licenses/mit-license.php The MIT License (MIT)
@@ -24,37 +24,37 @@ class BasicAuth extends DAV\Auth\Backend\AbstractBasic {
 	 *
 	 * It is used for building path in filestorage/.
 	 *
-	 * @var string|null
+	 * @var string|null $channel_name
 	 */
 	protected $channel_name = null;
 	/**
-	 * channel_id of the current channel of the logged-in account.
+	 * @brief channel_id of the current channel of the logged-in account.
 	 *
-	 * @var int
+	 * @var int $channel_id
 	 */
 	public $channel_id = 0;
 	/**
-	 * channel_hash of the current channel of the logged-in account.
+	 * @brief channel_hash of the current channel of the logged-in account.
 	 *
-	 * @var string
+	 * @var string $channel_hash
 	 */
 	public $channel_hash = '';
 	/**
-	 * Set in mod/cloud.php to observer_hash.
+	 * @brief Set in mod/cloud.php to observer_hash.
 	 *
-	 * @var string
+	 * @var string $observer
 	 */
 	public $observer = '';
 	/**
 	 *
 	 * @see Browser::set_writeable()
-	 * @var \Sabre\DAV\Browser\Plugin
+	 * @var \\Sabre\\DAV\\Browser\\Plugin $browser
 	 */
 	public $browser;
 	/**
-	 * channel_id of the current visited path. Set in Directory::getDir().
+	 * @brief channel_id of the current visited path. Set in Directory::getDir().
 	 *
-	 * @var int
+	 * @var int $owner_id
 	 */
 	public $owner_id = 0;
 	/**
@@ -62,15 +62,15 @@ class BasicAuth extends DAV\Auth\Backend\AbstractBasic {
 	 *
 	 * Used for creating the path in cloud/
 	 *
-	 * @var string
+	 * @var string $owner_nick
 	 */
 	public $owner_nick = '';
 	/**
 	 * Timezone from the visiting channel's channel_timezone.
 	 *
-	 * Used in @ref RedBrowser
+	 * Used in @ref Browser
 	 *
-	 * @var string
+	 * @var string $timezone
 	 */
 	protected $timezone = '';
 
@@ -82,7 +82,7 @@ class BasicAuth extends DAV\Auth\Backend\AbstractBasic {
 	 * @brief Validates a username and password.
 	 *
 	 *
-	 * @see \Sabre\DAV\Auth\Backend\AbstractBasic::validateUserPass
+	 * @see \\Sabre\\DAV\\Auth\\Backend\\AbstractBasic::validateUserPass
 	 * @param string $username
 	 * @param string $password
 	 * @return bool
@@ -211,7 +211,7 @@ class BasicAuth extends DAV\Auth\Backend\AbstractBasic {
 	 *
 	 * If nobody is currently logged in, this method should return null.
 	 *
-	 * @see \Sabre\DAV\Auth\Backend\AbstractBasic::getCurrentUser
+	 * @see \\Sabre\\DAV\\Auth\\Backend\\AbstractBasic::getCurrentUser
 	 * @return string|null
 	 */
 	public function getCurrentUser() {

Zotlabs/Storage/Browser.php

@@ -7,10 +7,10 @@ use Sabre\DAV;
 /**
  * @brief Provides a DAV frontend for the webbrowser.
  *
- * RedBrowser is a SabreDAV server-plugin to provide a view to the DAV storage
+ * Browser is a SabreDAV server-plugin to provide a view to the DAV storage
  * for the webbrowser.
  *
- * @extends \Sabre\DAV\Browser\Plugin
+ * @extends \\Sabre\\DAV\\Browser\\Plugin
  *
  * @link http://github.com/friendica/red
  * @license http://opensource.org/licenses/mit-license.php The MIT License (MIT)
@@ -19,13 +19,13 @@ class Browser extends DAV\Browser\Plugin {
 
 	/**
 	 * @see set_writeable()
-	 * @see \Sabre\DAV\Auth\Backend\BackendInterface
+	 * @see \\Sabre\\DAV\\Auth\\Backend\\BackendInterface
-	 * @var RedBasicAuth
+	 * @var BasicAuth $auth
 	 */
 	private $auth;
 
 	/**
-	 * @brief Constructor for RedBrowser class.
+	 * @brief Constructor for Browser class.
 	 *
 	 * $enablePost will be activated through set_writeable() in a later stage.
 	 * At the moment the write_storage permission is only valid for the whole
@@ -36,7 +36,7 @@ class Browser extends DAV\Browser\Plugin {
 	 * Disable assets with $enableAssets = false. Should get some thumbnail views
 	 * anyway.
 	 *
-	 * @param RedBasicAuth &$auth
+	 * @param BasicAuth &$auth
 	 */
 	public function __construct(&$auth) {
 		$this->auth = $auth;
@@ -95,7 +95,6 @@ class Browser extends DAV\Browser\Plugin {
 			'{DAV:}getlastmodified',
 			), 1);
 
-
 		$parent = $this->server->tree->getNodeForPath($path);
 
 		$parentpath = array();
@@ -263,7 +262,8 @@ class Browser extends DAV\Browser\Plugin {
 	 * @brief Creates a form to add new folders and upload files.
 	 *
 	 * @param \Sabre\DAV\INode $node
-	 * @param string &$output
+	 * @param[in,out] string &$output
+	 * @param string $path
 	 */
 	public function htmlActionsPanel(DAV\INode $node, &$output, $path) {
 		if(! $node instanceof DAV\ICollection)
@@ -355,7 +355,7 @@ class Browser extends DAV\Browser\Plugin {
 	 *
 	 * @param int $owner
 	 *  The owner_id
-	 * @param string $hash
+	 * @param string $parentHash
 	 *  The parent's folder hash
 	 * @param string $attachName
 	 *  The name of the attachment
@@ -373,6 +373,7 @@ class Browser extends DAV\Browser\Plugin {
 				$hash = $rr['hash'];
 			}
 		}
+
 		return $hash;
 	}
 

Zotlabs/Storage/Directory.php

@@ -9,9 +9,9 @@ use Sabre\DAV;
  *
  * A class that represents a directory.
  *
- * @extends \Sabre\DAV\Node
+ * @extends \\Sabre\\DAV\\Node
- * @implements \Sabre\DAV\ICollection
+ * @implements \\Sabre\\DAV\\ICollection
- * @implements \Sabre\DAV\IQuota
+ * @implements \\Sabre\\DAV\\IQuota
  *
  * @link http://github.com/friendica/red
  * @license http://opensource.org/licenses/mit-license.php The MIT License (MIT)
@@ -21,7 +21,7 @@ class Directory extends DAV\Node implements DAV\ICollection, DAV\IQuota {
 	/**
 	 * @brief The path inside /cloud
 	 *
-	 * @var string
+	 * @var string $red_path
 	 */
 	private $red_path;
 	private $folder_hash;
@@ -29,7 +29,7 @@ class Directory extends DAV\Node implements DAV\ICollection, DAV\IQuota {
 	 * @brief The full path as seen in the browser.
 	 * /cloud + $red_path
 	 * @todo I think this is not used anywhere, we always strip '/cloud' and only use it in debug
-	 * @var string
+	 * @var string $ext_path
 	 */
 	private $ext_path;
 	private $root_dir = '';
@@ -38,7 +38,7 @@ class Directory extends DAV\Node implements DAV\ICollection, DAV\IQuota {
 	 * @brief The real path on the filesystem.
 	 * The actual path in store/ with the hashed names.
 	 *
-	 * @var string
+	 * @var string $os_path
 	 */
 	private $os_path = '';
 
@@ -46,7 +46,7 @@ class Directory extends DAV\Node implements DAV\ICollection, DAV\IQuota {
 	 * @brief Sets up the directory node, expects a full path.
 	 *
 	 * @param string $ext_path a full path
-	 * @param RedBasicAuth &$auth_plugin
+	 * @param BasicAuth &$auth_plugin
 	 */
 	public function __construct($ext_path, &$auth_plugin) {
 //		$ext_path = urldecode($ext_path);
@@ -76,8 +76,8 @@ class Directory extends DAV\Node implements DAV\ICollection, DAV\IQuota {
 	/**
 	 * @brief Returns an array with all the child nodes.
 	 *
-	 * @throw \Sabre\DAV\Exception\Forbidden
+	 * @throw "\Sabre\DAV\Exception\Forbidden"
-	 * @return array \Sabre\DAV\INode[]
+	 * @return array \\Sabre\\DAV\\INode[]
 	 */
 	public function getChildren() {
 		logger('children for ' . $this->ext_path, LOGGER_DATA);
@@ -98,8 +98,8 @@ class Directory extends DAV\Node implements DAV\ICollection, DAV\IQuota {
 	/**
 	 * @brief Returns a child by name.
 	 *
-	 * @throw \Sabre\DAV\Exception\Forbidden
+	 * @throw "\Sabre\DAV\Exception\Forbidden"
-	 * @throw \Sabre\DAV\Exception\NotFound
+	 * @throw "\Sabre\DAV\Exception\NotFound"
 	 * @param string $name
 	 */
 	public function getChild($name) {
@@ -141,7 +141,7 @@ class Directory extends DAV\Node implements DAV\ICollection, DAV\IQuota {
 	 *
 	 * @todo handle duplicate directory name
 	 *
-	 * @throw \Sabre\DAV\Exception\Forbidden
+	 * @throw "\Sabre\DAV\Exception\Forbidden"
 	 * @param string $name The new name of the directory.
 	 * @return void
 	 */
@@ -186,7 +186,7 @@ class Directory extends DAV\Node implements DAV\ICollection, DAV\IQuota {
 	 * After successful creation of the file, you may choose to return the ETag
 	 * of the new file here.
 	 *
-	 * @throw \Sabre\DAV\Exception\Forbidden
+	 * @throw "\Sabre\DAV\Exception\Forbidden"
 	 * @param string $name Name of the file
 	 * @param resource|string $data Initial payload
 	 * @return null|string ETag
@@ -431,7 +431,7 @@ class Directory extends DAV\Node implements DAV\ICollection, DAV\IQuota {
 	/**
 	 * @todo add description of what this function does.
 	 *
-	 * @throw \Sabre\DAV\Exception\NotFound
+	 * @throw "\Sabre\DAV\Exception\NotFound"
 	 * @return void
 	 */
 	function getDir() {
@@ -557,13 +557,13 @@ class Directory extends DAV\Node implements DAV\ICollection, DAV\IQuota {
 
 
 	/**
-	 * @brief Array with all Directory and File DAV\Node items for the given path.
+	 * @brief Array with all Directory and File DAV\\Node items for the given path.
  	 *
 	 * @param string $file path to a directory
 	 * @param \Zotlabs\Storage\BasicAuth &$auth
-	 * @returns null|array \Sabre\DAV\INode[]
+	 * @returns null|array \\Sabre\\DAV\\INode[]
-	 * @throw \Sabre\DAV\Exception\Forbidden
+	 * @throw "\Sabre\DAV\Exception\Forbidden"
-	 * @throw \Sabre\DAV\Exception\NotFound
+	 * @throw "\Sabre\DAV\Exception\NotFound"
 	 */
 	function CollectionData($file, &$auth) {
 		$ret = array();
@@ -710,7 +710,7 @@ class Directory extends DAV\Node implements DAV\ICollection, DAV\IQuota {
 	 * @param BasicAuth &$auth
 	 * @param boolean $test (optional) enable test mode
 	 * @return File|Directory|boolean|null
-	 * @throw \Sabre\DAV\Exception\Forbidden
+	 * @throw "\Sabre\DAV\Exception\Forbidden"
 	 */
 	function FileData($file, &$auth, $test = false) {
 		logger($file . (($test) ? ' (test mode) ' : ''), LOGGER_DATA);

Zotlabs/Storage/File.php

@@ -9,8 +9,8 @@ use Sabre\DAV;
  *
  * It provides all functions to work with files in Red's cloud through DAV protocol.
  *
- * @extends \Sabre\DAV\Node
+ * @extends \\Sabre\\DAV\\Node
- * @implements \Sabre\DAV\IFile
+ * @implements \\Sabre\\DAV\\IFile
  *
  * @link http://github.com/friendica/red
  * @license http://opensource.org/licenses/mit-license.php The MIT License (MIT)
@@ -20,20 +20,20 @@ class File extends DAV\Node implements DAV\IFile {
 	/**
 	 * The file from attach table.
 	 *
-	 * @var array
+	 * @var array $data
-	 *  data
+	 *  * data
-	 *  flags
+	 *  * flags
-	 *  filename (string)
+	 *  * filename (string)
-	 *  filetype (string)
+	 *  * filetype (string)
 	 */
 	private $data;
 	/**
-	 * @see \Sabre\DAV\Auth\Backend\BackendInterface
+	 * @see \\Sabre\\DAV\\Auth\\Backend\\BackendInterface
-	 * @var \RedMatrix\RedDAV\RedBasicAuth
+	 * @var \\Zotlabs\\Storage\\BasicAuth $auth
 	 */
 	private $auth;
 	/**
-	 * @var string
+	 * @var string $name
 	 */
 	private $name;
 
@@ -65,8 +65,8 @@ class File extends DAV\Node implements DAV\IFile {
 	/**
 	 * @brief Renames the file.
 	 *
-	 * @throw Sabre\DAV\Exception\Forbidden
+	 * @throw "\Sabre\DAV\Exception\Forbidden"
-	 * @param string $name The new name of the file.
+	 * @param string $newName The new name of the file.
 	 * @return void
 	 */
 	public function setName($newName) {
@@ -322,7 +322,7 @@ class File extends DAV\Node implements DAV\IFile {
 	 * This method checks the permissions and then calls attach_delete() function
 	 * to actually remove the file.
 	 *
-	 * @throw \Sabre\DAV\Exception\Forbidden
+	 * @throw "\Sabre\DAV\Exception\Forbidden"
 	 */
 	public function delete() {
 		logger('delete file ' . basename($this->name), LOGGER_DEBUG);

Zotlabs/Web/Router.php

@@ -2,14 +2,6 @@
 
 namespace Zotlabs\Web;
 
-
-class Router {
-
-	private $modname = '';
-	private $controller = null;
-
-	function __construct(&$a) {
-
 /**
  *
  * We have already parsed the server path into App::$argc and App::$argv
@@ -19,9 +11,9 @@ class Router {
  * and use it for handling our URL request to 'https://ourgreatwebsite.something/foo' .
  * The module file contains a few functions that we call in various circumstances
  * and in the following order:
-		 *
+ * @code{.php}
  * Object:
-		 *    class Foo extends Zotlabs\Web\Controller {
+ *    class Foo extends \Zotlabs\Web\Controller {
  *        function init() { init function }
  *        function post() { post function }
  *        function get()  { normal page function }
@@ -31,22 +23,32 @@ class Router {
  *        foo_init()
  *        foo_post() (only called if there are $_POST variables)
  *        foo_content() - the string return of this function contains our page body
-		 *
+ * @endcode
  * Modules which emit other serialisations besides HTML (XML,JSON, etc.) should do
  * so within the module init and/or post functions and then invoke killme() to terminate
  * further processing.
  */
+class Router {
+
+	private $modname = '';
+	private $controller = null;
+
+	/**
+	 * @brief Router constructor
+	 *
+	 * @param[in,out] App &$a
+	 * @throws Exception module not found
+	 */
+	function __construct(&$a) {
 
 		$module = \App::$module;
 		$modname = "Zotlabs\\Module\\" . ucfirst($module);
 
 		if(strlen($module)) {
 
-			/**
+			/*
-			 *
 			 * We will always have a module name.
 			 * First see if we have a plugin which is masquerading as a module.
-			 *
 			 */
 
 			if(is_array(\App::$plugins) && in_array($module,\App::$plugins) && file_exists("addon/{$module}/{$module}.php")) {
@@ -66,7 +68,7 @@ class Router {
 				goaway(z_root());
 			}
 
-			/**
+			/*
 			 * If the site has a custom module to over-ride the standard module, use it.
 			 * Otherwise, look for the standard program module
 			 */
@@ -102,7 +104,7 @@ class Router {
 				}
 			}
 
-			/**
+			/*
 			 * This provides a place for plugins to register module handlers which don't otherwise exist
 			 * on the system, or to completely over-ride an existing module.
 			 * If the plugin sets 'installed' to true we won't throw a 404 error for the specified module even if
@@ -117,7 +119,7 @@ class Router {
 				$this->controller = $x['controller'];
 			}
 
-			/**
+			/*
 			 * The URL provided does not resolve to a valid module.
 			 *
 			 * On Dreamhost sites, quite often things go wrong for no apparent reason and they send us to '/internal_error.html'.
@@ -157,7 +159,11 @@ class Router {
 		}
 	}
 
-
+	/**
+	 * @brief
+	 *
+	 * @param[in,out] App &$a
+	 */
 	function Dispatch(&$a) {
 
 		/**
@@ -168,7 +174,7 @@ class Router {
 			\App::$page['page_title'] = \App::$module;
 			$placeholder = '';
 
-			/**
+			/*
 			 * No theme has been specified when calling the module_init functions
 			 * For this reason, please restrict the use of templates to those which
 			 * do not provide any presentation details - as themes will not be able
@@ -187,7 +193,7 @@ class Router {
 				}
 			}
 
-			/**
+			/*
 			 * Do all theme initialisation here before calling any additional module functions.
 			 * The module_init function may have changed the theme.
 			 * Additionally any page with a Comanche template may alter the theme.
@@ -195,7 +201,7 @@ class Router {
 			 */
 
 
-			/**
+			/*
 			 * In case a page has overloaded a module, see if we already have a layout defined
 			 * otherwise, if a PDL file exists for this module, use it
 			 * The member may have also created a customised PDL that's stored in the config
@@ -203,7 +209,7 @@ class Router {
 
 			load_pdl($a);
 
-			/**
+			/*
 		 	 * load current theme info
 		 	 */
 

Zotlabs/Web/SubModule.php

@@ -2,12 +2,17 @@
 
 namespace Zotlabs\Web;
 
-
+/*
+ * @brief
+ *
+ */
 class SubModule {
 
 	private $controller = false;
 
 	/**
+	 * @brief Submodule constructor.
+	 *
 	 * Initiate sub-modules. By default the submodule name is in argv(1), though this is configurable.
 	 * Example: Given a URL path such as /admin/plugins, and the Admin module initiates sub-modules.
 	 * This means we'll look for a class Plugins in Zotlabs/Module/Admin/Plugins.php
@@ -16,9 +21,9 @@ class SubModule {
 	 * **If** you were to provide sub-module support on the photos module, you would probably use
 	 * $whicharg = 2, as photos are typically called with a URL path of /photos/channel_address/submodule_name
 	 * where submodule_name might be something like album or image.
+	 *
+	 * @param int $whicharg
 	 */
-
-
 	function __construct($whicharg = 1) {
 
 		if(argc() < ($whicharg + 1))
@@ -31,13 +36,20 @@ class SubModule {
 		}
 	}
 
+	/**
+	 * @brief
+	 *
+	 * @param string $method
+	 * @return boolean|mixed
+	 */
 	function call($method) {
 		if(! $this->controller)
 			return false;
+
 		if(method_exists($this->controller, $method))
 			return $this->controller->$method();
+
 		return false;
 	}
 
 }
-

Zotlabs/Zot/Finger.php

@@ -2,7 +2,10 @@
 
 namespace Zotlabs\Zot;
 
-
+/**
+ * @brief Finger
+ *
+ */
 class Finger {
 
 	static private $token;
@@ -19,7 +22,6 @@ class Finger {
 	 *
 	 * @return zotinfo array (with 'success' => true) or array('success' => false);
 	 */
-
 	static public function run($webbie, $channel = null, $autofallback = true) {
 
 		$ret = array('success' => false);
@@ -38,6 +40,7 @@ class Finger {
 
 		if ((! $address) || (! $xchan_addr)) {
 			logger('zot_finger: no address :' . $webbie);
+
 			return $ret;
 		}
 
@@ -59,10 +62,10 @@ class Finger {
 			if($r[0]['hubloc_network'] && $r[0]['hubloc_network'] !== 'zot') {
 				logger('zot_finger: alternate network: ' . $webbie);
 				logger('url: '.$url.', net: '.var_export($r[0]['hubloc_network'], true), LOGGER_DATA, LOG_DEBUG);
+
 				return $ret;
 			}
-		} 
+		} else {
-		else {
 			$url = 'https://' . $host;
 		}
 
@@ -88,8 +91,7 @@ class Finger {
 					$result = z_post_url('http://' . $host . $rhs,$postvars);
 				}
 			}
-		} 
+		} else {
-		else {
 			$rhs .= '?f=&address=' . urlencode($address) . '&token=' . self::$token;
 
 			$result =  z_fetch_url($url . $rhs);
@@ -103,6 +105,7 @@ class Finger {
 
 		if(! $result['success']) {
 			logger('zot_finger: no results');
+
 			return $ret;
 		}
 
@@ -113,6 +116,7 @@ class Finger {
 				$valid = rsa_verify('token.' . self::$token, base64url_decode($signed_token), $x['key']);
 				if(! $valid) {
 					logger('invalid signed token: ' . $url . $rhs, LOGGER_NORMAL, LOG_ERR);
+
 					return $ret;
 				}
 			}

include/Import/Importer.php

@@ -5,7 +5,6 @@ namespace Hubzilla\Import;
 /**
  * @brief Class Import
  *
- * @package Hubzilla\Import
  */
 class Import {
 

include/acl_selectors.php

@@ -1,12 +1,19 @@
-<?php /** @file */
+<?php
 /**
+ * @file include/acl_selectors.php
  *
- */
-
-/**
  * @package acl_selectors
  */
 
+/**
+ * @brief
+ *
+ * @param string $selname
+ * @param string $selclass
+ * @param mixed $preselected
+ * @param number $size
+ * @return string
+ */
 function group_select($selname, $selclass, $preselected = false, $size = 4) {
 
 	$o = '';
@@ -40,13 +47,11 @@ function group_select($selname,$selclass,$preselected = false,$size = 4) {
 
 	call_hooks(App::$module . '_post_' . $selname, $o);
 
-
 	return $o;
 }
 
 function contact_select($selname, $selclass, $preselected = false, $size = 4, $privmail = false, $celeb = false, $privatenet = false, $tabindex = null) {
 
-
 	$o = '';
 
 	// When used for private messages, we limit correspondence to mutual DFRN/Friendica friends and the selector
@@ -54,7 +59,7 @@ function contact_select($selname, $selclass, $preselected = false, $size = 4, $p
 
 	$sql_extra = '';
 
-	$tabindex = ($tabindex > 0 ? "tabindex=\"$tabindex\"" : "");
+	$tabindex = ($tabindex > 0 ? 'tabindex="$tabindex"' : '');
 
 	if($privmail)
 		$o .= "<select name=\"$selname\" id=\"$selclass\" class=\"$selclass\" size=\"$size\" $tabindex >\r\n";
@@ -78,7 +83,7 @@ function contact_select($selname, $selclass, $preselected = false, $size = 4, $p
 	if($r) {
 		foreach($r as $rr) {
 			if((is_array($preselected)) && in_array($rr['id'], $preselected))
-				$selected = " selected=\"selected\" ";
+				$selected = ' selected="selected" ';
 			else
 				$selected = '';
 
@@ -86,7 +91,6 @@ function contact_select($selname, $selclass, $preselected = false, $size = 4, $p
 
 			$o .= "<option value=\"{$rr['abook_id']}\" $selected title=\"{$rr['xchan_name']}|{$rr['xchan_url']}\" >$trimmed</option>\r\n";
 		}
-	
 	}
 
 	$o .= "</select>\r\n";
@@ -104,7 +108,7 @@ function fixacl(&$item) {
 /**
 * Builds a modal dialog for editing permissions, using acl_selector.tpl as the template.
 *
-* @param array   $default Optional access control list for the initial state of the dialog.
+* @param array   $defaults Optional access control list for the initial state of the dialog.
 * @param boolean $show_jotnets Whether plugins for federated networks should be included in the permissions dialog
 * @param PermissionDescription $emptyACL_description - An optional description for the permission implied by selecting an empty ACL. Preferably an instance of PermissionDescription.
 * @param string  $dialog_description Optional message to include at the top of the dialog. E.g. "Warning: Post permissions cannot be changed once sent".
@@ -127,7 +131,6 @@ function populate_acl($defaults = null,$show_jotnets = true, $emptyACL_descripti
 		$showall_caption = $emptyACL_description->get_permission_description();
 		$showall_origin  = (($role === 'custom') ? $emptyACL_description->get_permission_origin_description() : '');
 		$showall_icon    = $emptyACL_description->get_permission_icon();
-
 	} else {
 		// For backwards compatibility we still accept a string... for now!
 		$showall_caption = $emptyACL_description;
@@ -169,9 +172,9 @@ function populate_acl($defaults = null,$show_jotnets = true, $emptyACL_descripti
 		'$select_label'    => t('Who can see this?'),
 		'$custom'          => t('Custom selection'),
 		'$showlimitedDesc' => t('Select "Show" to allow viewing. "Don\'t show" lets you override and limit the scope of "Show".'),
-		'$show'	           => t("Show"),
+		'$show'	           => t('Show'),
 		'$hide'	           => t("Don't show"),
-		'$search'          => t("Search"),
+		'$search'          => t('Search'),
 		'$allowcid'        => json_encode($allow_cid),
 		'$allowgid'        => json_encode($allow_gid),
 		'$denycid'         => json_encode($deny_cid),
@@ -183,7 +186,6 @@ function populate_acl($defaults = null,$show_jotnets = true, $emptyACL_descripti
 	));
 
 	return $o;
-
 }
 
 /**
@@ -212,4 +214,3 @@ function get_post_aclDialogDescription() {
 
 	return sprintf($description, $emphasisOpen, $emphasisClose);
 }
-

include/attach.php

@@ -159,7 +159,6 @@ function attach_count_files($channel_id, $observer, $hash = '', $filename = '',
 		intval($channel_id)
 	);
 
-
 	$ret['success'] = ((is_array($r)) ? true : false);
 	$ret['results'] = ((is_array($r)) ? count($r) : false);
 
@@ -226,7 +225,8 @@ function attach_list_files($channel_id, $observer, $hash = '', $filename = '', $
  * This could exhaust memory so most useful only when immediately sending the data.
  *
  * @param string $hash
- * @param int $rev Revision
+ * @param string $observer_hash
+ * @param int $rev (optional) Revision default 0
  * @return array
  */
 function attach_by_hash($hash, $observer_hash, $rev = 0) {
@@ -295,9 +295,10 @@ function attach_can_view_folder($uid,$ob_hash,$folder_hash) {
 		);
 		if(! $r)
 			return false;
+
 		$hash = $r[0]['folder'];
-	}
+	} while($hash);
-	while($hash);
+
 	return true;
 }
 
@@ -308,8 +309,9 @@ function attach_can_view_folder($uid,$ob_hash,$folder_hash) {
  * Returns the entire attach structure excluding data.
  *
  * @see attach_by_hash()
- * @param $hash
+ * @param string $hash
- * @param $rev revision default 0
+ * @param string $observer_hash
+ * @param int $rev (optional) revision default 0
  * @return associative array with everything except data
  *  * \e boolean \b success boolean true or false
  *  * \e string \b message (optional) only when success is false
@@ -362,7 +364,6 @@ function attach_by_hash_nodata($hash, $observer_hash, $rev = 0) {
 		}
 	}
 
-
 	$ret['success'] = true;
 	$ret['data'] = $r[0];
 
@@ -378,14 +379,7 @@ function attach_by_hash_nodata($hash, $observer_hash, $rev = 0) {
  * @note Requires an input field \e userfile and does not accept multiple files
  * in one request.
  *
- * @param array $channel channel array of owner
+ * @note A lot going on in this function, and some of it is old cruft and some is new cruft
- * @param string $observer_hash hash of current observer
- * @param string $options (optional) one of update, replace, revision
- * @param array $arr (optional) associative array
- */
-
-/**
- * A lot going on in this function, and some of it is old cruft and some is new cruft
  * and the entire thing probably needs to be refactored. It started out just storing
  * files, before we had DAV. It was made extensible to do extra stuff like edit an
  * existing file or optionally store a separate revision using $options to choose between different
@@ -404,8 +398,13 @@ function attach_by_hash_nodata($hash, $observer_hash, $rev = 0) {
  * That's where it sits currently. I repeat it needs to be refactored, and this note is here
  * for future explorers and those who may be doing that work to understand where it came
  * from and got to be the monstrosity of tangled unrelated code that it currently is.
+ *
+ * @param array $channel channel array of owner
+ * @param string $observer_hash hash of current observer
+ * @param string $options (optional) one of update, replace, revision
+ * @param array $arr (optional) associative array
+ * @return void|array
  */
-
 function attach_store($channel, $observer_hash, $options = '', $arr = null) {
 
 	require_once('include/photos.php');
@@ -493,9 +492,7 @@ function attach_store($channel, $observer_hash, $options = '', $arr = null) {
 			$filename = $f['filename'];
 			$filesize = $f['filesize'];
 			$type     = $f['type'];
-
 		} else {
-
 			if(! x($_FILES,'userfile')) {
 				$ret['message'] = t('No source file.');
 				return $ret;
@@ -543,8 +540,6 @@ function attach_store($channel, $observer_hash, $options = '', $arr = null) {
 		$hash = $x[0]['hash'];
 	}
 
-
-
 	$def_extension = '';
 	$is_photo = 0;
 	$gis = @getimagesize($src);
@@ -557,7 +552,6 @@ function attach_store($channel, $observer_hash, $options = '', $arr = null) {
 			$def_extension =  '.jpg';
 		if($gis[2] === IMAGETYPE_PNG)
 			$def_extension =  '.png';
-
 	}
 
 	$pathname = '';
@@ -654,8 +648,7 @@ function attach_store($channel, $observer_hash, $options = '', $arr = null) {
 						}
 						if($found)
 							$x++;
-					}			
+					} while($found);
-					while($found);
 					$filename = $basename . '(' . $x . ')' . $ext;
 				}
 				else
@@ -783,7 +776,6 @@ function attach_store($channel, $observer_hash, $options = '', $arr = null) {
 		);
 	}
 	else {
-
 		$r = q("INSERT INTO attach ( aid, uid, hash, creator, filename, filetype, folder, filesize, revision, os_storage, is_photo, content, created, edited, os_path, allow_cid, allow_gid,deny_cid, deny_gid )
 			VALUES ( %d, %d, '%s', '%s', '%s', '%s', '%s', %d, %d, %d, %d, '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s' ) ",
 			intval($channel['channel_account_id']),
@@ -869,7 +861,6 @@ function attach_store($channel, $observer_hash, $options = '', $arr = null) {
 		return $ret;
 	}
 
-
 	$ret['success'] = true;
 	$ret['data'] = $r[0];
 	if(! $is_photo) {
@@ -1178,25 +1169,21 @@ function attach_mkdirp($channel, $observer_hash, $arr = null) {
 	}
 
 	return $ret;
-
 }
 
 
 
-
-
-
-
 /**
  * @brief Changes permissions of a file.
  *
- * @param int $channel_id
+ * @param int $channel_id The id of the channel
  * @param array $resource
  * @param string $allow_cid
  * @param string $allow_gid
  * @param string $deny_cid
  * @param string $deny_gid
  * @param boolean $recurse (optional) default false
+ * @param boolean $sync (optional) default false
  */
 function attach_change_permissions($channel_id, $resource, $allow_cid, $allow_gid, $deny_cid, $deny_gid, $recurse = false, $sync = false) {
 
@@ -1263,6 +1250,7 @@ function attach_change_permissions($channel_id, $resource, $allow_cid, $allow_gi
  *  The id of the channel
  * @param string $resource
  *  The hash to delete
+ * @param int $is_photo (optional) default 0
  * @return void
  */
 function attach_delete($channel_id, $resource, $is_photo = 0) {
@@ -1425,6 +1413,7 @@ function get_parent_cloudpath($channel_id, $channel_name, $attachHash) {
 			$parentFullPath = $parentName . '/' . $parentFullPath;
 		}
 	} while ($parentHash);
+
 	$parentFullPath = z_root() . '/cloud/' . $channel_name . '/' . $parentFullPath;
 
 	return $parentFullPath;
@@ -1437,11 +1426,14 @@ function get_parent_cloudpath($channel_id, $channel_name, $attachHash) {
  *  The id of the channel
  * @param string $attachHash
  *  The hash of the attachment
+ * @param boolean $recurse
+ *  (optional) default false
  * @return string
  */
 function find_folder_hash_by_attach_hash($channel_id, $attachHash, $recurse = false) {
 
 	logger('attach_hash: ' . $attachHash);
+
 	$r = q("SELECT folder FROM attach WHERE uid = %d AND hash = '%s' LIMIT 1",
 		intval($channel_id),
 		dbesc($attachHash)
@@ -1453,6 +1445,7 @@ logger('attach_hash: ' . $attachHash);
 		else
 			$hash = $r[0]['folder'];
 	}
+
 	return $hash;
 }
 
@@ -1732,11 +1725,11 @@ function get_file_activity_object($channel_id, $hash, $cloudpath) {
 /**
  * @brief Returns array of channels which have recursive permission for a file
  *
- * @param $arr_allow_cid
+ * @param array $arr_allow_cid
- * @param $arr_allow_gid
+ * @param array $arr_allow_gid
- * @param $arr_deny_cid
+ * @param array $arr_deny_cid
- * @param $arr_deny_gid
+ * @param array $arr_deny_gid
- * @param $folder_hash
+ * @param string $folder_hash
  */
 function recursive_activity_recipients($arr_allow_cid, $arr_allow_gid, $arr_deny_cid, $arr_deny_gid, $folder_hash) {
 
@@ -1931,25 +1924,28 @@ function attach_export_data($channel, $resource_id, $deleted = false) {
 	}
 
 	return $ret;
-
 }
 
 
-/* strip off 'store/nickname/' from the provided path */
+/**
-
+ * @brief Strip off 'store/nickname/' from the provided path
+ *
+ * @param string $s
+ * @return string
+ */
 function get_attach_binname($s) {
 	$p = $s;
 	if(strpos($s, 'store/') === 0) {
 		$p = substr($s, 6);
 		$p = substr($p, strpos($p, '/')+1);
 	}
+
 	return $p;
 }
 
 
 function get_dirpath_by_cloudpath($channel, $path) {
 
-
 	$path = notags(trim($path));
 
 	$h = @parse_url($path);
@@ -1998,8 +1994,6 @@ function get_dirpath_by_cloudpath($channel, $path) {
 	} else {
 		return $clouddir . $subdir;
 	}
-	
-	
 }
 
 function get_filename_by_cloudname($cloudname, $channel, $storepath) {
@@ -2013,10 +2007,16 @@ function get_filename_by_cloudname($cloudname, $channel, $storepath) {
 	return null;
 }
 
-
+/**
-// recursively copy a directory into cloud files
+ * @brief recursively copy a directory into cloud files
-function copy_folder_to_cloudfiles($channel, $observer_hash, $srcpath, $cloudpath)
+ *
-{
+ * @param array $channel
+ * @param string $observer_hash
+ * @param string $srcpath
+ * @param string $cloudpath
+ * @return boolean
+ */
+function copy_folder_to_cloudfiles($channel, $observer_hash, $srcpath, $cloudpath) {
 	if (!is_dir($srcpath) || !is_readable($srcpath)) {
 		logger('Error reading source path: ' . $srcpath, LOGGER_NORMAL);
 		return false;
@@ -2038,14 +2038,13 @@ function copy_folder_to_cloudfiles($channel, $observer_hash, $srcpath, $cloudpat
 				return false;
 			}
 		} elseif(is_file($nodepath) && is_readable($nodepath)) {
-						$x = attach_store($channel, $observer_hash, 'import', 
+			$x = attach_store($channel, $observer_hash, 'import', array(
-												array(
 					'directory' => $cloudpath,
 					'src' => $nodepath,
 					'filename' => $node,
 					'filesize' => @filesize($nodepath),
-														'preserve_original'	=> true)
+					'preserve_original' => true
-												);
+			));
 			if(!$x['success']) {
 				logger('Error copying file: ' . $nodepath, LOGGER_NORMAL);
 				logger('Return value: ' . json_encode($x), LOGGER_NORMAL);
@@ -2060,7 +2059,6 @@ function copy_folder_to_cloudfiles($channel, $observer_hash, $srcpath, $cloudpat
 	return true;
 }
 /**
- * attach_move()
  * This function performs an in place directory-to-directory move of a stored attachment or photo.
  * The data is physically moved in the store/nickname storage location and the paths adjusted
  * in the attach structure (and if applicable the photo table). The new 'album name' is recorded
@@ -2070,8 +2068,12 @@ function copy_folder_to_cloudfiles($channel, $observer_hash, $srcpath, $cloudpat
  * the file is relocated to the root of the channel's storage area.
  *
  * @fixme: this operation is currently not synced to clones !!
+ *
+ * @param int $channel_id
+ * @param int $resource_id
+ * @param string $new_folder_hash
+ * @return void|boolean
  */
-
 function attach_move($channel_id, $resource_id, $new_folder_hash) {
 
 	$c = channelx_by_n($channel_id);
@@ -2094,6 +2096,7 @@ function attach_move($channel_id,$resource_id,$new_folder_hash) {
 		);
 		if(! $n)
 			return;
+
 		$newdirname = $n[0]['filename'];
 		$newstorepath = $n[0]['content'] . '/' . $resource_id;
 	}
@@ -2115,7 +2118,7 @@ function attach_move($channel_id,$resource_id,$new_folder_hash) {
 	if($s) {
 		$overwrite = get_pconfig($channel_id,'system','overwrite_dup_files');
 		if($overwrite) {
-			// @fixme
+			/// @fixme
 			return;
 		}
 		else {
@@ -2179,7 +2182,6 @@ function attach_move($channel_id,$resource_id,$new_folder_hash) {
 	}
 
 	return true;
-
 }
 
 
@@ -2199,6 +2201,7 @@ function attach_folder_select_list($channel_id) {
 				$out[$x[0]] = $x[1];
 		}
 	}
+
 	return $out;
 }
 
@@ -2228,6 +2231,6 @@ function attach_folder_rpaths($all_folders,$that_folder) {
 		}
 		while((! $found) && (! $error) && ($parent_hash != ''));
 	}
-	return (($error) ? false : [ $current_hash , $path ]);
 
+	return (($error) ? false : [ $current_hash , $path ]);
 }

include/channel.php

@@ -578,7 +578,6 @@ function identity_basic_export($channel_id, $items = false) {
 	if($r)
 		$ret['term'] = $r;
 
-
 	// add psuedo-column obj_baseurl to aid in relocations
 
 	$r = q("select obj.*, '%s' as obj_baseurl from obj where obj_channel = %d",
@@ -608,7 +607,6 @@ function identity_basic_export($channel_id, $items = false) {
 	if($r)
 		$ret['chatroom'] = $r;
 
-
 	$r = q("select * from event where uid = %d",
 		intval($channel_id)
 	);
@@ -636,12 +634,10 @@ function identity_basic_export($channel_id, $items = false) {
 		}
 	}
 
-
 	$addon = array('channel_id' => $channel_id,'data' => $ret);
 	call_hooks('identity_basic_export',$addon);
 	$ret = $addon['data'];
 
-
 	if(! $items)
 		return $ret;
 
@@ -663,7 +659,6 @@ function identity_basic_export($channel_id, $items = false) {
 		$ret['conv'] = $r;
 	}
 
-
 	$r = q("select * from mail where mail.uid = %d",
 		intval($channel_id)
 	);
@@ -745,8 +740,16 @@ function identity_export_year($channel_id,$year,$month = 0) {
 	return $ret;
 }
 
-// export items within an arbitrary date range. Date/time is in UTC.
+/**
-
+ * @brief Export items within an arbitrary date range.
+ *
+ * Date/time is in UTC.
+ *
+ * @param int $channel_id The channel ID
+ * @param string $start
+ * @param string $finish
+ * @return array
+ */
 function channel_export_items($channel_id, $start, $finish) {
 
 	if(! $start)
@@ -866,7 +869,6 @@ function profile_load($nickname, $profile = '') {
 		intval($p[0]['profile_uid'])
 	);
 	if($q) {
-
 		$extra_fields = array();
 
 		require_once('include/channel.php');
@@ -985,7 +987,6 @@ function profile_edit_menu($uid) {
 	}
 
 	return $ret;
-
 }
 
 /**
@@ -997,6 +998,7 @@ function profile_edit_menu($uid) {
  * @param array $profile
  * @param int $block
  * @param boolean $show_connect
+ * @param mixed $zcard
  *
  * @return HTML string suitable for sidebar inclusion
  * Exceptions: Returns empty string if passed $profile is wrong type or not populated
@@ -1163,7 +1165,6 @@ function advanced_profile(&$a) {
 		}
 
 
-
 		$tpl = get_markup_template('profile_advanced.tpl');
 
 		$profile = array();
@@ -1403,7 +1404,8 @@ function zid($s,$address = '') {
 	$mine = get_my_url();
 	$myaddr = (($address) ? $address : get_my_address());
 
-	/** @FIXME checking against our own channel url is no longer reliable. We may have a lot
+	/**
+	 * @FIXME checking against our own channel url is no longer reliable. We may have a lot
 	 * of urls attached to out channel. Should probably match against our site, since we
 	 * will not need to remote authenticate on our own site anyway.
 	 */
@@ -1638,13 +1640,13 @@ function notifications_on($channel_id,$value) {
 		intval($value),
 		intval($channel_id)
 	);
+
 	return $x;
 }
 
 
 function get_channel_default_perms($uid) {
 
-
 	$ret = [];
 
 	$r = q("select abook_xchan from abook where abook_channel = %d and abook_self = 1 limit 1",
@@ -1666,7 +1668,6 @@ function get_channel_default_perms($uid) {
 
 
 function profiles_build_sync($channel_id) {
-	
 	$r = q("select * from profile where uid = %d",
 		intval($channel_id)
 	);
@@ -1713,7 +1714,6 @@ function auto_channel_create($account_id) {
 	$arr['nickname'] = check_webbie(array($arr['nickname'], $arr['nickname'] . mt_rand(1000,9999)));
 
 	return create_identity($arr);
-
 }
 
 function get_cover_photo($channel_id,$format = 'bbcode', $res = PHOTO_RES_COVER_1200) {
@@ -1749,9 +1749,16 @@ function get_cover_photo($channel_id,$format = 'bbcode', $res = PHOTO_RES_COVER_
 	}
 
 	return $output;
-		
 }
 
+/**
+ * @brief
+ *
+ * @param array $channel
+ * @param string $observer_hash
+ * @param array $args
+ * @return string
+ */
 function get_zcard($channel, $observer_hash = '', $args = array()) {
 
 	logger('get_zcard');
@@ -1759,7 +1766,6 @@ function get_zcard($channel,$observer_hash = '',$args = array()) {
 	$maxwidth = (($args['width']) ? intval($args['width']) : 0);
 	$maxheight = (($args['height']) ? intval($args['height']) : 0);
 
-
 	if(($maxwidth > 1200) || ($maxwidth < 1))
 		$maxwidth = 1200;
 
@@ -1768,14 +1774,12 @@ function get_zcard($channel,$observer_hash = '',$args = array()) {
 		$size = 'hz_small';
 		$cover_size = PHOTO_RES_COVER_425;
 		$pphoto = array('mimetype' => $channel['xchan_photo_mimetype'], 'width' => 80 , 'height' => 80, 'href' => $channel['xchan_photo_m']);
-	}
+	} elseif($maxwidth <= 900) {
-	elseif($maxwidth <= 900) {
 		$width = 900;
 		$size = 'hz_medium';
 		$cover_size = PHOTO_RES_COVER_850;
 		$pphoto = array('mimetype' => $channel['xchan_photo_mimetype'], 'width' => 160 , 'height' => 160, 'href' => $channel['xchan_photo_l']);
-	}
+	} elseif($maxwidth <= 1200) {
-	elseif($maxwidth <= 1200) {
 		$width = 1200;
 		$size = 'hz_large';
 		$cover_size = PHOTO_RES_COVER_1200;
@@ -1785,7 +1789,6 @@ function get_zcard($channel,$observer_hash = '',$args = array()) {
 //	$scale = (float) $maxwidth / $width;
 //	$translate = intval(($scale / 1.0) * 100);
 
-
 	$channel['channel_addr'] = channel_reddress($channel);
 	$zcard = array('chan' => $channel);
 
@@ -1798,8 +1801,7 @@ function get_zcard($channel,$observer_hash = '',$args = array()) {
 	if($r) {
 		$cover = $r[0];
 		$cover['href'] = z_root() . '/photo/' . $r[0]['resource_id'] . '-' . $r[0]['imgscale'];
-	}		
+	} else {
-	else {
 		$cover = $pphoto;
 	}
 
@@ -1814,7 +1816,6 @@ function get_zcard($channel,$observer_hash = '',$args = array()) {
 	));
 
 	return $o;
-		
 }
 
 
@@ -1825,7 +1826,6 @@ function get_zcard_embed($channel,$observer_hash = '',$args = array()) {
 	$maxwidth = (($args['width']) ? intval($args['width']) : 0);
 	$maxheight = (($args['height']) ? intval($args['height']) : 0);
 
-
 	if(($maxwidth > 1200) || ($maxwidth < 1))
 		$maxwidth = 1200;
 
@@ -1860,8 +1860,7 @@ function get_zcard_embed($channel,$observer_hash = '',$args = array()) {
 	if($r) {
 		$cover = $r[0];
 		$cover['href'] = z_root() . '/photo/' . $r[0]['resource_id'] . '-' . $r[0]['imgscale'];
-	}		
+	} else {
-	else {
 		$cover = $pphoto;
 	}
 
@@ -1876,33 +1875,59 @@ function get_zcard_embed($channel,$observer_hash = '',$args = array()) {
 	));
 
 	return $o;
-		
 }
 
-
+/**
+ * @brief
+ *
+ * @param string $nick
+ * @return mixed
+ */
 function channelx_by_nick($nick) {
 	$r = q("SELECT * FROM channel left join xchan on channel_hash = xchan_hash WHERE channel_address = '%s'  and channel_removed = 0 LIMIT 1",
 		dbesc($nick)
 	);
+
 	return(($r) ? $r[0] : false);
 }
 
+/**
+ * @brief
+ *
+ * @param string $hash
+ * @return mixed
+ */
 function channelx_by_hash($hash) {
 	$r = q("SELECT * FROM channel left join xchan on channel_hash = xchan_hash WHERE channel_hash = '%s' and channel_removed = 0 LIMIT 1",
 		dbesc($hash)
 	);
+
 	return(($r) ? $r[0] : false);
 }
 
+/**
+ * @brief
+ *
+ * @param int $id
+ * @return mixed
+ */
 function channelx_by_n($id) {
 	$r = q("SELECT * FROM channel left join xchan on channel_hash = xchan_hash WHERE channel_id = %d and channel_removed = 0 LIMIT 1",
 		dbesc($id)
 	);
+
 	return(($r) ? $r[0] : false);
 }
 
+/**
+ * @brief
+ *
+ * @param string $channel
+ * @return string
+ */
 function channel_reddress($channel) {
 	if(! ($channel && array_key_exists('channel_address', $channel)))
 		return '';
+
 	return strtolower($channel['channel_address'] . '@' . App::get_hostname());
 }

include/config.php

@@ -1,5 +1,4 @@
 <?php
-
 /**
  * @file include/config.php
  * @brief Arbitrary configuration storage.
@@ -7,7 +6,6 @@
  * Arrays get stored as serialized strings.
  * Booleans are stored as integer 0/1.
  *
-
  * - <b>config</b> is used for hub specific configurations. It overrides the
  * configurations from .htconfig file. The storage is of size TEXT.
  * - <b>pconfig</b> is used for channel specific configurations and takes a

include/datetime.php

@@ -195,7 +195,7 @@ function timesel($format, $h, $m, $id='timepicker') {
 /**
  * @brief Returns a datetime selector.
  *
- * @param $format
+ * @param string $format
  *  format string, e.g. 'ymd' or 'mdy'. Not currently supported
  * @param $min
  *  unix timestamp of minimum date
@@ -203,6 +203,7 @@ function timesel($format, $h, $m, $id='timepicker') {
  *  unix timestap of maximum date
  * @param $default
  *  unix timestamp of default date
+ * @param string $label
  * @param string $id
  *  id and name of datetimepicker (defaults to "datetimepicker")
  * @param boolean $pickdate
@@ -214,6 +215,7 @@ function timesel($format, $h, $m, $id='timepicker') {
  * @param $maxfrom
  *  set maximum date from picker with id $maxfrom (none by default)
  * @param boolean $required default false
+ * @param int $first_day (optional) default 0
  * @return string Parsed HTML output.
  *
  * @todo Once browser support is better this could probably be replaced with

include/help.php

@@ -1,5 +1,11 @@
 <?php
 
+/**
+ * @brief
+ *
+ * @param string $tocpath
+ * @return string|unknown
+ */
 function get_help_content($tocpath = false) {
 
 	global $lang;
@@ -78,8 +84,8 @@ function get_help_content($tocpath = false) {
 	}
 
 	$content = preg_replace_callback("/#include (.*?)\;/ism", 'preg_callback_help_include', $content);
-	return translate_projectname($content);
 
+	return translate_projectname($content);
 }
 
 function preg_callback_help_include($matches) {
@@ -125,6 +131,12 @@ function find_doc_file($s) {
 	return '';
 }
 
+/**
+ * @brief
+ *
+ * @param string $s
+ * @return number|mixed|unknown|boolean
+ */
 function search_doc_files($s) {
 
 	$itemspage = get_pconfig(local_channel(),'system','itemspage');
@@ -168,6 +180,7 @@ function search_doc_files($s) {
 
 	}
 	usort($r,'doc_rank_sort');
+
 	return $r;
 }
 
@@ -175,10 +188,15 @@ function search_doc_files($s) {
 function doc_rank_sort($s1, $s2) {
 	if($s1['rank'] == $s2['rank'])
 		return 0;
+
 	return (($s1['rank'] < $s2['rank']) ? 1 : (-1));
 }
 
-
+/**
+ * @brief
+ *
+ * @return string
+ */
 function load_context_help() {
 
 	$path = App::$cmd;
@@ -196,6 +214,7 @@ function load_context_help() {
 		}
 		if($context_help)
 			break;
+
 		array_pop($args);
 		$path = implode($args,'/');
 	}
@@ -203,7 +222,12 @@ function load_context_help() {
 	return $context_help;
 }
 
-
+/**
+ * @brief
+ *
+ * @param string $s
+ * @return void|boolean[]|number[]|string[]|unknown[]
+ */
 function store_doc_file($s) {
 
 	if(is_dir($s))
@@ -215,7 +239,6 @@ function store_doc_file($s) {
 	$item['aid'] = 0;
 	$item['uid'] = $sys['channel_id'];
 
-
 	if(strpos($s, '.md'))
 		$mimetype = 'text/markdown';
 	elseif(strpos($s, '.html'))
@@ -252,6 +275,4 @@ function store_doc_file($s) {
 	}
 
 	return $x;
-
 }
-

include/items.php

@@ -3,9 +3,6 @@
  * @file include/items.php
  */
 
-// uncertain if this line is needed and why
-use Sabre\HTTP\URLUtil;
-
 use Zotlabs\Lib as Zlib;
 
 require_once('include/bbcode.php');
@@ -66,6 +63,7 @@ function collect_recipients($item, &$private_envelope) {
 
 		if($recipients && $deny)
 			$recipients = array_diff($recipients,$deny);
+
 		$private_envelope = true;
 	}
 	else {
@@ -132,7 +130,6 @@ function collect_recipients($item, &$private_envelope) {
 			}
 		}
 
-
 	}
 
 	// This is a somewhat expensive operation but important.
@@ -184,8 +181,8 @@ function item_normal() {
  * This is a compatibility function primarily for plugins, because
  * in earlier DB schemas this was a much simpler single integer compare
  *
+ * @param array $item
  */
-
 function is_item_normal($item) {
 
 	if(intval($item['item_hidden']) || intval($item['item_type']) || intval($item['item_deleted'])
@@ -194,7 +191,6 @@ function is_item_normal($item) {
 		return false;
 
 	return true;
-
 }
 
 /**
@@ -495,10 +491,6 @@ function validate_item_elements($message,$arr) {
 }
 
 
-
-
-
-
 /**
  * @brief Limit lenght on imported system messages.
  *
@@ -652,7 +644,6 @@ function get_item_elements($x,$allow_code = false) {
 	if(mb_strlen($arr['title']) > 255)
 		$arr['title'] = mb_substr($arr['title'],0,255);
 
-
 	$arr['app']          = (($x['app'])            ? htmlspecialchars($x['app'],            ENT_COMPAT,'UTF-8',false) : '');
 	$arr['route']        = (($x['route'])          ? htmlspecialchars($x['route'],          ENT_COMPAT,'UTF-8',false) : '');
 	$arr['mid']          = (($x['message_id'])     ? htmlspecialchars($x['message_id'],     ENT_COMPAT,'UTF-8',false) : '');
@@ -1057,7 +1048,6 @@ function encode_item($item,$mirror = false) {
 		$x['item_blocked'] = $item['item_blocked'];
 	}
 
-
 	$x['message_id']      = $item['mid'];
 	$x['message_top']     = $item['parent_mid'];
 	$x['message_parent']  = $item['thr_parent'];
@@ -1078,9 +1068,9 @@ function encode_item($item,$mirror = false) {
 	$x['longlat']         = $item['coord'];
 	$x['signature']       = $item['sig'];
 	$x['route']           = $item['route'];
-
 	$x['owner']           = encode_item_xchan($item['owner']);
 	$x['author']          = encode_item_xchan($item['author']);
+
 	if($item['obj'])
 		$x['object']      = json_decode($item['obj'],true);
 	if($item['target'])
@@ -1530,6 +1520,8 @@ function get_profile_elements($x) {
  *
  * @param array $arr
  * @param boolean $allow_exec (optional) default false
+ * @param boolean $deliver (optional) default true
+ *
  * @return array
  *   * \e boolean \b success
  *   * \e int \b item_id

include/network.php

@@ -30,7 +30,7 @@ function get_capath() {
  *  * \b filep => stream resource to write body to. header and body are not returned when using this option.
  *  * \b custom => custom request method: e.g. 'PUT', 'DELETE'
  *  * \b cookiejar => cookie file (write)
- *  * \B cookiefile => cookie file (read)
+ *  * \b cookiefile => cookie file (read)
  *
  * @return array an associative array with:
  *  * \e int \b return_code => HTTP return code or 0 if timeout or failure

include/photos.php

@@ -443,9 +443,12 @@ function photo_upload($channel, $observer, $args) {
  *
  * @param array $channel
  * @param array $observer
+ * @param array $sort_key (optional) default album
+ * @param array $direction (optional) default asc
+ *
  * @return bool|array false if no view_storage permission or an array
- *   * success (bool)
+ *   * \e boolean \b success
- *   * albums (array)
+ *   * \e array \b albums
  */
 function photos_albums_list($channel, $observer, $sort_key = 'album', $direction = 'asc') {
 
@@ -455,14 +458,11 @@ function photos_albums_list($channel, $observer, $sort_key = 'album', $direction
 	if(! perm_is_allowed($channel_id, $observer_xchan, 'view_storage'))
 		return false;
 
-
 	$sql_extra = permissions_sql($channel_id,$observer_xchan);
 
 	$sort_key = dbesc($sort_key);
 	$direction = dbesc($direction);
 
-
-
 	$albums = q("SELECT count( distinct resource_id ) as total, album from photo where uid = %d and photo_usage IN ( %d, %d ) $sql_extra group by album order by $sort_key $direction",
 		intval($channel_id),
 		intval(PHOTO_NORMAL),

include/plugin.php

@@ -261,6 +261,8 @@ function load_hooks() {
  *     name of hook to attach callback
  * @param string $fn
  *     function name of callback handler
+ * @param int $version (optional) default 0
+ * @param int $priority (optional) default 0
  */
 function insert_hook($hook, $fn, $version = 0, $priority = 0) {
 

include/security.php

@@ -2,11 +2,12 @@
 /**
  * @file include/security.php
  *
- * Some security related functions.
+ * @brief Some security related functions.
  */
 
 /**
  * @param int $user_record The account_id
+ * @param array $channel
  * @param bool $login_initial default false
  * @param bool $interactive default false
  * @param bool $return
@@ -89,15 +90,22 @@ function authenticate_success($user_record, $channel = null, $login_initial = fa
 function atoken_login($atoken) {
 	if(! $atoken)
 		return false;
+
 	$_SESSION['authenticated'] = 1;
 	$_SESSION['visitor_id'] = $atoken['xchan_hash'];
 	$_SESSION['atoken'] = $atoken['atoken_id'];
 
 	\App::set_observer($atoken);
+
 	return true;
 }
 
-
+/**
+ * @brief
+ *
+ * @param array $atoken
+ * @return array|null
+ */
 function atoken_xchan($atoken) {
 
 	$c = channelx_by_n($atoken['atoken_uid']);
@@ -114,9 +122,9 @@ function atoken_xchan($atoken) {
 			'xchan_photo_l' => get_default_profile_photo(300),
 			'xchan_photo_m' => get_default_profile_photo(80),
 			'xchan_photo_s' => get_default_profile_photo(48)
-	
 		];
 	}
+
 	return null;
 }
 
@@ -145,12 +153,16 @@ function atoken_delete($atoken_id) {
 	);
 }
 
-
+/**
-
+ * @brief
-// in order for atoken logins to create content (such as posts) they need a stored xchan.
+ *
-// we'll create one on the first atoken_login; it can't really ever go away but perhaps
+ * In order for atoken logins to create content (such as posts) they need a stored xchan.
-// @fixme we should set xchan_deleted if it's expired or removed 
+ * we'll create one on the first atoken_login; it can't really ever go away but perhaps
-
+ * @fixme we should set xchan_deleted if it's expired or removed
+ *
+ * @param array $xchan
+ * @return void|boolean
+ */
 function atoken_create_xchan($xchan) {
 
 	$r = q("select xchan_hash from xchan where xchan_hash = '%s'",
@@ -202,7 +214,6 @@ function atoken_abook($uid,$xchan_hash) {
 	}
 
 	return false;
-
 }
 
 
@@ -216,8 +227,8 @@ function pseudo_abook($xchan) {
 	$xchan['abook_blocked'] = 0;
 	$xchan['abook_ignored'] = 0;
 	$xchan['abook_pending'] = 0;
-	return $xchan;
 
+	return $xchan;
 }
 
 
@@ -228,7 +239,6 @@ function pseudo_abook($xchan) {
  *
  * @return bool|array false or channel record of the new channel
  */
-
 function change_channel($change_channel) {
 
 	$ret = false;
@@ -275,7 +285,6 @@ function change_channel($change_channel) {
 
 		$arr = [ 'channel_id' => $change_channel, 'chanx' => $ret ];
 		call_hooks('change_channel', $arr);
-
 	}
 
 	return $ret;
@@ -285,11 +294,11 @@ function change_channel($change_channel) {
  * @brief Creates an additional SQL where statement to check permissions.
  *
  * @param int $owner_id
- * @param bool $remote_observer - if unset use current observer
+ * @param bool $remote_observer (optional) use current observer if unset
+ * @param $table (optional)
  *
  * @return string additional SQL where statement
  */
-
 function permissions_sql($owner_id, $remote_observer = null, $table = '') {
 
 	$local_channel = local_channel();
@@ -303,7 +312,6 @@ function permissions_sql($owner_id, $remote_observer = null, $table = '') {
 	if($table)
 		$table .= '.';
 
-
 	$sql = " AND {$table}allow_cid = ''
 			 AND {$table}allow_gid = ''
 			 AND {$table}deny_cid  = ''
@@ -358,7 +366,7 @@ function permissions_sql($owner_id, $remote_observer = null, $table = '') {
  * @brief Creates an addiontal SQL where statement to check permissions for an item.
  *
  * @param int $owner_id
- * @param bool $remote_observer, use current observer if unset
+ * @param bool $remote_observer (optional) use current observer if unset
  *
  * @return string additional SQL where statement
  */

include/text.php

@@ -17,6 +17,7 @@ define('RANDOM_STRING_TEXT', 0x01 );
  * @param string|SmartyEngine $s the string requiring macro substitution,
  *   or an instance of SmartyEngine
  * @param array $r key value pairs (search => replace)
+ *
  * @return string substituted string
  */
 function replace_macros($s, $r) {
@@ -35,6 +36,7 @@ function replace_macros($s, $r) {
  *
  * @param number $size
  * @param int $type
+ *
  * @return string
  */
 function random_string($size = 64, $type = RANDOM_STRING_HEX) {
@@ -60,6 +62,7 @@ function random_string($size = 64, $type = RANDOM_STRING_HEX) {
  * if these are not allowed either.
  *
  * @param string $string Input string
+ *
  * @return string Filtered string
  */
 function notags($string) {
@@ -74,13 +77,13 @@ function notags($string) {
 /**
  * use this on "body" or "content" input where angle chars shouldn't be removed,
  * and allow them to be safely displayed.
+ *
  * @param string $string
+ *
  * @return string
  */
 function escape_tags($string) {
-
 	return(htmlspecialchars($string, ENT_COMPAT, 'UTF-8', false));
-
 }
 
 
@@ -272,14 +275,12 @@ function purify_html($s, $allow_position = false) {
 
 	}
 
-
 	$purifier = new HTMLPurifier($config);
 
 	return $purifier->purify($s);
 }
 
 
-
 /**
  * @brief generate a string that's random, but usually pronounceable.
  *
@@ -376,7 +377,6 @@ function xmlify($str) {
 		btlogger('xmlify called with array: ' . print_r($str,true), LOGGER_NORMAL, LOG_WARNING);
 	}
 
-
 	$len = mb_strlen($str);
 	for($x = 0; $x < $len; $x ++) {
 		$char = mb_substr($str,$x,1);
@@ -412,27 +412,36 @@ function xmlify($str) {
 	return($buffer);
 }
 
-// undo an xmlify
+/**
-// pass xml escaped text ($s), returns unescaped text
+ * @brief Undo an xmlify.
-
+ *
-
+ * Pass xml escaped text ($s), returns unescaped text.
+ *
+ * @param string $s
+ *
+ * @return string
+ */
 function unxmlify($s) {
 	$ret = str_replace('&amp;', '&', $s);
 	$ret = str_replace(array('&lt;', '&gt;', '&quot;', '&apos;'), array('<', '>', '"', "'"), $ret);
+
 	return $ret;
 }
 
-// Automatic pagination.
+/**
-// To use, get the count of total items.
+ * @brief Automatic pagination.
-// Then call App::set_pager_total($number_items);
+ *
-// Optionally call App::set_pager_itemspage($n) to the number of items to display on each page
+ * To use, get the count of total items.
-// Then call paginate($a) after the end of the display loop to insert the pager block on the page
+ * Then call App::set_pager_total($number_items);
-// (assuming there are enough items to paginate).
+ * Optionally call App::set_pager_itemspage($n) to the number of items to display on each page
-// When using with SQL, the setting LIMIT %d, %d => App::$pager['start'],App::$pager['itemspage']
+ * Then call paginate($a) after the end of the display loop to insert the pager block on the page
-// will limit the results to the correct items for the current page. 
+ * (assuming there are enough items to paginate).
-// The actual page handling is then accomplished at the application layer. 
+ * When using with SQL, the setting LIMIT %d, %d => App::$pager['start'],App::$pager['itemspage']
-
+ * will limit the results to the correct items for the current page.
-
+ * The actual page handling is then accomplished at the application layer.
+ *
+ * @param App &$a
+ */
 function paginate(&$a) {
 	$o = '';
 	$stripped = preg_replace('/(&page=[0-9]*)/','',App::$query_string);
@@ -484,6 +493,7 @@ function paginate(&$a) {
 			$o .= '<span class="pager_next">'."<a href=\"$url"."&page=".(App::$pager['page'] + 1).'">' . t('next') . '</a></span>';
 		$o .= '</div>'."\r\n";
 	}
+
 	return $o;
 }
 
@@ -514,7 +524,6 @@ function alt_pager(&$a, $i, $more = '', $less = '') {
 }
 
 
-
 /**
  * @brief Generate a guaranteed unique (for this domain) item ID for ATOM.
  *
@@ -558,17 +567,23 @@ function photo_new_resource() {
 	return $resource;
 }
 
-
+/**
-
+ * @brief
-// for html,xml parsing - let's say you've got
+ *
-// an attribute foobar="class1 class2 class3"
+ * for html,xml parsing - let's say you've got
-// and you want to find out if it contains 'class3'.
+ * an attribute foobar="class1 class2 class3"
-// you can't use a normal sub string search because you
+ * and you want to find out if it contains 'class3'.
-// might match 'notclass3' and a regex to do the job is 
+ * you can't use a normal sub string search because you
-// possible but a bit complicated. 
+ * might match 'notclass3' and a regex to do the job is
-// pass the attribute string as $attr and the attribute you 
+ * possible but a bit complicated.
-// are looking for as $s - returns true if found, otherwise false
+ *
-
+ * pass the attribute string as $attr and the attribute you
+ * are looking for as $s - returns true if found, otherwise false
+ *
+ * @param string $attr attribute string
+ * @param string $s attribute you are looking for
+ * @return boolean true if found
+ */
 function attribute_contains($attr, $s) {
 	$a = explode(' ', $attr);
 	if(count($a) && in_array($s, $a))
@@ -591,10 +606,9 @@ function attribute_contains($attr, $s) {
  * was called, so no need to add it to the message anymore.
  *
  * @param string $msg Message to log
- * @param int $level A log level.
+ * @param int $level A log level
  * @param int $priority - compatible with syslog
  */
-
 function logger($msg, $level = LOGGER_NORMAL, $priority = LOG_INFO) {
 
 	if(App::$module == 'setup' && is_writable('install.log')) {
@@ -630,10 +644,14 @@ function logger($msg, $level = LOGGER_NORMAL, $priority = LOG_INFO) {
 		@file_put_contents($pluginfo['filename'], $pluginfo['message'], FILE_APPEND);
 }
 
-// like logger() but with a function backtrace to pinpoint certain classes
+/**
-// of problems which show up deep in the calling stack
+ * @brief like logger() but with a function backtrace to pinpoint certain classes
-
+ * of problems which show up deep in the calling stack.
-
+ *
+ * @param string $msg Message to log
+ * @param int $level A log level
+ * @param int $priority - compatible with syslog
+ */
 function btlogger($msg, $level = LOGGER_NORMAL, $priority = LOG_INFO) {
 
 	logger($msg, $level, $priority);
@@ -718,15 +736,17 @@ function activity_match($haystack,$needle) {
 	return false;
 }
 
-
+/**
-// Pull out all #hashtags and @person tags from $s;
+ * @brief Pull out all #hashtags and @person tags from $s.
-// We also get @person@domain.com - which would make 
+ *
-// the regex quite complicated as tags can also
+ * We also get @person@domain.com - which would make
-// end a sentence. So we'll run through our results
+ * the regex quite complicated as tags can also
-// and strip the period from any tags which end with one.
+ * end a sentence. So we'll run through our results
-// Returns array of tags found, or empty array.
+ * and strip the period from any tags which end with one.
-
+ *
-
+ * @param string $s
+ * @return Returns array of tags found, or empty array.
+ */
 function get_tags($s) {
 	$ret = array();
 	$match = array();
@@ -824,10 +844,12 @@ function strip_zats($s) {
 	return preg_replace('/[\?&]zat=(.*?)(&|$)/ism','$2',$s);
 }
 
-
+/**
-// quick and dirty quoted_printable encoding
+ * @brief Quick and dirty quoted_printable encoding.
-
+ *
-
+ * @param string $s
+ * @return string
+ */
 function qp($s) {
 	return str_replace ("%", "=", rawurlencode($s));
 }
@@ -1105,8 +1127,11 @@ function get_mood_verbs() {
 	return $arr;
 }
 
-// Function to list all smilies, both internal and from addons
+/**
-// Returns array with keys 'texts' and 'icons'
+ * @brief Function to list all smilies, both internal and from addons.
+ *
+ * @return Returns array with keys 'texts' and 'icons'
+ */
 function list_smilies() {
 
 	$texts =  array(
@@ -1602,7 +1627,9 @@ function prepare_body(&$item,$attach = false) {
  * @brief Given a text string, convert from bbcode to html and add smilie icons.
  *
  * @param string $text
- * @param sting $content_type
+ * @param sting $content_type (optional) default text/bbcode
+ * @param boolean $cache (optional) default false
+ *
  * @return string
  */
 function prepare_text($text, $content_type = 'text/bbcode', $cache = false) {
@@ -1621,7 +1648,6 @@ function prepare_text($text, $content_type = 'text/bbcode', $cache = false) {
 			$s = Markdown($text);
 			break;
 
-
 		case 'application/x-pdl';
 			$s = escape_tags($text);
 			break;
@@ -1735,8 +1761,12 @@ function feed_hublinks() {
 	return $hubxml;
 }
 
-/* return atom link elements for salmon endpoints */
+/**
-
+ * @brief Return atom link elements for salmon endpoints
+ *
+ * @param string $nick
+ * @return string
+ */
 function feed_salmonlinks($nick) {
 
 	$salmon  = '<link rel="salmon" href="' . xmlify(z_root() . '/salmon/' . $nick) . '" />' . "\n" ;
@@ -1886,9 +1916,8 @@ function base64special_decode($s) {
 	return base64_decode(strtr($s,',.','+/'));
 }
 
-
 /**
- * @ Return a div to clear floats.
+ * @brief Return a div to clear floats.
  *
  * @return string
  */
@@ -2087,10 +2116,17 @@ function ids_to_querystr($arr,$idx = 'id') {
 	return(implode(',', $t));
 }
 
-// Fetches xchan and hubloc data for an array of items with only an 
+/**
-// author_xchan and owner_xchan. If $abook is true also include the abook info. 
+ * @brief Fetches xchan and hubloc data for an array of items with only an
-// This is needed in the API to save extra per item lookups there.
+ * author_xchan and owner_xchan.
-
+ *
+ * If $abook is true also include the abook info. This is needed in the API to
+ * save extra per item lookups there.
+ *
+ * @param array[in,out] &$items
+ * @param boolean $abook If true also include the abook info
+ * @param number $effective_uid
+ */
 function xchan_query(&$items, $abook = true, $effective_uid = 0) {
 	$arr = array();
 	if($items && count($items)) {
@@ -2182,15 +2218,19 @@ function magic_link($s) {
 	return $s;
 }
 
-// if $escape is true, dbesc() each element before adding quotes
+/**
-
+ * if $escape is true, dbesc() each element before adding quotes
+ *
+ * @param array[in,out] &$arr
+ * @param boolean $escape default false
+ */
 function stringify_array_elms(&$arr, $escape = false) {
 	for($x = 0; $x < count($arr); $x ++)
 		$arr[$x] = "'" . (($escape) ? dbesc($arr[$x]) : $arr[$x]) . "'";
 }
 
 /**
- * Indents a flat JSON string to make it more human-readable.
+ * @brief Indents a flat JSON string to make it more human-readable.
  *
  * @param string $json The original JSON string to process.
  *
@@ -2249,9 +2289,8 @@ function jindent($json) {
 /**
  * @brief Creates navigation menu for webpage, layout, blocks, menu sites.
  *
- * @return string
+ * @return string with parsed HTML
  */
-
 function design_tools() {
 
 	$channel  = App::get_channel();
@@ -2312,8 +2351,13 @@ function website_portation_tools() {
 	));
 }
 
-/* case insensitive in_array() */
+/**
-
+ * @brief case insensitive in_array()
+ *
+ * @param string $needle
+ * @param array $haystack
+ * @return boolean
+ */
 function in_arrayi($needle, $haystack) {
 	return in_array(strtolower($needle), array_map('strtolower', $haystack));
 }
@@ -2322,10 +2366,13 @@ function normalise_openid($s) {
 	return trim(str_replace(array('http://','https://'),array('',''),$s),'/');
 }
 
-// used in ajax endless scroll request to find out all the args that the master page was viewing.
+/**
-// This was using $_REQUEST, but $_REQUEST also contains all your cookies. So we're restricting it 
+ * Used in ajax endless scroll request to find out all the args that the master page was viewing.
-// to $_GET and $_POST. 
+ * This was using $_REQUEST, but $_REQUEST also contains all your cookies. So we're restricting it
-
+ * to $_GET and $_POST.
+ *
+ * @return string with additional URL parameters
+ */
 function extra_query_args() {
 	$s = '';
 	if(count($_GET)) {
@@ -2344,6 +2391,7 @@ function extra_query_args() {
 			}
 		}
 	}
+
 	return $s;
 }
 
@@ -2841,7 +2889,6 @@ function perms2str($p) {
 	return $ret;
 }
 
-
 /**
  * @brief Turn user/group ACLs stored as angle bracketed text into arrays.
  *
@@ -2869,24 +2916,30 @@ function expand_acl($s) {
 function acl2json($s) {
 	$s = expand_acl($s);
 	$s = json_encode($s);
+
 	return $s;
 }
 
-
+/**
-// When editing a webpage - a dropdown is needed to select a page layout
+ * @brief When editing a webpage - a dropdown is needed to select a page layout
-// On submit, the pdl_select value (which is the mid of an item with item_type = ITEM_TYPE_PDL) is stored in 
+ *
-// the webpage's resource_id, with resource_type 'pdl'.
+ * On submit, the pdl_select value (which is the mid of an item with item_type = ITEM_TYPE_PDL)
-
+ * is stored in the webpage's resource_id, with resource_type 'pdl'.
-// Then when displaying a webpage, we can see if it has a pdl attached. If not we'll 
+ *
-// use the default site/page layout.
+ * Then when displaying a webpage, we can see if it has a pdl attached. If not we'll
-
+ * use the default site/page layout.
-// If it has a pdl we'll load it as we know the mid and pass the body through comanche_parser() which will generate the 
+ *
-// page layout from the given description
+ * If it has a pdl we'll load it as we know the mid and pass the body through comanche_parser() which will generate the
-
+ * page layout from the given description
-// @FIXME - there is apparently a very similar function called layout_select; this one should probably take precedence
+ *
-// and the other should be checked for compatibility and removed
+ * @FIXME - there is apparently a very similar function called layout_select; this one should probably take precedence
-
+ * and the other should be checked for compatibility and removed
-function pdl_selector($uid, $current="") {
+ *
+ * @param int $uid
+ * @param string $current
+ * @return string HTML code for dropdown
+ */
+function pdl_selector($uid, $current='') {
 	$o = '';
 
 	$sql_extra = item_permissions_sql($uid);
@@ -2913,16 +2966,17 @@ function pdl_selector($uid, $current="") {
 	return $o;
 }
 
-/* 
+/**
- * array flatten_array_recursive(array);
+ * @brief returns a one-dimensional array from a multi-dimensional array
- * returns a one-dimensional array from a multi-dimensional array 
  * empty values are discarded
+ *
  * example: print_r(flatten_array_recursive(array('foo','bar',array('baz','blip',array('zob','glob')),'','grip')));
  *
  * Array ( [0] => foo [1] => bar [2] => baz [3] => blip [4] => zob [5] => glob [6] => grip )
  *
+ * @param array $arr multi-dimensional array
+ * @return one-dimensional array
  */
-
 function flatten_array_recursive($arr) {
 	$ret = array();
 
@@ -2940,9 +2994,17 @@ function flatten_array_recursive($arr) {
 			$ret[] = $a;
 		}
 	}
+
 	return($ret);
 }
 
+/**
+ * @brief Highlight Text.
+ *
+ * @param string $s Text to highlight
+ * @param string $lang Which language should be highlighted
+ * @return string
+ */
 function text_highlight($s, $lang) {
 
 	if($lang === 'js')
@@ -2976,7 +3038,6 @@ function text_highlight($s,$lang) {
 			$s = '<?php' . "\n" . $s;
 			$tag_added = true;
 		}
-
 	}
 	$renderer = new Text_Highlighter_Renderer_HTML($options);
 	$hl = Text_Highlighter::factory($lang);
@@ -3007,23 +3068,19 @@ function text_highlight($s,$lang) {
 function arrtoxml($root_elem,$arr) {
 	$xml = new SimpleXMLElement('<?xml version="1.0" encoding="UTF-8"?><' . $root_elem . '></' . $root_elem . '>', null, false);
 	array2XML($xml,$arr);
+
 	return $xml->asXML();
 }
 
-function array2XML($obj, $array)
+function array2XML($obj, $array) {
-{
+	foreach ($array as $key => $value) {
-    foreach ($array as $key => $value)
-    {
 		if(is_numeric($key))
 			$key = 'item' . $key;
 
-        if (is_array($value))
+		if(is_array($value)) {
-        {
 			$node = $obj->addChild($key);
 			array2XML($node, $value);
-        }
+		} else {
-        else
-        {
 			$obj->addChild($key, htmlspecialchars($value));
 		}
 	}
@@ -3043,6 +3100,6 @@ function create_table_from_array($table,$arr) {
 			. "')"
 		);
 	}
-	return $r;
 
+	return $r;
 }

include/widgets.php

@@ -1124,17 +1124,16 @@ return $o;
 
 }
 
-
 /**
- * @function widget_photo($arr)
+ * @brief Widget to display a single photo.
- *    widget to display a single photo.
+ *
- * @param array $arr;
+ * @param array $arr associative array with
- *    'src' => URL of photo
+ *    * \e string \b src URL of photo; URL must be an http or https URL
- *    'zrl' => true or false, use zid in url
+ *    * \e boolean \b zrl use zid in URL
- *    'style' => CSS string
+ *    * \e string \b style CSS string
- * URL must be an http or https URL
+ *
+ * @return string with parsed HTML
  */
-
 function widget_photo($arr) {
 
 	$style = $zrl = false;

include/zot.php

@@ -176,7 +176,7 @@ function zot_zot($url, $data) {
  * @param boolean $autofallback
  *   fallback/failover to http if https connection cannot be established. Default is true.
  *
- * @return array see z_post_url() and \ref mod/zfinger.php
+ * @return array see z_post_url() and \ref Zotlabs::Zot::Finger "\\Zotlabs\\Zot\\Finger"
  */
 function zot_finger($webbie, $channel = null, $autofallback = true) {
 
@@ -571,6 +571,7 @@ function zot_refresh($them, $channel = null, $force = false) {
  *  * \e string \b guid_sig => guid signed with conversant's private key
  *  * \e string \b url => URL of the origination hub of this communication
  *  * \e string \b url_sig => URL signed with conversant's private key
+ * @param boolean $multiple (optional) default false
  *
  * @returns array|null null if site is blacklisted or not found, otherwise an
  *  array with an hubloc record
@@ -1934,9 +1935,11 @@ function remove_community_tag($sender, $arr, $uid) {
  * @brief Just calls item_store_update() and logs result.
  *
  * @see item_store_update()
+ *
  * @param array $sender (unused)
  * @param array $item
- * @param int $uid (unused)
+ * @param array $orig
+ * @param int $uid
  */
 function update_imported_item($sender, $item, $orig, $uid) {
 

util/Doxyfile

@@ -1,8 +1,8 @@
-INPUT = README.md index.php boot.php mod/ include/ util/ view/ version.inc
+INPUT = README.md index.php boot.php include/ install/ util/ view/ Zotlabs/
 RECURSIVE = YES
 PROJECT_NAME = "The Hubzilla"
 PROJECT_LOGO = images/rm-64.png
-EXCLUDE = .htconfig.php library/ doc/ vendor/ .git/ util/zotsh/easywebdav/
+EXCLUDE = .htconfig.php library/ doc/ store/ vendor/ .git/ util/zotsh/easywebdav/ util/generate-hooks-index/
 EXCLUDE_PATTERNS = *smarty3* *strings.php *.out *test*
 OUTPUT_DIRECTORY = doc
 GENERATE_HTML = YES
@@ -21,3 +21,5 @@ ALIASES += "fixme=\xrefitem fixme \"Fixme\" \"Fixme List\""
 ALIASES += "FIXME=\fixme"
 ALIASES += "TODO=\todo"
 ALIASES += "BUG=\bug"
+ALIASES += "hooks=\xrefitem hooks \"Hooks\" \"Hooks List\""
+ALIASES += "HOOKS=\hooks"