Merge pull request #2198 from rabuzarus/2312_code_cleanup

boot.php - code cleanup + doxygen

boot.php

@@ -1,4 +1,21 @@
 <?php
+/** @file boot.php
+ *
+ * This file defines some global constants and includes the central App class.
+ */
+
+/**
+ * Friendica
+ * 
+ * Friendica is a communications platform for integrated social communications
+ * utilising decentralised communications and linkage to several indie social
+ * projects - as well as popular mainstream providers.
+ * 
+ * Our mission is to free our friends and families from the clutches of
+ * data-harvesting corporations, and pave the way to a future where social
+ * communications are free and open and flow between alternate providers as
+ * easily as email does today.
+ */
 
 require_once('include/config.php');
 require_once('include/network.php');
@@ -20,13 +37,22 @@ define ( 'FRIENDICA_CODENAME',     'Asparagus');
 define ( 'FRIENDICA_VERSION',      '3.5-dev' );
 define ( 'DFRN_PROTOCOL_VERSION',  '2.23'    );
 define ( 'DB_UPDATE_VERSION',      1191      );
+
+/**
+ * @brief Constant with a HTML line break.
+ *
+ * Contains a HTML line break (br) element and a real carriage return with line
+ * feed for the source.
+ * This can be used in HTML and JavaScript where needed a line break.
+ */
 define ( 'EOL',                    "<br />\r\n"     );
 define ( 'ATOM_TIME',              'Y-m-d\TH:i:s\Z' );
 
 
 /**
+ * @brief Image storage quality.
  * 
- * Image storage quality. Lower numbers save space at cost of image detail.
+ * Lower numbers save space at cost of image detail.
  * For ease of upgrade, please do not change here. Change jpeg quality with
  * $a->config['system']['jpeg_quality'] = n;
  * in .htconfig.php, where n is netween 1 and 100, and with very poor results
@@ -66,61 +92,76 @@ define ( 'MAX_IMAGE_LENGTH',        -1  );
 define ( 'DEFAULT_DB_ENGINE',  'MyISAM'  );
 
 /**
+ * @name SSL Policy
+ * 
  * SSL redirection policies
+ * @{
  */
-
 define ( 'SSL_POLICY_NONE',         0 );
 define ( 'SSL_POLICY_FULL',         1 );
 define ( 'SSL_POLICY_SELFSIGN',     2 );
-
+/* @}*/
 
 /**
+ * @name Logger
+ * 
  * log levels
+ * @{
  */
-
 define ( 'LOGGER_NORMAL',          0 );
 define ( 'LOGGER_TRACE',           1 );
 define ( 'LOGGER_DEBUG',           2 );
 define ( 'LOGGER_DATA',            3 );
 define ( 'LOGGER_ALL',             4 );
+/* @}*/
 
 /**
- * cache levels
+ * @name Cache
+ * 
+ * Cache levels
+ * @{
  */
-
 define ( 'CACHE_MONTH',            0 );
 define ( 'CACHE_WEEK',             1 );
 define ( 'CACHE_DAY',              2 );
 define ( 'CACHE_HOUR',             3 );
+/* @}*/
 
 /**
- * registration policies
+ * @name Register
+ * 
+ * Registration policies
+ * @{
  */
-
 define ( 'REGISTER_CLOSED',        0 );
 define ( 'REGISTER_APPROVE',       1 );
 define ( 'REGISTER_OPEN',          2 );
+/** @}*/
 
 /**
- * relationship types
+ * @name Contact_is
+ * 
+ * Relationship types
+ * @{
  */
-
 define ( 'CONTACT_IS_FOLLOWER', 1);
 define ( 'CONTACT_IS_SHARING',  2);
 define ( 'CONTACT_IS_FRIEND',   3);
-
+/** @}*/
 
 /**
+ * @name Update
+ * 
  * DB update return values
+ * @{
  */
-
 define ( 'UPDATE_SUCCESS', 0);
 define ( 'UPDATE_FAILED',  1);
+/** @}*/
 
 
 /**
- *
+ * @name page/profile types
- * page/profile types
  *
  * PAGE_NORMAL is a typical personal profile account
  * PAGE_SOAPBOX automatically approves all friend requests as CONTACT_IS_SHARING, (readonly)
@@ -128,24 +169,33 @@ define ( 'UPDATE_FAILED',  1);
  *      write access to wall and comments (no email and not included in page owner's ACL lists)
  * PAGE_FREELOVE automatically approves all friend requests as full friends (CONTACT_IS_FRIEND).
  *
+ * @{
  */
-
 define ( 'PAGE_NORMAL',            0 );
 define ( 'PAGE_SOAPBOX',           1 );
 define ( 'PAGE_COMMUNITY',         2 );
 define ( 'PAGE_FREELOVE',          3 );
 define ( 'PAGE_BLOG',              4 );
 define ( 'PAGE_PRVGROUP',          5 );
+/** @}*/
 
-// Type of the community page
+/**
+ * @name CP
+ * 
+ * Type of the community page
+ * @{
+ */
 define ( 'CP_NO_COMMUNITY_PAGE',   -1 );
 define ( 'CP_USERS_ON_SERVER',     0 );
 define ( 'CP_GLOBAL_COMMUNITY',    1 );
+/** @}*/
 
 /**
+ * @name Network
+ * 
  * Network and protocol family types
+ * @{
  */
-
 define ( 'NETWORK_DFRN',             'dfrn');    // Friendica, Mistpark, other DFRN implementations
 define ( 'NETWORK_ZOT',              'zot!');    // Zot!
 define ( 'NETWORK_OSTATUS',          'stat');    // status.net, identi.ca, GNU-social, other OStatus implementations
@@ -166,6 +216,7 @@ define ( 'NETWORK_APPNET',           'apdn');    // app.net
 define ( 'NETWORK_NEWS',             'nntp');    // Network News Transfer Protocol
 define ( 'NETWORK_ICALENDAR',        'ical');    // iCalendar
 define ( 'NETWORK_PHANTOM',          'unkn');    // Place holder
+/** @}*/
 
 /**
  * These numbers are used in stored permissions
@@ -212,9 +263,11 @@ define ( 'ZCURL_TIMEOUT' , (-1));
 
 
 /**
- * email notification options
+ * @name Notify
+ * 
+ * Email notification options
+ * @{
  */
-
 define ( 'NOTIFY_INTRO',    0x0001 );
 define ( 'NOTIFY_CONFIRM',  0x0002 );
 define ( 'NOTIFY_WALL',     0x0004 );
@@ -228,12 +281,15 @@ define ( 'NOTIFY_POKE',     0x0200 );
 define ( 'NOTIFY_SHARE',    0x0400 );
 
 define ( 'NOTIFY_SYSTEM',   0x8000 );
+/* @}*/
 
 
 /**
+ * @name Term
+ * 
  * Tag/term types
+ * @{
  */
-
 define ( 'TERM_UNKNOWN',   0 );
 define ( 'TERM_HASHTAG',   1 );
 define ( 'TERM_MENTION',   2 );
@@ -249,9 +305,11 @@ define ( 'TERM_OBJ_PHOTO', 2 );
 
 
 /**
- * various namespaces we may need to parse
+ * @name Namespaces
+ * 
+ * Various namespaces we may need to parse
+ * @{
  */
-
 define ( 'NAMESPACE_ZOT',             'http://purl.org/zot' );
 define ( 'NAMESPACE_DFRN' ,           'http://purl.org/macgirvin/dfrn/1.0' );
 define ( 'NAMESPACE_THREAD' ,         'http://purl.org/syndication/thread/1.0' );
@@ -267,10 +325,14 @@ define ( 'NAMESPACE_FEED',            'http://schemas.google.com/g/2010#updates-
 define ( 'NAMESPACE_OSTATUS',         'http://ostatus.org/schema/1.0' );
 define ( 'NAMESPACE_STATUSNET',       'http://status.net/schema/api/1/' );
 define ( 'NAMESPACE_ATOM1',           'http://www.w3.org/2005/Atom' );
-/**
+/* @}*/
- * activity stream defines
- */
 
+/**
+ * @name Activity
+ * 
+ * Activity stream defines
+ * @{
+ */
 define ( 'ACTIVITY_LIKE',        NAMESPACE_ACTIVITY_SCHEMA . 'like' );
 define ( 'ACTIVITY_DISLIKE',     NAMESPACE_DFRN            . '/dislike' );
 define ( 'ACTIVITY_ATTEND',      NAMESPACE_ZOT             . '/activity/attendyes' );
@@ -309,14 +371,19 @@ define ( 'ACTIVITY_OBJ_GROUP',   NAMESPACE_ACTIVITY_SCHEMA . 'group' );
 define ( 'ACTIVITY_OBJ_TAGTERM', NAMESPACE_DFRN            . '/tagterm' );
 define ( 'ACTIVITY_OBJ_PROFILE', NAMESPACE_DFRN            . '/profile' );
 define ( 'ACTIVITY_OBJ_QUESTION', 'http://activityschema.org/object/question' );
+/* @}*/
 
 /**
- * item weight for query ordering
+ * @name Gravity
+ * 
+ * Item weight for query ordering
+ * @{
  */
-
 define ( 'GRAVITY_PARENT',       0);
 define ( 'GRAVITY_LIKE',         3);
 define ( 'GRAVITY_COMMENT',      6);
+/* @}*/
+
 
 /**
  *
@@ -358,7 +425,8 @@ function startup() {
  *
  * class: App
  * 
- * Our main application structure for the life of this page
+ * @brief Our main application structure for the life of this page.
+ * 
  * Primarily deals with the URL that got us here
  * and tries to make some sense of it, and
  * stores our page contents and config storage
@@ -366,9 +434,7 @@ function startup() {
  * before we spit the page out.
  *
  */
-
+class App {
-if(! class_exists('App')) {
-	class App {
 
 	public  $module_loaded = false;
 	public  $query_string;
@@ -417,10 +483,12 @@ if(! class_exists('App')) {
 	public	$theme_thread_allow = true;
 	public	$theme_events_in_profile = true;
 
-		// An array for all theme-controllable parameters
+	/**
-		// Mostly unimplemented yet. Only options 'stylesheet' and
+	 * @brief An array for all theme-controllable parameters
-		// beyond are used.
+	 *
-
+	 * Mostly unimplemented yet. Only options 'template_engine' and
+	 * beyond are used.
+	 */
 	public	$theme = array(
 		'sourcename' => '',
 		'videowidth' => 425,
@@ -431,9 +499,13 @@ if(! class_exists('App')) {
 		'template_engine' => 'smarty3',
 	);
 
-		// array of registered template engines ('name'=>'class name')
+	/**
+	 * @brief An array of registered template engines ('name'=>'class name')
+	 */
 	public $template_engines = array();
-		// array of instanced template engines ('name'=>'instance')
+	/**
+	 * @brief An array of instanced template engines ('name'=>'instance')
+	 */
 	public $template_engine_instance = array();
 
 	private $ldelim = array(
@@ -457,6 +529,9 @@ if(! class_exists('App')) {
 	private $cached_profile_image;
 	private $cached_profile_picdate;
 
+	/**
+	 * @brief App constructor.
+	 */
 	function __construct() {
 
 		global $default_timezone;
@@ -515,7 +590,7 @@ if(! class_exists('App')) {
 
 			if(x($_SERVER,'SERVER_PORT') && $_SERVER['SERVER_PORT'] != 80 && $_SERVER['SERVER_PORT'] != 443)
 				$this->hostname .= ':' . $_SERVER['SERVER_PORT'];
-				/**
+			/*
 			 * Figure out if we are running at the top of a domain
 			 * or in a sub-directory and adjust accordingly
 			 */
@@ -568,7 +643,7 @@ if(! class_exists('App')) {
 			$this->cmd = 'profile/' . substr($this->cmd,2);
 
 
-			/**
+		/*
 		 *
 		 * Break the URL path into C style argc/argv style arguments for our
 		 * modules. Given "http://example.com/module/arg1/arg2", $this->argc
@@ -595,7 +670,7 @@ if(! class_exists('App')) {
 			$this->module = 'home';
 		}
 
-			/**
+		/*
 		 * See if there is any page number information, and initialise
 		 * pagination
 		 */
@@ -607,7 +682,7 @@ if(! class_exists('App')) {
 			$this->pager['start'] = 0;
 		$this->pager['total'] = 0;
 
-			/**
+		/*
 		 * Detect mobile devices
 		 */
 
@@ -618,7 +693,7 @@ if(! class_exists('App')) {
 		// Friendica-Client
 		$this->is_friendica_app = ($_SERVER['HTTP_USER_AGENT'] == "Apache-HttpClient/UNAVAILABLE (java 1.4)");
 
-			/**
+		/*
 		 * register template engines
 		 */
 		$dc = get_declared_classes();
@@ -851,8 +926,10 @@ if(! class_exists('App')) {
 
 
 	/**
-		 * register template engine class
+	 * @brief Register template engine class
-		 * if $name is "", is used class static property $class::$name
+	 * 
+	 * If $name is "", is used class static property $class::$name
+	 * 
 	 * @param string $class
 	 * @param string $name
 	 */
@@ -869,8 +946,10 @@ if(! class_exists('App')) {
 	}
 
 	/**
-		 * return template engine instance. If $name is not defined,
+	 * @brief Return template engine instance.
-		 * return engine defined by theme, or default
+	 * 
+	 * If $name is not defined, return engine defined by theme,
+	 * or default
 	 *
 	 * @param strin $name Template engine name
 	 * @return object Template Engine instance
@@ -899,6 +978,11 @@ if(! class_exists('App')) {
 		echo "template engine <tt>$template_engine</tt> is not registered!\n"; killme();
 	}
 
+	/**
+	 * @brief Returns the active template engine.
+	 *
+	 * @return string
+	 */
 	function get_template_engine() {
 		return $this->theme['template_engine'];
 	}
@@ -947,28 +1031,34 @@ if(! class_exists('App')) {
 		return($this->is_friendica_app);
 	}
 
-	}
 }
 
-// retrieve the App structure
+/**
-// useful in functions which require it but don't get it passed to them
+ * @brief Retrieve the App structure
-
+ * 
-if(! function_exists('get_app')) {
+ * Useful in functions which require it but don't get it passed to them
-	function get_app() {
+ */
+function get_app() {
 	global $a;
 	return $a;
-	}
+}
-};
 
 
-// Multi-purpose function to check variable state.
+/**
-// Usage: x($var) or $x($array,'key')
+ * @brief Multi-purpose function to check variable state.
-// returns false if variable/key is not set
+ *
-// if variable is set, returns 1 if has 'non-zero' value, otherwise returns 0.
+ * Usage: x($var) or $x($array, 'key')
-// e.g. x('') or x(0) returns 0;
+ *
-
+ * returns false if variable/key is not set
-if(! function_exists('x')) {
+ * if variable is set, returns 1 if has 'non-zero' value, otherwise returns 0.
-	function x($s,$k = NULL) {
+ * e.g. x('') or x(0) returns 0;
+ *
+ * @param string|array $s variable to check
+ * @param string $k key inside the array to check
+ *
+ * @return bool|int
+ */
+function x($s,$k = NULL) {
 	if($k != NULL) {
 		if((is_array($s)) && (array_key_exists($k,$s))) {
 			if($s[$k])
@@ -986,21 +1076,19 @@ if(! function_exists('x')) {
 		}
 		return false;
 	}
-	}
 }
 
-// called from db initialisation if db is dead.
 
-if(! function_exists('system_unavailable')) {
+/**
-	function system_unavailable() {
+ * @brief Called from db initialisation if db is dead.
+ */
+function system_unavailable() {
 	include('system_unavailable.php');
 	system_down();
 	killme();
-	}
 }
 
 
-
 function clean_urls() {
 	global $a;
 	//	if($a->config['system']['clean_urls'])
@@ -1016,17 +1104,36 @@ function z_path() {
 	return $base;
 }
 
+/**
+ * @brief Returns the baseurl.
+ *
+ * @see App::get_baseurl()
+ *
+ * @return string
+ */
 function z_root() {
 	global $a;
 	return $a->get_baseurl();
 }
 
+/**
+ * @brief Return absolut URL for given $path.
+ *
+ * @param string $path
+ *
+ * @return string
+ */
 function absurl($path) {
 	if(strpos($path,'/') === 0)
 		return z_path() . $path;
 	return $path;
 }
 
+/**
+ * @brief Function to check if request was an AJAX (xmlhttprequest) request.
+ *
+ * @return boolean
+ */
 function is_ajax() {
 	return (!empty($_SERVER['HTTP_X_REQUESTED_WITH']) && strtolower($_SERVER['HTTP_X_REQUESTED_WITH']) == 'xmlhttprequest');
 }
@@ -1044,13 +1151,11 @@ function check_db() {
 }
 
 
-
+/**
-
+ * Sets the base url for use in cmdline programs which don't have
-// Sets the base url for use in cmdline programs which don't have
+ * $_SERVER variables
-// $_SERVER variables
+ */
-
+function check_url(&$a) {
-if(! function_exists('check_url')) {
-	function check_url(&$a) {
 
 	$url = get_config('system','url');
 
@@ -1066,14 +1171,13 @@ if(! function_exists('check_url')) {
 		$url = set_config('system','url',$a->get_baseurl());
 
 	return;
-	}
 }
 
 
-// Automatic database updates
+/**
-
+ * @brief Automatic database updates
-if(! function_exists('update_db')) {
+ */
-	function update_db(&$a) {
+function update_db(&$a) {
 	$build = get_config('system','build');
 	if(! x($build))
 		$build = set_config('system','build',DB_UPDATE_VERSION);
@@ -1132,10 +1236,9 @@ if(! function_exists('update_db')) {
 	}
 
 	return;
-	}
 }
-if(!function_exists('run_update_function')){
+
-	function run_update_function($x) {
+function run_update_function($x) {
 	if(function_exists('update_' . $x)) {
 
 		// There could be a lot of processes running or about to run.
@@ -1174,16 +1277,10 @@ if(!function_exists('run_update_function')){
 		return true;
 	}
 	return true;
-	}
 }
 
-
+/**
-if(! function_exists('check_plugins')) {
+ * @brief Synchronise plugins:
-	function check_plugins(&$a) {
-
-		/**
-		 *
-		 * Synchronise plugins:
  *
  * $a->config['system']['addon'] contains a comma-separated list of names
  * of plugins/addons which are used on this system.
@@ -1192,8 +1289,11 @@ if(! function_exists('check_plugins')) {
  * and mark it uninstalled in the database (for now we'll remove it).
  * Then go through the config list and if we have a plugin that isn't installed,
  * call the install procedure and add it to the database.
+ * 
+ * @param App $a
  *
 	 */
+function check_plugins(&$a) {
 
 	$r = q("SELECT * FROM `addon` WHERE `installed` = 1");
 	if(count($r))
@@ -1234,7 +1334,6 @@ if(! function_exists('check_plugins')) {
 	load_hooks();
 
 	return;
-	}
 }
 
 function get_guid($size=16, $prefix = "") {
@@ -1256,12 +1355,21 @@ function get_guid($size=16, $prefix = "") {
 	}
 }
 
-// wrapper for adding a login box. If $register == true provide a registration
+/** 
-// link. This will most always depend on the value of $a->config['register_policy'].
+ * @brief Wrapper for adding a login box.
-// returns the complete html for inserting into the page
+ * 
-
+ * @param bool $register
-if(! function_exists('login')) {
+ *	If $register == true provide a registration link.
-	function login($register = false, $hiddens=false) {
+ *	This will most always depend on the value of $a->config['register_policy'].
+ * @param bool $hiddens
+ * 
+ * @return string
+ *	Returns the complete html for inserting into the page
+ * 
+ * @hooks 'login_hook'
+ *	string $o
+ */
+function login($register = false, $hiddens=false) {
 	$a = get_app();
 	$o = "";
 	$reg = false;
@@ -1320,75 +1428,69 @@ if(! function_exists('login')) {
 	call_hooks('login_hook',$o);
 
 	return $o;
-	}
 }
 
-// Used to end the current process, after saving session state.
+/**
-
+ * @brief Used to end the current process, after saving session state.
-if(! function_exists('killme')) {
+ */
-	function killme() {
+function killme() {
 	session_write_close();
 	exit;
-	}
 }
 
-// redirect to another URL and terminate this process.
+/**
-
+ * @brief Redirect to another URL and terminate this process.
-if(! function_exists('goaway')) {
+ */
-	function goaway($s) {
+function goaway($s) {
 	header("Location: $s");
 	killme();
-	}
 }
 
 
-// Returns the uid of locally logged in user or false.
+/**
-
+ * @brief Returns the user id of locally logged in user or false.
-if(! function_exists('local_user')) {
+ * 
-	function local_user() {
+ * @return int|bool user id or false
+ */
+function local_user() {
 	if((x($_SESSION,'authenticated')) && (x($_SESSION,'uid')))
 		return intval($_SESSION['uid']);
 	return false;
-	}
 }
 
-// Returns contact id of authenticated site visitor or false
+/**
-
+ * @brief Returns contact id of authenticated site visitor or false
-if(! function_exists('remote_user')) {
+ * 
-	function remote_user() {
+ * @return int|bool visitor_id or false
+ */
+function remote_user() {
 	if((x($_SESSION,'authenticated')) && (x($_SESSION,'visitor_id')))
 		return intval($_SESSION['visitor_id']);
 	return false;
-	}
 }
 
-// contents of $s are displayed prominently on the page the next time
+/**
-// a page is loaded. Usually used for errors or alerts.
+ * @brief Show an error message to user.
-
-if(! function_exists('notice')) {
-	/**
-	 * Show an error message to user.
  *
  * This function save text in session, to be shown to the user at next page load
  *
  * @param string $s - Text of notice
  */
-	function notice($s) {
+function notice($s) {
 	$a = get_app();
 	if(! x($_SESSION,'sysmsg'))	$_SESSION['sysmsg'] = array();
 	if($a->interactive)
 		$_SESSION['sysmsg'][] = $s;
-	}
 }
-if(! function_exists('info')) {
+
-	/**
+/**
-	 * Show an info message to user.
+ * @brief Show an info message to user.
  *
  * This function save text in session, to be shown to the user at next page load
  *
  * @param string $s - Text of notice
  */
-	function info($s) {
+function info($s) {
 	$a = get_app();
 
 	if (local_user() AND get_pconfig(local_user(),'system','ignore_info'))
@@ -1397,35 +1499,34 @@ if(! function_exists('info')) {
 	if(! x($_SESSION,'sysmsg_info')) $_SESSION['sysmsg_info'] = array();
 	if($a->interactive)
 		$_SESSION['sysmsg_info'][] = $s;
-	}
 }
 
 
-// wrapper around config to limit the text length of an incoming message
+/**
-
+ * @brief Wrapper around config to limit the text length of an incoming message
-if(! function_exists('get_max_import_size')) {
+ *
-	function get_max_import_size() {
+ * @return int
+ */
+function get_max_import_size() {
 	global $a;
 	return ((x($a->config,'max_import_size')) ? $a->config['max_import_size'] : 0 );
-	}
 }
 
 /**
- *
+ * @brief Wrap calls to proc_close(proc_open()) and call hook
- * Wrap calls to proc_close(proc_open()) and call hook
  *	so plugins can take part in process :)
  *
- * args:
+ * @param string $cmd program to run
- * $cmd program to run
- *  next args are passed as $cmd command line
  * 
+ * next args are passed as $cmd command line
  * e.g.: proc_run("ls","-la","/tmp");
  *
- * $cmd and string args are surrounded with ""
+ * @note $cmd and string args are surrounded with ""
+ * 
+ * @hooks 'proc_run'
+ *	array $arr
  */
-
+function proc_run($cmd){
-if(! function_exists('proc_run')) {
-	function proc_run($cmd){
 
 	$a = get_app();
 
@@ -1508,11 +1609,9 @@ if(! function_exists('proc_run')) {
 		proc_close(proc_open('cmd /c start /b ' . $cmdline,array(),$foo,dirname(__FILE__)));
 	else
 		proc_close(proc_open($cmdline." &",array(),$foo,dirname(__FILE__)));
-	}
 }
 
-if(! function_exists('current_theme')) {
+function current_theme(){
-	function current_theme(){
 	$app_base_themes = array('duepuntozero', 'dispy', 'quattro');
 
 	$a = get_app();
@@ -1586,15 +1685,16 @@ if(! function_exists('current_theme')) {
 	if(count($fallback))
 		return (str_replace('view/theme/','', substr($fallback[0],0,-10)));
 
-	}
 }
 
-/*
+/**
- * Return full URL to theme which is currently in effect.
+ * @brief Return full URL to theme which is currently in effect.
-* Provide a sane default if nothing is chosen or the specified theme does not exist.
+ * 
-*/
+ * Provide a sane default if nothing is chosen or the specified theme does not exist.
-if(! function_exists('current_theme_url')) {
+ * 
-	function current_theme_url() {
+ * @return string
+ */
+function current_theme_url() {
 	global $a;
 
 	$t = current_theme();
@@ -1604,11 +1704,9 @@ if(! function_exists('current_theme_url')) {
 		return($a->get_baseurl() . '/view/theme/' . $t . '/style.pcss' . $opts);
 
 	return($a->get_baseurl() . '/view/theme/' . $t . '/style.css');
-	}
 }
 
-if(! function_exists('feed_birthday')) {
+function feed_birthday($uid,$tz) {
-	function feed_birthday($uid,$tz) {
 
 	/**
 	 *
@@ -1653,11 +1751,14 @@ if(! function_exists('feed_birthday')) {
 	}
 
 	return $birthday;
-	}
 }
 
-if(! function_exists('is_site_admin')) {
+/**
-	function is_site_admin() {
+ * @brief Check if current user has admin role.
+ *
+ * @return bool true if user is an admin
+ */
+function is_site_admin() {
 	$a = get_app();
 
 	$adminlist = explode(",", str_replace(" ", "", $a->config['admin_email']));
@@ -1666,12 +1767,10 @@ if(! function_exists('is_site_admin')) {
 	if(local_user() && x($a->user,'email') && x($a->config,'admin_email') && in_array($a->user['email'], $adminlist))
 		return true;
 	return false;
-	}
 }
 
 
-if(! function_exists('load_contact_links')) {
+function load_contact_links($uid) {
-	function load_contact_links($uid) {
 
 	$a = get_app();
 
@@ -1693,15 +1792,16 @@ if(! function_exists('load_contact_links')) {
 
 	$a->contacts = $ret;
 	return;
-	}
 }
 
 /**
-* returns querystring as string from a mapped array
+ * @brief Returns querystring as string from a mapped array.
-*
+ *
-* @param params Array
+ * @param array $params mapped array with query parameters
-* @return string
+ * @param string $name of parameter, default null
-*/
+ *
+ * @return string
+ */
 function build_querystring($params, $name=null) {
 	$ret = "";
 	foreach($params as $key=>$val) {
@@ -1908,8 +2008,8 @@ function get_temppath() {
 }
 
 function set_template_engine(&$a, $engine = 'internal') {
-// This function is no longer necessary, but keep it as a wrapper to the class method
+/// @note This function is no longer necessary, but keep it as a wrapper to the class method
-// to avoid breaking themes again unnecessarily
+/// to avoid breaking themes again unnecessarily
 
 	$a->set_template_engine($engine);
 }

include/identity.php

@@ -9,12 +9,8 @@ require_once("mod/proxy.php");
 
 /**
  *
- * Function : profile_load
+ * @brief Loads a profile into the page sidebar.
- * @parameter App    $a
- * @parameter string $nickname
- * @parameter int    $profile
  *
- * Summary: Loads a profile into the page sidebar.
  * The function requires a writeable copy of the main App structure, and the nickname
  * of a registered local account.
  *
@@ -26,14 +22,16 @@ require_once("mod/proxy.php");
  * Profile information is placed in the App structure for later retrieval.
  * Honours the owner's chosen theme for display.
  *
- * IMPORTANT: Should only be run in the _init() functions of a module. That ensures that
+ * @attention Should only be run in the _init() functions of a module. That ensures that
  *      the theme is chosen before the _init() function of a theme is run, which will usually
  *      load a lot of theme-specific content
  *
+ * @param App $a
+ * @param string $nickname
+ * @param int $profile
+ * @param array $profiledata
  */
-
+function profile_load(&$a, $nickname, $profile = 0, $profiledata = array()) {
-if(! function_exists('profile_load')) {
-	function profile_load(&$a, $nickname, $profile = 0, $profiledata = array()) {
 
 	$user = q("SELECT `uid` FROM `user` WHERE `nickname` = '%s' LIMIT 1",
 		dbesc($nickname)
@@ -78,7 +76,7 @@ if(! function_exists('profile_load')) {
 
 	$_SESSION['mobile-theme'] = $a->profile['mobile-theme'];
 
-		/**
+	/*
 	 * load/reload current theme info
 	 */
 
@@ -101,9 +99,11 @@ if(! function_exists('profile_load')) {
 
 	$block = (((get_config('system','block_public')) && (! local_user()) && (! remote_user())) ? true : false);
 
-		// To-Do:
+	/**
-		// By now, the contact block isn't shown, when a different profile is given
+	 * @todo
-		// But: When this profile was on the same server, then we could display the contacts
+	 * By now, the contact block isn't shown, when a different profile is given
+	 * But: When this profile was on the same server, then we could display the contacts
+	 */
 	if ($profiledata)
 		$a->page['aside'] .= profile_sidebar($profiledata, true);
 	else
@@ -113,12 +113,12 @@ if(! function_exists('profile_load')) {
 	 $a->page['aside'] .= contact_block();*/
 
 	return;
-	}
 }
 
 
 /**
  * @brief Get all profil data of a local user
+ * 
  * If the viewer is an authenticated remote viewer, the profile displayed is the
  * one that has been configured for his/her viewing in the Contact manager.
  * Passing a non-zero profile ID can also allow a preview of a selected profile
@@ -170,21 +170,24 @@ function get_profiledata_by_nick($nickname, $uid = 0, $profile = 0) {
 
 
 /**
+ * @brief Formats a profile for display in the sidebar.
  * 
- * Function: profile_sidebar
- *
- * Formats a profile for display in the sidebar.
  * It is very difficult to templatise the HTML completely
  * because of all the conditional logic.
  * 
- * @parameter: array $profile
+ * @param array $profile
+ * @param int $block
  * 
- * Returns HTML string stuitable for sidebar inclusion
+ * @return HTML string stuitable for sidebar inclusion
- * Exceptions: Returns empty string if passed $profile is wrong type or not populated
  * 
+ * @note Returns empty string if passed $profile is wrong type or not populated
+ * 
+ * @hooks 'profile_sidebar_enter'
+ *      array $profile - profile data
+ * @hooks 'profile_sidebar'
+ *      array $arr
  */
-if(! function_exists('profile_sidebar')) {
+function profile_sidebar($profile, $block = 0) {
-	function profile_sidebar($profile, $block = 0) {
 	$a = get_app();
 
 	$o = '';
@@ -399,12 +402,10 @@ if(! function_exists('profile_sidebar')) {
 	call_hooks('profile_sidebar', $arr);
 
 	return $o;
-	}
 }
 
 
-if(! function_exists('get_birthdays')) {
+function get_birthdays() {
-	function get_birthdays() {
 
 	$a = get_app();
 	$o = '';
@@ -483,12 +484,10 @@ if(! function_exists('get_birthdays')) {
 		'$rbr' => '}'
 
 	));
-	}
 }
 
 
-if(! function_exists('get_events')) {
+function get_events() {
-	function get_events() {
 
 	require_once('include/bbcode.php');
 
@@ -566,7 +565,6 @@ if(! function_exists('get_events')) {
 		'$event_title' => t('Events this week:'),
 		'$events' => $r,
 	));
-	}
 }
 
 function advanced_profile(&$a) {
@@ -669,8 +667,7 @@ function advanced_profile(&$a) {
 	return '';
 }
 
-if(! function_exists('profile_tabs')){
+function profile_tabs($a, $is_owner=False, $nickname=Null){
-	function profile_tabs($a, $is_owner=False, $nickname=Null){
 	//echo "<pre>"; var_dump($a->user); killme();
 
 	if (is_null($nickname))
@@ -753,7 +750,6 @@ if(! function_exists('profile_tabs')){
 	$tpl = get_markup_template('common_tabs.tpl');
 
 	return replace_macros($tpl,array('$tabs' => $arr['tabs']));
-	}
 }
 
 function get_my_url() {
@@ -799,12 +795,20 @@ function zrl($s,$force = false) {
 	return $s;
 }
 
-// Used from within PCSS themes to set theme parameters. If there's a
+/**
-// puid request variable, that is the "page owner" and normally their theme
+ * @brief Get the user ID of the page owner
-// settings take precedence; unless a local user sets the "always_my_theme"
+ *
-// system pconfig, which means they don't want to see anybody else's theme
+ * Used from within PCSS themes to set theme parameters. If there's a
-// settings except their own while on this site.
+ * puid request variable, that is the "page owner" and normally their theme
-
+ * settings take precedence; unless a local user sets the "always_my_theme"
+ * system pconfig, which means they don't want to see anybody else's theme
+ * settings except their own while on this site.
+ *
+ * @return int user ID
+ * 
+ * @note Returns local_user instead of user ID if "always_my_theme"
+ *      is set to true
+ */
 function get_theme_uid() {
 	$uid = (($_REQUEST['puid']) ? intval($_REQUEST['puid']) : 0);
 	if(local_user()) {

include/plugin.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * @file include/identity.php
+ * @file include/plugin.php
  * 
  * @brief Some functions to handle addons and themes.
  */