Merge pull request #207 from Spuds/docblock

! Fix many of the phpdocumentor errors with our docblock's

Packages/index.php

@@ -1,6 +1,8 @@
 <?php
 
-// This file is here solely to protect your Packages directory.
+/**
+ * This file is here solely to protect your Packages directory.
+ */
 
 // Look for Settings.php....
 if (file_exists(dirname(dirname(__FILE__)) . '/Settings.php'))

Smileys/index.php

@@ -1,6 +1,8 @@
 <?php
 
-// This file is here solely to protect your Smileys directory.
+/**
+ * This file is here solely to protect your Smileys directory.
+ */
 
 // Look for Settings.php....
 if (file_exists(dirname(dirname(__FILE__)) . '/Settings.php'))

Sources/Class-BrowserDetect.php

@@ -1,8 +1,21 @@
 <?php
 
 /**
- * This class is an experiment for the job of correctly detecting browsers and settings
- * needed for them.
+ * Simple Machines Forum (SMF)
+ *
+ * @package SMF
+ * @author Simple Machines http://www.simplemachines.org
+ * @copyright 2012 Simple Machines
+ * @license http://www.simplemachines.org/about/smf/license.php BSD
+ *
+ * @version 2.1 Alpha 1
+ */
+
+if (!defined('SMF'))
+	die('Hacking attempt...');
+
+/**
+ *  This class is an experiment for the job of correctly detecting browsers and settings needed for them.
  * - Detects the following browsers
  * - Opera, Webkit, Firefox, Web_tv, Konqueror, IE, Gecko
  * - Webkit variants: Chrome, iphone, blackberry, android, safari, ipad, ipod
@@ -12,10 +25,6 @@
  * - IE Versions: 4, 5, 5.5, 6, 7, 8, 9, 10 ... mobile and Mac
  * - Nokia
  */
-
-if (!defined('SMF'))
-	die('Hacking attempt...');
-
 class browser_detector
 {
 	/**
@@ -24,6 +33,12 @@ class browser_detector
 	 * @var array
 	 */
 	private $_browsers = null;
+
+	/**
+	 * Holds if the detected device may be a mobile one
+	 *
+	 * @var type
+	 */
 	private $_is_mobile = null;
 
 	/**

Sources/Class-CurlFetchWeb.php

@@ -1,7 +1,19 @@
 <?php
 /**
- *
  * Simple Machines Forum (SMF)
+ *
+ * @package SMF
+ * @author Simple Machines http://www.simplemachines.org
+ * @copyright 2012 Simple Machines
+ * @license http://www.simplemachines.org/about/smf/license.php BSD
+ *
+ * @version 2.1 Alpha 1
+ */
+
+if (!defined('SMF'))
+	die('Hacking attempt...');
+
+/**
  * Simple cURL class to fetch a web page
  * Properly redirects even with safe mode and basedir restrictions
  * Can provide simple post options to a page
@@ -23,20 +35,14 @@
  *  - $fetch_data->result(); // an array of results, body, header, http result codes
  *  - $fetch_data->result_raw(); // show all results of all calls (in the event of a redirect)
  *  - $fetch_data->result_raw(0); // show all results of call x
- *
- * @package SMF
- * @author Simple Machines http://www.simplemachines.org
- * @copyright 2012 Simple Machines
- * @license http://www.simplemachines.org/about/smf/license.php BSD
- *
- * @version 2.1 Alpha 1
  */
-
-if (!defined('SMF'))
-	die('Hacking attempt...');
-
 class curl_fetch_web_data
 {
+	/**
+	 * Set the default itmes for this class
+	 *
+	 * @var type
+	 */
 	private $default_options = array(
 		CURLOPT_RETURNTRANSFER	=> 1, // Get returned value as a string (don't output it)
 		CURLOPT_HEADER			=> 1, // We need the headers to do our own redirect
@@ -55,8 +61,8 @@ class curl_fetch_web_data
 	* Start the curl object
 	* - allow for user override values
 	*
-	* @param type $options, cURL options as an array
-	* @param type $max_redirect, use to overide the default of 3
+	* @param type $options cURL options as an array
+	* @param type $max_redirect use to overide the default of 3
 	*/
 	public function __construct($options = array(), $max_redirect = 3)
 	{
@@ -72,8 +78,8 @@ class curl_fetch_web_data
 	*  - passed arrays will be converted to a post string joined with &'s
 	*  - calls set_options to set the curl opts array values based on the defaults and user input
 	*
-	* @param type $url, the site we are going to fetch
-	* @param type $post_data, any post data as form name => value
+	* @param type $url the site we are going to fetch
+	* @param type $post_data any post data as form name => value
 	*/
 	public function get_url_data($url, $post_data = array())
 	{
@@ -95,8 +101,8 @@ class curl_fetch_web_data
 	*  - stores responses (url, code, error, headers, body) in the response array
 	*  - detects 301, 302, 307 codes and will redirect to the given response header location
 	*
-	* @param type $url, site to fetch
-	* @param type $redirect, flag to indicate if this was a redirect request or not
+	* @param type $url site to fetch
+	* @param type $redirect flag to indicate if this was a redirect request or not
 	* @return boolean
 	*/
 	private function curl_request($url, $redirect = false)
@@ -151,8 +157,8 @@ class curl_fetch_web_data
 	/**
 	* Used if being redirected to ensure we have a fully qualified address
 	*
-	* @param type $last_url, where we went to
-	* @param type $new_url, where we were redirected to
+	* @param type $last_url where we went to
+	* @param type $new_url where we were redirected to
 	* @return new url location
 	*/
 	private function get_redirect_url($last_url = '', $new_url = '')
@@ -176,7 +182,7 @@ class curl_fetch_web_data
 	*  - called as ->result() will return the full final array
 	*  - called as ->result('body') to just return the page source of the result
 	*
-	* @param type $area, used to return an area such as body, header, error
+	* @param type $area used to return an area such as body, header, error
 	* @return type
 	*/
 	public function result($area = '')

Sources/Class-Package.php

@@ -21,19 +21,33 @@ if (!defined('SMF'))
  */
 class xmlArray
 {
-	// The array and debugging output level.
-	public $array, $debug_level, $trim;
+	/**
+	 * holds xml parsed results
+	 * @var array
+	 */
+	public $array;
+
+	/**
+	 * holds debugging level
+	 * @var type
+	 */
+	public $debug_level;
+
+	/**
+	 * holds trim level textual data
+	 * @var bool
+	 */
+	public $trim;
 
 	/**
 	 * Constructor for the xml parser.
 	 * Example use:
 	 *  $xml = new xmlArray(file('data.xml'));
+	 *
 	 * @param string $data the xml data or an array of, unless is_clone is true.
-	 * @param bool $auto_trim, default false, used to automatically trim textual data.
-	 * @param int $level, default null, the debug level, specifies whether notices
-	 *  should be generated for missing elements and attributes.
-	 * @param bool $is_clone, default false. If is_clone is true, the
-	 *  xmlArray is cloned from another - used internally only.
+	 * @param bool $auto_trim default false, used to automatically trim textual data.
+	 * @param int $level default null, the debug level, specifies whether notices should be generated for missing elements and attributes.
+	 * @param bool $is_clone default false. If is_clone is true, the  xmlArray is cloned from another - used internally only.
 	 */
 	public function __construct($data, $auto_trim = false, $level = null, $is_clone = false)
 	{
@@ -179,8 +193,9 @@ class xmlArray
 	 * Check if an element exists.
 	 * Example use,
 	 *  echo $xml->exists('html/body') ? 'y' : 'n';
+	 *
 	 * @param string $path - the path to the element to get.
-	 * @return bool
+	 * @return boolean
 	 */
 	public function exists($path)
 	{
@@ -298,7 +313,8 @@ class xmlArray
 	 * Output the xml in an array form.
 	 * Example use:
 	 *  print_r($xml->to_array());
-	 * @param string $path, the path to output.
+	 *
+	 * @param string $path the path to output.
 	 */
 	public function to_array($path = null)
 	{
@@ -322,6 +338,7 @@ class xmlArray
 
 	/**
 	 * Parse data into an array. (privately used...)
+	 *
 	 * @param string $data to parse
 	 */
 	protected function _parse($data)
@@ -469,6 +486,7 @@ class xmlArray
 
 	/**
 	 * Get a specific element's xml. (privately used...)
+	 *
 	 * @param $array
 	 * @param $indent
 	 */
@@ -519,7 +537,12 @@ class xmlArray
 		return $output;
 	}
 
-	// Return an element as an array...
+	/**
+	 * Return an element as an array
+	 *
+	 * @param type $array
+	 * @return type
+	 */
 	protected function _array($array)
 	{
 		$return = array();
@@ -543,6 +566,7 @@ class xmlArray
 
 	/**
 	 * Parse out CDATA tags. (htmlspecialchars them...)
+	 *
 	 * @param $data
 	 */
 	function _to_cdata($data)
@@ -579,6 +603,7 @@ class xmlArray
 
 	/**
 	 * Turn the CDATAs back to normal text.
+	 *
 	 * @param $data
 	 */
 	protected function _from_cdata($data)
@@ -624,6 +649,7 @@ class xmlArray
 
 	/**
 	 * Get a specific array by path, one level down. (privately used...)
+	 *
 	 * @param array $array
 	 * @param string $path
 	 * @param int $level
@@ -686,13 +712,43 @@ class xmlArray
 
 /**
  * Simple FTP protocol implementation.
+ *
  * http://www.faqs.org/rfcs/rfc959.html
  */
 class ftp_connection
 {
-	public $connection, $error, $last_message, $pasv;
+	/**
+	 * holds the connection response
+	 * @var type
+	 */
+	public $connection;
 
-	// Create a new FTP connection...
+	/**
+	 * holds any errors
+	 * @var type
+	 */
+	public $error;
+
+	/**
+	 * holds last message from the server
+	 * @var type
+	 */
+	public $last_message;
+
+	/**
+	 * Passive connection
+	 * @var type
+	 */
+	public $pasv;
+
+	/**
+	 * Create a new FTP connection...
+	 *
+	 * @param type $ftp_server
+	 * @param type $ftp_port
+	 * @param type $ftp_user
+	 * @param type $ftp_pass
+	 */
 	public function __construct($ftp_server, $ftp_port = 21, $ftp_user = 'anonymous', $ftp_pass = '[email protected]')
 	{
 		// Initialize variables.
@@ -704,6 +760,15 @@ class ftp_connection
 			$this->connect($ftp_server, $ftp_port, $ftp_user, $ftp_pass);
 	}
 
+	/**
+	 * Connects to a server
+	 *
+	 * @param type $ftp_server
+	 * @param type $ftp_port
+	 * @param type $ftp_user
+	 * @param type $ftp_pass
+	 * @return type
+	 */
 	public function connect($ftp_server, $ftp_port = 21, $ftp_user = 'anonymous', $ftp_pass = '[email protected]')
 	{
 		if (strpos($ftp_server, 'ftp://') === 0)
@@ -746,6 +811,12 @@ class ftp_connection
 		}
 	}
 
+	/**
+	 * Changes to a directory (chdir) via the ftp connection
+	 *
+	 * @param type $ftp_path
+	 * @return boolean
+	 */
 	public function chdir($ftp_path)
 	{
 		if (!is_resource($this->connection))
@@ -765,6 +836,13 @@ class ftp_connection
 		return true;
 	}
 
+	/**
+	 * Changes a files atrributes (chmod)
+	 *
+	 * @param string $ftp_file
+	 * @param type $chmod
+	 * @return boolean
+	 */
 	public function chmod($ftp_file, $chmod)
 	{
 		if (!is_resource($this->connection))
@@ -784,6 +862,12 @@ class ftp_connection
 		return true;
 	}
 
+	/**
+	 * Deletes a file
+	 *
+	 * @param type $ftp_file
+	 * @return boolean
+	 */
 	public function unlink($ftp_file)
 	{
 		// We are actually connected, right?
@@ -807,6 +891,12 @@ class ftp_connection
 		return true;
 	}
 
+	/**
+	 * Reads the response to the command from the server
+	 *
+	 * @param type $desired
+	 * @return type
+	 */
 	public function check_response($desired)
 	{
 		// Wait for a response that isn't continued with -, but don't wait too long.
@@ -819,6 +909,11 @@ class ftp_connection
 		return is_array($desired) ? in_array(substr($this->last_message, 0, 3), $desired) : substr($this->last_message, 0, 3) == $desired;
 	}
 
+	/**
+	 * Used to create a passive connection
+	 *
+	 * @return boolean
+	 */
 	public function passive()
 	{
 		// We can't create a passive data connection without a primary one first being there.
@@ -852,6 +947,12 @@ class ftp_connection
 		return true;
 	}
 
+	/**
+	 * Creates a new file on the server
+	 *
+	 * @param type $ftp_file
+	 * @return boolean
+	 */
 	public function create_file($ftp_file)
 	{
 		// First, we have to be connected... very important.
@@ -885,6 +986,13 @@ class ftp_connection
 		return true;
 	}
 
+	/**
+	 * Generates a direcotry listing for the current directory
+	 *
+	 * @param type $ftp_path
+	 * @param type $search
+	 * @return boolean
+	 */
 	public function list_dir($ftp_path = '', $search = false)
 	{
 		// Are we even connected...?
@@ -923,6 +1031,13 @@ class ftp_connection
 		return $data;
 	}
 
+	/**
+	 * Determins the current dirctory we are in
+	 *
+	 * @param type $file
+	 * @param type $listing
+	 * @return string|boolean
+	 */
 	public function locate($file, $listing = null)
 	{
 		if ($listing === null)
@@ -963,6 +1078,12 @@ class ftp_connection
 		return false;
 	}
 
+	/**
+	 * Creates a new directory on the server
+	 *
+	 * @param type $ftp_dir
+	 * @return boolean
+	 */
 	public function create_dir($ftp_dir)
 	{
 		// We must be connected to the server to do something.
@@ -980,6 +1101,13 @@ class ftp_connection
 		return true;
 	}
 
+	/**
+	 * Detects the current path
+	 *
+	 * @param type $filesystem_path
+	 * @param type $lookup_file
+	 * @return type
+	 */
 	public function detect_path($filesystem_path, $lookup_file = null)
 	{
 		$username = '';
@@ -1025,6 +1153,11 @@ class ftp_connection
 		return array($username, $path, isset($found_path));
 	}
 
+	/**
+	 * Close the ftp connection
+	 *
+	 * @return boolean
+	 */
 	public function close()
 	{
 		// Goodbye!

Sources/DbExtra-mysql.php

@@ -216,8 +216,9 @@ function smf_db_optimize_table($table)
 /**
  * This function lists all tables in the database.
  * The listing could be filtered according to $filter.
- * @param mixed $db, string holding the table name, or false, default false
- * @param mixed $filter, string to filter by, or false, default false
+ *
+ * @param mixed $db string holding the table name, or false, default false
+ * @param mixed $filter string to filter by, or false, default false
  * @return array, an array of table names. (strings)
  */
 function smf_db_list_tables($db = false, $filter = false)
@@ -248,9 +249,10 @@ function smf_db_list_tables($db = false, $filter = false)
 /**
  * Gets all the necessary INSERTs for the table named table_name.
  * It goes in 250 row segments.
+ *
  * @param string $tableName - the table to create the inserts for.
- * @return string, the query to insert the data back in, or an empty
- *  string if the table was empty.
+ * @param bool $new_table
+ * @return string the query to insert the data back in, or an empty string if the table was empty.
  */
 function smf_db_insert_sql($tableName, $new_table = false)
 {

Sources/DbExtra-postgresql.php

@@ -112,9 +112,10 @@ function smf_db_optimize_table($table)
 /**
  * This function lists all tables in the database.
  * The listing could be filtered according to $filter.
- * @param mixed $db, string holding the table name, or false, default false
- * @param mixed $filter, string to filter by, or false, default false
- * @return array, an array of table names. (strings)
+ *
+ * @param mixed $db string holding the table name, or false, default false
+ * @param mixed $filter string to filter by, or false, default false
+ * @return array an array of table names. (strings)
  */
 function smf_db_list_tables($db = false, $filter = false)
 {
@@ -143,9 +144,10 @@ function smf_db_list_tables($db = false, $filter = false)
 /**
  * Gets all the necessary INSERTs for the table named table_name.
  * It goes in 250 row segments.
+ *
  * @param string $tableName - the table to create the inserts for.
- * @return string, the query to insert the data back in, or an empty
- *  string if the table was empty.
+ * @param bool new_table
+ * @return string the query to insert the data back in, or an empty string if the table was empty.
  */
 function smf_db_insert_sql($tableName, $new_table = false)
 {

Sources/DbExtra-sqlite.php

@@ -158,9 +158,10 @@ function smf_db_optimize_table($table)
 /**
  * This function lists all tables in the database.
  * The listing could be filtered according to $filter.
- * @param mixed $db, string holding the table name, or false, default false
- * @param mixed $filter, string to filter by, or false, default false
- * @return array, an array of table names. (strings)
+ * 
+ * @param mixed $db string holding the table name, or false, default false
+ * @param mixed $filter string to filter by, or false, default false
+ * @return array an array of table names. (strings)
  */
 function smf_db_list_tables($db = false, $filter = false)
 {
@@ -190,9 +191,10 @@ function smf_db_list_tables($db = false, $filter = false)
 /**
  * Gets all the necessary INSERTs for the table named table_name.
  * It goes in 250 row segments.
+ *
  * @param string $tableName - the table to create the inserts for.
- * @return string, the query to insert the data back in, or an empty
- *  string if the table was empty.
+ * @param bool new_table
+ * @return string the query to insert the data back in, or an empty string if the table was empty.
  */
 function smf_db_insert_sql($tableName, $new_table = false)
 {

Sources/DbPackages-mysql.php

@@ -82,12 +82,13 @@ function db_packages_init()
  *  	- 'ignore' will do nothing if the table exists. (And will return true)
  *  	- 'overwrite' will drop any existing table of the same name.
  *  	- 'error' will return false if the table already exists.
+ *
  * @param string $table_name
- * @param array $columns, in the format specified.
- * @param array $indexes, default array(), in the format specified.
- * @param array $parameters, default array()
- * @param string $if_exists, default 'ignore'
- * @param string $error, default 'fatal'
+ * @param array $columns in the format specified.
+ * @param array $indexes default array(), in the format specified.
+ * @param array $parameters default array()
+ * @param string $if_exists default 'ignore'
+ * @param string $error default 'fatal'
  */
 function smf_db_create_table($table_name, $columns, $indexes = array(), $parameters = array(), $if_exists = 'ignore', $error = 'fatal')
 {
@@ -157,9 +158,10 @@ function smf_db_create_table($table_name, $columns, $indexes = array(), $paramet
 
 /**
  * Drop a table.
+ *
  * @param string $table_name
- * @param array $parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param string $error default 'fatal'
  */
 function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 {
@@ -196,11 +198,12 @@ function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 
 /**
  * This function adds a column.
- * @param string $table_name, the name of the table
- * @param array $column_info, with column information
- * @param array $parameters, default array()
- * @param string $if_exists, default 'update'
- * @param string $error, default 'fatal'
+ *
+ * @param string $table_name the name of the table
+ * @param array $column_info with column information
+ * @param array $parameters default array()
+ * @param string $if_exists default 'update'
+ * @param string $error default 'fatal'
  */
 function smf_db_add_column($table_name, $column_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -248,10 +251,11 @@ function smf_db_add_column($table_name, $column_info, $parameters = array(), $if
 
 /**
  * Removes a column.
+ *
  * @param string $table_name
  * @param string $column_name
- * @param array $parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param string $error default 'fatal'
  */
 function smf_db_remove_column($table_name, $column_name, $parameters = array(), $error = 'fatal')
 {
@@ -281,11 +285,12 @@ function smf_db_remove_column($table_name, $column_name, $parameters = array(),
 
 /**
  * Change a column.
+ *
  * @param string $table_name
  * @param $old_column
  * @param $column_info
- * @param array $parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param string $error default 'fatal'
  */
 function smf_db_change_column($table_name, $old_column, $column_info, $parameters = array(), $error = 'fatal')
 {
@@ -341,11 +346,12 @@ function smf_db_change_column($table_name, $old_column, $column_info, $parameter
 
 /**
  * Add an index.
+ *
  * @param string $table_name
  * @param array $index_info
- * @param array $parameters, default array()
- * @param string $if_exists, default 'update'
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param string $if_exists default 'update'
+ * @param string $error default 'fatal'
  */
 function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -413,10 +419,11 @@ function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_e
 
 /**
  * Remove an index.
+ *
  * @param string $table_name
  * @param string $index_name
- * @param array$parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array$parameters default array()
+ * @param string $error default 'fatal'
  */
 function smf_db_remove_index($table_name, $index_name, $parameters = array(), $error = 'fatal')
 {
@@ -464,6 +471,7 @@ function smf_db_remove_index($table_name, $index_name, $parameters = array(), $e
 
 /**
  * Get the schema formatted name for a type.
+ *
  * @param string $type_name
  * @param $type_size
  * @param $reverse
@@ -476,8 +484,9 @@ function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 
 /**
  * Get table structure.
+ *
  * @param string $table_name
- * @param array $parameters, default array()
+ * @param array $parameters default array()
  */
 function smf_db_table_structure($table_name, $parameters = array())
 {
@@ -494,9 +503,10 @@ function smf_db_table_structure($table_name, $parameters = array())
 
 /**
  * Return column information for a table.
+ *
  * @param string $table_name
  * @param bool $detail
- * @param array $parameters, default array()
+ * @param array $parameters default array()
  * @return mixed
  */
 function smf_db_list_columns($table_name, $detail = false, $parameters = array())
@@ -561,6 +571,7 @@ function smf_db_list_columns($table_name, $detail = false, $parameters = array()
 
 /**
  * Get index information.
+ *
  * @param string $table_name
  * @param bool $detail
  * @param array $parameters
@@ -618,6 +629,12 @@ function smf_db_list_indexes($table_name, $detail = false, $parameters = array()
 	return $indexes;
 }
 
+/**
+ * Creates a query for a column
+ *
+ * @param array $column
+ * @return type
+ */
 function smf_db_create_query_column($column)
 {
 	global $smcFunc;

Sources/DbPackages-postgresql.php

@@ -82,12 +82,13 @@ function db_packages_init()
  *  	- 'ignore' will do nothing if the table exists. (And will return true)
  *  	- 'overwrite' will drop any existing table of the same name.
  *  	- 'error' will return false if the table already exists.
+ *
  * @param string $table_name
- * @param array $columns, in the format specified.
- * @param array $indexes, default array(), in the format specified.
- * @param array $parameters, default array()
- * @param string $if_exists, default 'ignore'
- * @param string $error, default 'fatal'
+ * @param array $columns in the format specified.
+ * @param array $indexes default array(), in the format specified.
+ * @param array $parameters default array()
+ * @param string $if_exists default 'ignore'
+ * @param string $error default 'fatal'
  */
 function smf_db_create_table($table_name, $columns, $indexes = array(), $parameters = array(), $if_exists = 'ignore', $error = 'fatal')
 {
@@ -192,9 +193,10 @@ function smf_db_create_table($table_name, $columns, $indexes = array(), $paramet
 
 /**
  * Drop a table.
+ *
  * @param string $table_name
- * @param array $parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param string $error default 'fatal'
  */
 function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 {
@@ -248,11 +250,12 @@ function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 
 /**
  * This function adds a column.
- * @param string $table_name, the name of the table
- * @param array $column_info, with column information
- * @param array $parameters, default array()
- * @param string $if_exists, default 'update'
- * @param string $error, default 'fatal'
+ *
+ * @param string $table_name the name of the table
+ * @param array $column_info with column information
+ * @param array $parameters default array()
+ * @param string $if_exists default 'update'
+ * @param string $error default 'fatal'
  */
 function smf_db_add_column($table_name, $column_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -302,10 +305,11 @@ function smf_db_add_column($table_name, $column_info, $parameters = array(), $if
 
 /**
  * Removes a column.
+ *
  * @param string $table_name
  * @param string $column_name
- * @param array $parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param string $error default 'fatal'
  */
 function smf_db_remove_column($table_name, $column_name, $parameters = array(), $error = 'fatal')
 {
@@ -344,11 +348,12 @@ function smf_db_remove_column($table_name, $column_name, $parameters = array(),
 
 /**
  * Change a column.
+ *
  * @param string $table_name
  * @param $old_column
  * @param $column_info
- * @param array $parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param string $error default 'fatal'
  */
 function smf_db_change_column($table_name, $old_column, $column_info, $parameters = array(), $error = 'fatal')
 {
@@ -500,11 +505,12 @@ function smf_db_change_column($table_name, $old_column, $column_info, $parameter
 
 /**
  * Add an index.
+ *
  * @param string $table_name
  * @param array $index_info
- * @param array $parameters, default array()
- * @param string $if_exists, default 'update'
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param string $if_exists default 'update'
+ * @param string $error default 'fatal'
  */
 function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -571,10 +577,11 @@ function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_e
 
 /**
  * Remove an index.
+ *
  * @param string $table_name
  * @param string $index_name
- * @param array$parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array$parameters default array()
+ * @param string $error default 'fatal'
  */
 function smf_db_remove_index($table_name, $index_name, $parameters = array(), $error = 'fatal')
 {
@@ -623,6 +630,7 @@ function smf_db_remove_index($table_name, $index_name, $parameters = array(), $e
 
 /**
  * Get the schema formatted name for a type.
+ *
  * @param string $type_name
  * @param $type_size
  * @param $reverse
@@ -669,8 +677,9 @@ function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 
 /**
  * Get table structure.
+ *
  * @param string $table_name
- * @param array $parameters, default array()
+ * @param array $parameters default array()
  */
 function smf_db_table_structure($table_name, $parameters = array())
 {
@@ -687,9 +696,10 @@ function smf_db_table_structure($table_name, $parameters = array())
 
 /**
  * Return column information for a table.
+ *
  * @param string $table_name
  * @param bool $detail
- * @param array $parameters, default array()
+ * @param array $parameters default array()
  * @return mixed
  */
 function smf_db_list_columns($table_name, $detail = false, $parameters = array())
@@ -748,6 +758,7 @@ function smf_db_list_columns($table_name, $detail = false, $parameters = array()
 
 /**
  * Get index information.
+ *
  * @param string $table_name
  * @param bool $detail
  * @param array $parameters

Sources/DbPackages-sqlite.php

@@ -83,12 +83,13 @@ function db_packages_init()
  *  	- 'ignore' will do nothing if the table exists. (And will return true)
  *  	- 'overwrite' will drop any existing table of the same name.
  *  	- 'error' will return false if the table already exists.
+ *
  * @param string $table_name
- * @param array $columns, in the format specified.
- * @param array $indexes, default array(), in the format specified.
- * @param array $parameters, default array()
- * @param string $if_exists, default 'ignore'
- * @param string $error, default 'fatal'
+ * @param array $columns in the format specified.
+ * @param array $indexes default array(), in the format specified.
+ * @param array $parameters default array()
+ * @param string $if_exists default 'ignore'
+ * @param string $error default 'fatal'
  */
 function smf_db_create_table($table_name, $columns, $indexes = array(), $parameters = array(), $if_exists = 'ignore', $error = 'fatal')
 {
@@ -196,9 +197,11 @@ function smf_db_create_table($table_name, $columns, $indexes = array(), $paramet
 
 /**
  * Drop a table.
+ *
  * @param string $table_name
- * @param array $parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param bool $error
+ * @param string $error default 'fatal'
  */
 function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 {
@@ -232,11 +235,12 @@ function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 
 /**
  * This function adds a column.
- * @param string $table_name, the name of the table
- * @param array $column_info, with column information
- * @param array $parameters, default array()
- * @param string $if_exists, default 'update'
- * @param string $error, default 'fatal'
+ *
+ * @param string $table_name the name of the table
+ * @param array $column_info with column information
+ * @param array $parameters default array()
+ * @param string $if_exists default 'update'
+ * @param string $error default 'fatal'
  */
 function smf_db_add_column($table_name, $column_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -268,11 +272,12 @@ function smf_db_add_column($table_name, $column_info, $parameters = array(), $if
 
 /**
  * Removes a column.
+ *
  * We can't reliably do this on SQLite - damn!
  * @param string $table_name
  * @param string $column_name
- * @param array $parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param string $error default 'fatal'
  */
 function smf_db_remove_column($table_name, $column_name, $parameters = array(), $error = 'fatal')
 {
@@ -288,11 +293,12 @@ function smf_db_remove_column($table_name, $column_name, $parameters = array(),
 
 /**
  * Change a column.
+ *
  * @param string $table_name
  * @param $old_column
  * @param $column_info
- * @param array $parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param string $error default 'fatal'
  */
 function smf_db_change_column($table_name, $old_column, $column_info, $parameters = array(), $error = 'fatal')
 {
@@ -308,11 +314,12 @@ function smf_db_change_column($table_name, $old_column, $column_info, $parameter
 
 /**
  * Add an index.
+ *
  * @param string $table_name
  * @param array $index_info
- * @param array $parameters, default array()
- * @param string $if_exists, default 'update'
- * @param string $error, default 'fatal'
+ * @param array $parameters default array()
+ * @param string $if_exists default 'update'
+ * @param string $error default 'fatal'
  */
 function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -373,10 +380,11 @@ function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_e
 
 /**
  * Remove an index.
+ *
  * @param string $table_name
  * @param string $index_name
- * @param array$parameters, default array()
- * @param string $error, default 'fatal'
+ * @param array$parameters default array()
+ * @param string $error default 'fatal'
  */
 function smf_db_remove_index($table_name, $index_name, $parameters = array(), $error = 'fatal')
 {
@@ -410,6 +418,7 @@ function smf_db_remove_index($table_name, $index_name, $parameters = array(), $e
 
 /**
  * Get the schema formatted name for a type.
+ *
  * @param string $type_name
  * @param $type_size
  * @param $reverse
@@ -451,8 +460,9 @@ function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 
 /**
  * Get table structure.
+ *
  * @param string $table_name
- * @param array $parameters, default array()
+ * @param array $parameters default array()
  */
 function smf_db_table_structure($table_name, $parameters = array())
 {
@@ -470,9 +480,10 @@ function smf_db_table_structure($table_name, $parameters = array())
 /**
  * Return column information for a table.
  * Harder than it should be, on sqlite!
+ *
  * @param string $table_name
  * @param bool $detail
- * @param array $parameters, default array()
+ * @param array $parameters default array()
  * @return mixed
  */
 function smf_db_list_columns($table_name, $detail = false, $parameters = array())
@@ -535,6 +546,7 @@ function smf_db_list_columns($table_name, $detail = false, $parameters = array()
 
 /**
  * Get index information.
+ *
  * @param string $table_name
  * @param bool $detail
  * @param array $parameters
@@ -596,6 +608,7 @@ function smf_db_list_indexes($table_name, $detail = false, $parameters = array()
 
 /**
  * Alter table on SQLite.
+ *
  * @param string $table_name
  * @param array $columns
  */

Sources/DbSearch-postgresql.php

@@ -49,7 +49,7 @@ function smf_db_search_support($search_type)
  *
  * @param string $identifier
  * @param string $db_string
- * @param array $db_values, default array()
+ * @param array $db_values default array()
  * @param resource $connection
  */
 function smf_db_search_query($identifier, $db_string, $db_values = array(), $connection = null)

Sources/DbSearch-sqlite.php

@@ -49,7 +49,7 @@ function smf_db_search_support($search_type)
  *
  * @param string $identifier
  * @param string $db_string
- * @param array $db_values, default array()
+ * @param array $db_values default array()
  * @param resource $connection
  */
 function smf_db_search_query($identifier, $db_string, $db_values = array(), $connection = null)

Sources/Display.php

@@ -1166,7 +1166,8 @@ function Display()
  * It actually gets and prepares the message context.
  * This function will start over from the beginning if reset is set to true, which is
  * useful for showing an index before or after the posts.
- * @param bool $reset, default false.
+ *
+ * @param bool $reset default false.
  */
 function prepareDisplayContext($reset = false)
 {
@@ -1511,11 +1512,14 @@ function Download()
 
 /**
  * This loads an attachment's contextual data including, most importantly, its size if it is an image.
- *  Pre-condition: $attachments array to have been filled with the proper attachment data, as Display() does.
- *  (@todo change this pre-condition, too fragile and error-prone.)
- *  It requires the view_attachments permission to calculate image size.
- *  It attempts to keep the "aspect ratio" of the posted image in line, even if it has to be resized by
- *  the max_image_width and max_image_height settings.
+ * Pre-condition: $attachments array to have been filled with the proper attachment data, as Display() does.
+ * (@todo change this pre-condition, too fragile and error-prone.)
+ * It requires the view_attachments permission to calculate image size.
+ * It attempts to keep the "aspect ratio" of the posted image in line, even if it has to be resized by
+ * the max_image_width and max_image_height settings.
+ *
+ * @param type $id_msg message number to load attachments for
+ * @return array of attachemnts
  */
 function loadAttachmentContext($id_msg)
 {

Sources/Drafts.php

@@ -23,7 +23,9 @@ loadLanguage('Drafts');
  * Saves a post draft in the user_drafts table
  * The core draft feature must be enabled, as well as the post draft option
  * Determines if this is a new or an existing draft
+ * Returns errors in $post_errors for display in the template
  *
+ * @param string $post_errors
  * @return boolean
  */
 function SaveDraft(&$post_errors)
@@ -659,7 +661,6 @@ function showProfileDrafts($memID, $draft_type = 0)
  * Allows for the deleting and loading/editing of drafts
  *
  * @param type $memID
- * @param type $draft_type
  */
 function showPMDrafts($memID = -1)
 {

Sources/Errors.php

@@ -23,6 +23,7 @@ if (!defined('SMF'))
  * filename and line should be __FILE__ and __LINE__, respectively.
  * Example use:
  *  die(log_error($msg));
+ *
  * @param string $error_message
  * @param string $error_type = 'general'
  * @param string $file = null
@@ -257,9 +258,10 @@ function error_handler($error_level, $error_string, $file, $line)
 
 /**
  * It is called by fatal_error() and fatal_lang_error().
- * @uses Errors template, fatal_error sub template, or Wireless template,
- * error sub template.
+ * @uses Errors template, fatal_error sub template, or Wireless template, error sub template.
+ * 
  * @param string $error_message
+ * @param type $error_code
  */
 function setup_fatal_error_context($error_message, $error_code)
 {

Sources/Karma.php

@@ -151,7 +151,9 @@ function ModifyKarma()
 	}
 }
 
-//  What's this?  I dunno, what are you talking about?  Never seen this before, nope.  No sir.
+/**
+ * What's this?  I dunno, what are you talking about?  Never seen this before, nope.  No sir.
+ */
 function BookOfUnknown()
 {
 	global $context;

Sources/Load.php

@@ -1038,7 +1038,7 @@ function loadMemberData($users, $is_name = false, $set = 'normal')
  *
  * @param int $user
  * @param bool $display_custom_fields = false
- * @return bool
+ * @return boolean
  */
 function loadMemberContext($user, $display_custom_fields = false)
 {
@@ -1786,7 +1786,7 @@ function loadTheme($id_theme = 0, $initialize = true)
  * @param string $template_name
  * @param array $style_sheets = array()
  * @param bool $fatal = true if fatal is true, dies with an error message if the template cannot be found
- * @return bool
+ * @return boolean
  */
 function loadTemplate($template_name, $style_sheets = array(), $fatal = true)
 {

Sources/LogInOut.php

@@ -571,7 +571,7 @@ function DoLogin()
  * It redirects back to $_SESSION['logout_url'], if it exists.
  * It is accessed via ?action=logout;session_var=...
  *
- * @param bool $internal, if true, it doesn't check the session
+ * @param bool $internal if true, it doesn't check the session
  * @param $redirect
  */
 function Logout($internal = false, $redirect = true)

Sources/Logging.php

@@ -329,7 +329,7 @@ function displayDebug()
  * It depends on the trackStats setting.
  *
  * @param array $stats = array()
- * @return bool|array
+ * @return boolean|array
  */
 function trackStats($stats = array())
 {
@@ -389,9 +389,10 @@ function trackStats($stats = array())
  * @example logAction('remove', array('starter' => $id_member_started));
  *
  * @deprecated deprecated since version 2.1
+ *
  * @param string $action
  * @param array $extra = array()
- * @param string $log_type, options 'moderate', 'admin', ...etc.
+ * @param string $log_type options: 'moderate', 'admin', ...etc.
  */
 function logAction($action, $extra = array(), $log_type = 'moderate')
 {

Sources/ManageAttachments.php

@@ -557,7 +557,7 @@ function BrowseFiles()
  * @param int $start
  * @param int $items_per_page
  * @param string $sort
- * @param string $browse_type, can be 'avatars' or ... not. :P
+ * @param string $browse_type can be on eof 'avatars' or ... not. :P
  */
 function list_getFiles($start, $items_per_page, $sort, $browse_type)
 {
@@ -616,8 +616,7 @@ function list_getFiles($start, $items_per_page, $sort, $browse_type)
  * Return the number of files of the specified type recorded in the database.
  * (the specified type being attachments or avatars).
  *
- * @param string $browse_type, can be 'avatars' or not. (in which case they're
- * attachments)
+ * @param string $browse_type can be one of 'avatars' or not. (in which case they're attachments)
  */
 function list_getNumFiles($browse_type)
 {
@@ -2581,6 +2580,9 @@ function attachDirStatus($dir, $expected_files)
 		return array('ok', false, $num_files);
 }
 
+/**
+ * Maintance function to move attachments from one directory to another
+ */
 function TransferAttachments()
 {
 	global $modSettings, $context, $smcFunc, $sourcedir, $txt, $boarddir;

Sources/ManageBans.php

@@ -328,6 +328,11 @@ function list_getBans($start, $items_per_page, $sort)
 	return $bans;
 }
 
+/**
+ * Get the total number of ban from the ban group table
+ *
+ * @return int
+ */
 function list_getNumBans()
 {
 	global $smcFunc;
@@ -1625,8 +1630,8 @@ function list_getNumBanLogEntries()
  * @example
  * range2ip(array(10, 10, 10, 0), array(10, 10, 20, 255)) returns '10.10.10-20.*
  *
- * @param array $low, IPv4 format
- * @param array $high, IPv4 format
+ * @param array $low IPv4 format
+ * @param array $high IPv4 format
  * @return string
  */
 function range2ip($low, $high)
@@ -1681,7 +1686,7 @@ function range2ip($low, $high)
  *
  * @param array $ip_array
  * @param string $fullip
- * @return bool
+ * @return boolean
  */
 function checkExistingTriggerIP($ip_array, $fullip = '')
 {

Sources/ManageBoards.php

@@ -20,8 +20,7 @@ if (!defined('SMF'))
  * The main dispatcher; doesn't do anything, just delegates.
  * This is the main entry point for all the manageboards admin screens.
  * Called by ?action=admin;area=manageboards.
- * It checks the permissions, based on the sub-action, and calls a function
- *  based on the sub-action.
+ * It checks the permissions, based on the sub-action, and calls a function based on the sub-action.
  *
  *  @uses ManageBoards language file.
  */
@@ -369,7 +368,6 @@ function EditCategory2()
  * uses the modify_board sub-template of the ManageBoards template.
  * requires manage_boards permission.
  * also used to show the confirm deletion of category screen (sub-template confirm_board_delete).
-		  (sub-template confirm_board_delete).
 
  */
 function EditBoard()
@@ -726,6 +724,9 @@ function EditBoard2()
 		redirectexit('action=admin;area=manageboards');
 }
 
+/**
+ * Used to retrieve data for modifying a board category
+ */
 function ModifyCat()
 {
 	global $cat_tree, $boardList, $boards, $sourcedir, $smcFunc;

Sources/ManageLanguages.php

@@ -137,6 +137,12 @@ function AddLanguage()
 	$context['sub_template'] = 'add_language';
 }
 
+/**
+ * Gets a list of available languages from the mother ship
+ * Will return a subset if searching, otherwise all avaialble
+ *
+ * @return string
+ */
 function list_getLanguagesList()
 {
 	global $forum_version, $context, $sourcedir, $smcFunc, $txt, $scripturl;
@@ -214,7 +220,7 @@ function DownloadLanguage()
 
 		$chmod_files = array();
 		$install_files = array();
-		
+
 		// Check writable status.
 		foreach ($_POST['copy_file'] as $file)
 		{

Sources/ManageMaintenance.php

@@ -366,7 +366,9 @@ function MaintainEmptyUnimportantLogs()
 	$context['maintenance_finished'] = $txt['maintain_logs'];
 }
 
-// Oh noes!
+/**
+ * Oh noes! I'd document this but that would give it away
+ */
 function Destroy()
 {
 	global $context;

Sources/ManageNews.php

@@ -265,6 +265,11 @@ function EditNews()
 	$context['default_list'] = 'news_lists';
 }
 
+/**
+ * Prepares an array of the forum news items for display in the template
+ *
+ * @return array
+ */
 function list_getNews()
 {
 	global $modSettings;

Sources/ManagePermissions.php

@@ -1393,7 +1393,7 @@ function setPermissionLevel($level, $group, $profile = 'null')
  * Load permissions into $context['permissions'].
  * @internal
  *
- * @param string $loadType, options: 'classic' or 'simple'
+ * @param string $loadType options: 'classic' or 'simple'
  */
 function loadAllPermissions($loadType = 'classic')
 {

Sources/ManageSearch.php

@@ -745,6 +745,10 @@ function loadSearchAPIs()
 	return $apis;
 }
 
+/**
+ * Checks if the message table already has a fulltext index created and returns the key name
+ * Determines if a db is capable of creating a fulltext index
+ */
 function detectFulltextIndex()
 {
 	global $smcFunc, $context, $db_prefix;

Sources/ManageSearchEngines.php

@@ -1020,6 +1020,11 @@ function SpiderStats()
 
 /**
  * Callback function for createList()
+ * Get a list of spider stats from the log_spider table
+ *
+ * @param type $start
+ * @param type $items_per_page
+ * @param type $sort
  * @return array
  */
 function list_getSpiderStats($start, $items_per_page, $sort)
@@ -1045,6 +1050,8 @@ function list_getSpiderStats($start, $items_per_page, $sort)
 
 /**
  * Callback function for createList()
+ * Get the number of spider stat rows from the log spicer stats table
+ *
  * @return int
  */
 function list_getNumSpiderStats()

Sources/ManageSettings.php

@@ -482,6 +482,8 @@ function ModifyCoreFeatures($return_config = false)
 }
 
 /**
+ * Config array for chaning the basic forum settings
+ * Accessed  from ?action=admin;area=featuresettings;sa=basic;
  *
  * @param $return_config
  */
@@ -624,6 +626,8 @@ function ModifyGeneralSecuritySettings($return_config = false)
 }
 
 /**
+ * Allows modifying the global layout settings in the forum
+ * Accessed through ?action=admin;area=featuresettings;sa=layout;
  *
  * @param $return_config
  */
@@ -676,6 +680,8 @@ function ModifyLayoutSettings($return_config = false)
 }
 
 /**
+ * Config array for chaning the karma settings
+ * Accessed  from ?action=admin;area=featuresettings;sa=karma;
  *
  * @param $return_config
  */
@@ -2191,6 +2197,11 @@ function ModifyGeneralModSettings($return_config = false)
 	prepareDBSettingContext($config_vars);
 }
 
+/**
+ * Generates a list of integration hooks for display
+ * Accessed through ?action=admin;area=modsettings;sa=hooks;
+ * Allows for removal or disabing of selected hooks
+ */
 function list_integration_hooks()
 {
 	global $sourcedir, $scripturl, $context, $txt, $modSettings, $settings;
@@ -2369,6 +2380,12 @@ function list_integration_hooks()
 	$context['default_list'] = 'list_integration_hooks';
 }
 
+/**
+ * Gets all of the files in a directory and its chidren directories
+ *
+ * @param type $dir_path
+ * @return array
+ */
 function get_files_recursive($dir_path)
 {
 	$files = array();
@@ -2391,6 +2408,16 @@ function get_files_recursive($dir_path)
 	return $files;
 }
 
+/**
+ * Callback function for the integration hooks list (list_integration_hooks)
+ * Gets all of the hooks in the system and their status
+ * Would be better documented if Ema was not lazy
+ *
+ * @param type $start
+ * @param type $per_page
+ * @param type $sort
+ * @return array
+ */
 function get_integration_hooks_data($start, $per_page, $sort)
 {
 	global $boarddir, $sourcedir, $settings, $txt, $context, $scripturl, $modSettings;
@@ -2549,6 +2576,13 @@ function get_integration_hooks_data($start, $per_page, $sort)
 	return $hooks_data;
 }
 
+/**
+ * Simply returns the total count of integraion hooks
+ * Used but the intergation hooks list function (list_integration_hooks)
+ *
+ * @global type $context
+ * @return int
+ */
 function get_integration_hooks_count()
 {
 	global $context;
@@ -2569,6 +2603,12 @@ function get_integration_hooks_count()
 	return $hooks_count;
 }
 
+/**
+ * Parses modSettings to create integration hook array
+ * 
+ * @staticvar type $integration_hooks
+ * @return type
+ */
 function get_integration_hooks()
 {
 	global $modSettings;

Sources/MoveTopic.php

@@ -384,7 +384,16 @@ function MoveTopic2()
 		redirectexit('topic=' . $topic . '.0');
 }
 
-// Moves one or more topics to a specific board. (doesn't check permissions.)
+/**
+ * Moves one or more topics to a specific board. (doesn't check permissions.)
+ * Determines the source boards for the supplied topics
+ * Handles the moving of mark_read data
+ * Updates the posts count of the affected boards
+ *
+ * @param type $topics
+ * @param type $toBoard
+ * @return type
+ */
 function moveTopics($topics, $toBoard)
 {
 	global $sourcedir, $user_info, $modSettings, $smcFunc;
@@ -702,6 +711,10 @@ function moveTopics($topics, $toBoard)
 	));
 }
 
+/**
+ * Called after a topic is moved to update $board_link and $topic_link to point to new location
+ *
+ */
 function moveTopicConcurrence()
 {
 	global $board, $topic, $smcFunc, $scripturl;

Sources/News.php

@@ -348,6 +348,13 @@ function ShowXmlFeed()
 	obExit(false);
 }
 
+/**
+ * Called from dumpTags to convert data to xml
+ * Finds urls for local sitte and santizes them
+ *
+ * @param type $val
+ * @return type
+ */
 function fix_possible_url($val)
 {
 	global $modSettings, $context, $scripturl;
@@ -364,6 +371,14 @@ function fix_possible_url($val)
 	return $val;
 }
 
+/**
+ * Ensures supplied data is properly encpsulated in cdata xml tags
+ * Called from getXmlProfile in News.php
+ *
+ * @param type $data
+ * @param type $ns
+ * @return type
+ */
 function cdata_parse($data, $ns = '')
 {
 	global $smcFunc, $cdata_override;
@@ -438,9 +453,9 @@ function cdata_parse($data, $ns = '')
  * Additionally formats data based on the specific format passed.
  * This function is recursively called to handle sub arrays of data.
 
- * @param array $data, the array to output as xml data
- * @param int $i, the amount of indentation to use.
- * @param string $tag, if specified, it will be used instead of the keys of data.
+ * @param array $data the array to output as xml data
+ * @param int $i the amount of indentation to use.
+ * @param string $tag if specified, it will be used instead of the keys of data.
  * @param string $xml_format
  */
 function dumpTags($data, $i, $tag = null, $xml_format = '')

Sources/Packages.php

@@ -1117,6 +1117,13 @@ function PackageInstall()
 			{
 				// We're really just checking for entries which are create table AND add columns (etc).
 				$tables = array();
+				/**
+				 * Table sorting function used in usort
+				 *
+				 * @param type $a
+				 * @param type $b
+				 * @return int
+				 */
 				function sort_table_first($a, $b)
 				{
 					if ($a[0] == $b[0])
@@ -1503,6 +1510,18 @@ function PackageBrowse()
 	$context['available_all'] = array();
 }
 
+/**
+ * Get a listing of all the packages
+ * Determines if the package is a mod, avatar, language package
+ * Determines if the package has been installed or not
+ *
+ * @param type $start
+ * @param type $items_per_page
+ * @param type $sort
+ * @param type $params
+ * @param type $installed
+ * @return type
+ */
 function list_getPackages($start, $items_per_page, $sort, $params, $installed)
 {
 	global $boarddir, $scripturl, $context, $forum_version;
@@ -1767,6 +1786,9 @@ function list_getPackages($start, $items_per_page, $sort, $params, $installed)
 	return $packages[$params];
 }
 
+/**
+ * Used when a temp FTP access is needed to package functions
+ */
 function PackageOptions()
 {
 	global $txt, $scripturl, $context, $sourcedir, $modSettings, $smcFunc;
@@ -2201,6 +2223,14 @@ function PackagePermissions()
 	}
 }
 
+/**
+ * Checkes the permissions of all the areas that will be affected by the package
+ *
+ * @param type $path
+ * @param type $data
+ * @param type $level
+ * @return type
+ */
 function fetchPerms__recursive($path, &$data, $level)
 {
 	global $context;
@@ -2480,6 +2510,12 @@ function PackagePermissionsAction()
 		// Haven't counted the items yet?
 		if (empty($context['total_items']))
 		{
+			/**
+			 * Counts all the directorys under a given path
+			 *
+			 * @param type $dir
+			 * @return integer
+			 */
 			function count_directories__recursive($dir)
 			{
 				global $context;
@@ -2515,6 +2551,13 @@ function PackagePermissionsAction()
 		if (!isset($_POST['specialFiles']) && $context['predefined_type'] != 'free')
 		{
 			$context['special_files'] = array();
+
+			/**
+			 * Builds a list of special files recusivly for a given path
+			 *
+			 * @param type $path
+			 * @param type $data
+			 */
 			function build_special_files__recursive($path, &$data)
 			{
 				global $context;

Sources/PersonalMessage.php

@@ -2628,7 +2628,7 @@ function MessagePrune()
 /**
  * Delete the specified personal messages.
  *
- * @param array $personal_messages, array of pm ids
+ * @param array $personal_messages array of pm ids
  * @param string $folder = null
  * @param int $owner = null
  */
@@ -3660,7 +3660,7 @@ function LoadRules($reload = false)
  *
  * @param int $pmID
  * @param $validFor
- * @return bool
+ * @return boolean
  */
 function isAccessiblePM($pmID, $validFor = 'in_or_outbox')
 {

Sources/Post.php

@@ -26,6 +26,8 @@ if (!defined('SMF'))
  * - requires different permissions depending on the actions, but most notably post_new, post_reply_own, and post_reply_any.
  * - shows options for the editing and posting of calendar events and attachments, as well as the posting of polls.
  * - accessed from ?action=post.
+ *
+ *  @param array $post_errors holds any errors found tyring to post
  */
 function Post($post_errors = array())
 {

Sources/PostModeration.php

@@ -602,13 +602,10 @@ function list_getUnapprovedAttachments($start, $items_per_page, $sort, $approve_
 
 /**
  * Callback function for UnapprovedAttachments
- * count all the attachments waiting for approval the approver can approve
+ * count all the attachments waiting for approval that this approver can approve
  *
- * @param int $start
- * @param int $items_per_page
- * @param string $sort
  * @param string $approve_query additional restrictions based on the boards the approver can see
- * @return int, the number of unapproved attachments
+ * @return int the number of unapproved attachments
  */
 function list_getNumUnapprovedAttachments($approve_query)
 {

Sources/Profile-Actions.php

@@ -473,7 +473,7 @@ function list_getUserWarningCount($memID)
  * @param int $start
  * @param int $items_per_page
  * @param string $sort
- * @param int $memID, the member ID
+ * @param int $memID the member ID
  * @return array the preview warnings
  */
 function list_getUserWarnings($start, $items_per_page, $sort, $memID)
@@ -516,7 +516,7 @@ function list_getUserWarnings($start, $items_per_page, $sort, $memID)
 /**
  * Present a screen to make sure the user wants to be deleted
  *
- * @param int $memID, the member ID
+ * @param int $memID the member ID
  */
 function deleteAccount($memID)
 {
@@ -538,7 +538,7 @@ function deleteAccount($memID)
 /**
  * Actually delete an account.
  *
- * @param int $memID, the member ID
+ * @param int $memID the member ID
  */
 function deleteAccount2($memID)
 {

Sources/Profile-Modify.php

@@ -2334,7 +2334,7 @@ function ignoreboards($memID)
 
 /**
  * Load all the languages for the profile.
- * @return bool
+ * @return boolean
  */
 function profileLoadLanguages()
 {
@@ -2892,7 +2892,7 @@ function profileSaveAvatarData(&$value)
  * Validate the signature
  *
  * @param mixed &$value
- * @return bool|string
+ * @return boolean|string
  */
 function profileValidateSignature(&$value)
 {
@@ -3076,7 +3076,7 @@ function profileValidateSignature(&$value)
  *
  * @param string $email
  * @param int $memID = 0
- * @return bool|string
+ * @return boolean|string
  */
 function profileValidateEmail($email, $memID = 0)
 {

Sources/Profile-View.php

@@ -619,6 +619,16 @@ function showAttachments($memID)
 
 }
 
+/**
+ * Get a list of attachments for this user
+ *
+ * @param type $start
+ * @param type $items_per_page
+ * @param type $sort
+ * @param type $boardsAllowed
+ * @param type $memID
+ * @return type
+ */
 function list_getAttachments($start, $items_per_page, $sort, $boardsAllowed, $memID)
 {
 	global $smcFunc, $board, $modSettings, $context;
@@ -670,6 +680,13 @@ function list_getAttachments($start, $items_per_page, $sort, $boardsAllowed, $me
 	return $attachments;
 }
 
+/**
+ * Gets the total number of attachments for the user
+ *
+ * @param type $boardsAllowed
+ * @param type $memID
+ * @return type
+ */
 function list_getNumAttachments($boardsAllowed, $memID)
 {
 	global $board, $smcFunc, $modSettings, $context;

Sources/QueryString.php

@@ -294,8 +294,9 @@ function cleanRequest()
 
 /**
  * Validates a IPv6 address. returns true if it is ipv6.
+ *
  * @param string $ip ip address to be validated
- * @return bool true|false
+ * @return boolean true|false
  */
 function isValidIPv6($ip)
 {
@@ -307,6 +308,7 @@ function isValidIPv6($ip)
 
 /**
  * Converts IPv6s to numbers.  This makes ban checks much easier.
+ *
  * @param string $ip ip address to be converted
  * @return array
  */
@@ -333,8 +335,10 @@ function convertIPv6toInts($ip)
 
 /**
  * Expands a IPv6 address to its full form.
- * @param string $ip ip address to be converted
- * @return bool/string expanded ipv6 address.
+ *
+ * @param type $addr
+ * @param type $strict_check checks lenght to expaned address for compliance
+ * @return boolean/string expanded ipv6 address.
  */
 function expandIPv6($addr, $strict_check = true)
 {
@@ -555,7 +559,7 @@ function cleanXml($string)
 }
 
 /**
- * @todo needs a description
+ * Escapes (replaces) characters in strings to make them safe for use in javascript
  *
  * @param string $string
  * @return string

Sources/RemoveTopic.php

@@ -3,7 +3,7 @@
 /**
  * The contents of this file handle the deletion of topics, posts, and related
  * paraphernalia.
- * 
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -1231,7 +1231,11 @@ function RestoreTopic()
 }
 
 /**
- * Take a load of messages from one place and stick them in a topic.
+ * Take a load of messages from one place and stick them in a topic
+ *
+ * @param array $msgs
+ * @param integer $from_topic
+ * @param integer $target_topic
  */
 function mergePosts($msgs = array(), $from_topic, $target_topic)
 {

Sources/RepairBoards.php

@@ -157,7 +157,9 @@ function pauseRepairProcess($to_fix, $current_step_description, $max_substep = 0
 	obExit();
 }
 
-// Load up all the tests we might want to do ;)
+/**
+ * Load up all the tests we might want to do ;)
+ */
 function loadForumTests()
 {
 	global $errorTests;

Sources/Reports.php

@@ -906,7 +906,7 @@ function addData($inc_data, $custom_table = null)
  * @param string $title = ''
  * @param string $custom_table = null
  *
- * @return bool returns false if there are no tables
+ * @return boolean returns false if there are no tables
  */
 function addSeparator($title = '', $custom_table = null)
 {

Sources/ScheduledTasks.php

@@ -842,7 +842,12 @@ function scheduled_weekly_digest()
 }
 
 /**
- * Send a bunch of emails from the mail queue.
+ * Send a group of emails from the mail queue.
+ *
+ * @param type $number the number to send each loop through
+ * @param type $override_limit bypassing our limit flaf
+ * @param type $force_send
+ * @return boolean
  */
 function ReduceMailQueue($number = false, $override_limit = false, $force_send = false)
 {
@@ -1043,6 +1048,9 @@ function ReduceMailQueue($number = false, $override_limit = false, $force_send =
 
 /**
  * Calculate the next time the passed tasks should be triggered.
+ *
+ * @param type $tasks
+ * @param type $forceUpdate
  */
 function CalculateNextTrigger($tasks = array(), $forceUpdate = false)
 {
@@ -1109,6 +1117,11 @@ function CalculateNextTrigger($tasks = array(), $forceUpdate = false)
 
 /**
  * Simply returns a time stamp of the next instance of these time parameters.
+ *
+ * @param int $regularity
+ * @param type $unit
+ * @param type $offset
+ * @return int
  */
 function next_time($regularity, $unit, $offset)
 {

Sources/SearchAPI-Custom.php

@@ -14,23 +14,58 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
+/**
+ * Custom Search API class .. used when custom SMF index is used
+ */
 class custom_search
 {
-	// This is the last version of SMF that this was tested on, to protect against API changes.
+	/**
+	 *This is the last version of SMF that this was tested on, to protect against API changes.
+	 * @var type
+	 */
 	public $version_compatible = 'SMF 2.1 Alpha 1';
-	// This won't work with versions of SMF less than this.
+
+	/**
+	 *This won't work with versions of SMF less than this.
+	 * @var type
+	 */
 	public $min_smf_version = 'SMF 2.1 Alpha 1';
-	// Is it supported?
+
+	/**
+	 * Is it supported?
+	 * @var type
+	 */
 	public $is_supported = true;
 
+	/**
+	 * Index Settings
+	 * @var type
+	 */
 	protected $indexSettings = array();
-	// What words are banned?
+
+	/**
+	 * What words are banned?
+	 * @var type
+	 */
 	protected $bannedWords = array();
-	// What is the minimum word length?
+
+	/**
+	 * What is the minimum word length?
+	 * @var type
+	 */
 	protected $min_word_length = null;
-	// What databases support the custom index?
+
+	/**
+	 * What databases support the custom index?
+	 * @var type
+	 */
 	protected $supported_databases = array('mysql', 'postgresql', 'sqlite');
 
+	/**
+	 * constructor function
+	 *
+	 * @return type
+	 */
 	public function __construct()
 	{
 		global $modSettings, $db_type;
@@ -51,7 +86,13 @@ class custom_search
 		$this->min_word_length = $this->indexSettings['bytes_per_word'];
 	}
 
-	// Check whether the search can be performed by this API.
+	/**
+	 * Check whether the search can be performed by this API.
+	 *
+	 * @param type $methodName
+	 * @param type $query_params
+	 * @return boolean
+	 */
 	public function supportsMethod($methodName, $query_params = null)
 	{
 		switch ($methodName)
@@ -72,7 +113,11 @@ class custom_search
 		}
 	}
 
-	// If the settings don't exist we can't continue.
+	/**
+	 * If the settings don't exist we can't continue.
+	 *
+	 * @return type
+	 */
 	public function isValid()
 	{
 		global $modSettings;
@@ -98,7 +143,14 @@ class custom_search
 		return $y < $x ? 1 : ($y > $x ? -1 : 0);
 	}
 
-	// Do we have to do some work with the words we are searching for to prepare them?
+	/**
+	 * Do we have to do some work with the words we are searching for to prepare them?
+	 *
+	 * @param type $word
+	 * @param type $wordsSearch
+	 * @param type $wordsExclude
+	 * @param type $isExcluded
+	 */
 	public function prepareIndexes($word, &$wordsSearch, &$wordsExclude, $isExcluded)
 	{
 		global $modSettings, $smcFunc;
@@ -125,7 +177,13 @@ class custom_search
 		}
 	}
 
-	// Search for indexed words.
+	/**
+	 * Search for indexed words.
+	 *
+	 * @param type $words
+	 * @param type $search_data
+	 * @return type
+	 */
 	public function indexedWordQuery($words, $search_data)
 	{
 		global $modSettings, $smcFunc;
@@ -212,7 +270,11 @@ class custom_search
 	}
 
 	/**
-	 * After a post is made, we update the search index database.
+	 *  After a post is made, we update the search index database
+	 *
+	 * @param type $msgOptions
+	 * @param type $topicOptions
+	 * @param type $posterOptions
 	 */
 	public function postCreated($msgOptions, $topicOptions, $posterOptions)
 	{
@@ -235,6 +297,10 @@ class custom_search
 
 	/**
 	 * After a post is modified, we update the search index database.
+	 *
+	 * @param type $msgOptions
+	 * @param type $topicOptions
+	 * @param type $posterOptions
 	 */
 	public function postModified($msgOptions, $topicOptions, $posterOptions)
 	{

Sources/SearchAPI-Fulltext.php

@@ -14,19 +14,46 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
+/**
+ * Fulltext API, used when an SQL fulltext index is used
+ */
 class fulltext_search
 {
-	// This is the last version of SMF that this was tested on, to protect against API changes.
+	/**
+	 * This is the last version of SMF that this was tested on, to protect against API changes.
+	 * @var type
+	 */
 	public $version_compatible = 'SMF 2.1 Alpha 1';
-	// This won't work with versions of SMF less than this.
+
+	/**
+	 * This won't work with versions of SMF less than this.
+	 * @var type
+	 */
 	public $min_smf_version = 'SMF 2.1 Alpha 1';
-	// Is it supported?
+
+	/**
+	 * Is it supported?
+	 *
+	 * @var type
+	 */
 	public $is_supported = true;
-	// What words are banned?
+
+	/**
+	 * What words are banned?
+	 * @var type
+	 */
 	protected $bannedWords = array();
-	// What is the minimum word length?
+
+	/**
+	 * What is the minimum word length?
+	 * @var type
+	 */
 	protected $min_word_length = 4;
-	// What databases support the fulltext index?
+
+	/**
+	 * What databases support the fulltext index?
+	 * @var type
+	 */
 	protected $supported_databases = array('mysql');
 
 	/**
@@ -104,11 +131,12 @@ class fulltext_search
 
 		return $min_word_length;
 	}
-	
+
 	/**
 	 * callback function for usort used to sort the fulltext results.
 	 * the order of sorting is: large words, small words, large words that
 	 * are excluded from the search, small words that are excluded.
+	 *
 	 * @param string $a Word A
 	 * @param string $b Word B
 	 * @return int
@@ -119,10 +147,10 @@ class fulltext_search
 
 		$x = $smcFunc['strlen']($a) - (in_array($a, $excludedWords) ? 1000 : 0);
 		$y = $smcFunc['strlen']($b) - (in_array($b, $excludedWords) ? 1000 : 0);
-		
+
 		return $x < $y ? 1 : ($x > $y ? -1 : 0);
 	}
-	
+
 	/**
 	 * fulltext_search::prepareIndexes()
 	 *

Sources/SearchAPI-Standard.php

@@ -14,18 +14,38 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
+/**
+ * Standard non full index, non custom index search
+ */
 class standard_search
 {
-	// This is the last version of SMF that this was tested on, to protect against API changes.
+	/**
+	 * This is the last version of SMF that this was tested on, to protect against API changes.
+	 *
+	 * @var type
+	 */
 	public $version_compatible = 'SMF 2.1 ALpha';
 
-	// This won't work with versions of SMF less than this.
+	/**
+	 * This won't work with versions of SMF less than this.
+	 *
+	 * @var type
+	 */
 	public $min_smf_version = 'SMF 2.1 Alpha 1';
 
-	// Standard search is supported by default.
+	/**
+	 * Standard search is supported by default.
+	 * @var type
+	 */
 	public $is_supported = true;
 
-	// Method to check whether the method can be performed by the API.
+	/**
+	 * Method to check whether the method can be performed by the API.
+	 *
+	 * @param type $methodName
+	 * @param type $query_params
+	 * @return boolean
+	 */
 	public function supportsMethod($methodName, $query_params = null)
 	{
 		// Always fall back to the standard search method.

Sources/Security.php

@@ -760,7 +760,7 @@ function createToken($action, $type = 'post')
  * @param string $action
  * @param string $type = 'post' (get, request, or post)
  * @param bool $reset = true
- * @return bool
+ * @return boolean
  */
 function validateToken($action, $type = 'post', $reset = true)
 {
@@ -848,7 +848,7 @@ function cleanTokens($complete = false)
  *
  * @param string $action
  * @param bool $is_fatal = true
- * @return bool
+ * @return boolean
  */
 function checkSubmitOnce($action, $is_fatal = true)
 {
@@ -894,7 +894,7 @@ function checkSubmitOnce($action, $is_fatal = true)
  *
  * @param string $permission
  * @param array $boards = null
- * @return bool if the user can do the permission
+ * @return boolean if the user can do the permission
  */
 function allowedTo($permission, $boards = null)
 {
@@ -1151,7 +1151,7 @@ function showEmailAddress($userProfile_hideEmail, $userProfile_id)
  * This function attempts to protect from spammed messages and the like.
  * The time taken depends on error_type - generally uses the modSetting.
  *
- * @param string $error_type, used also as a $txt index. (not an actual string.)
+ * @param string $error_type used also as a $txt index. (not an actual string.)
  * @return boolean
  */
 function spamProtection($error_type)
@@ -1210,9 +1210,9 @@ function spamProtection($error_type)
 /**
  * A generic function to create a pair of index.php and .htaccess files in a directory
  *
- * @param string $path, the (absolute) directory path
- * @param boolean $attachments, if the directory is an attachments directory or not
- * @return true on success, error string if anything fails
+ * @param string $path the (absolute) directory path
+ * @param boolean $attachments if the directory is an attachments directory or not
+ * @return true on success error string if anything fails
  */
 function secureDirectory($path, $attachments = false)
 {

Sources/Session.php

@@ -101,7 +101,7 @@ function loadSession()
  *
  * @param string $save_path
  * @param string $session_name
- * @return bool
+ * @return boolean
  */
 function sessionOpen($save_path, $session_name)
 {
@@ -112,7 +112,7 @@ function sessionOpen($save_path, $session_name)
  * Implementation of sessionClose() replacing the standard close handler.
  * It simply returns true.
  *
- * @return bool
+ * @return boolean
  */
 function sessionClose()
 {
@@ -153,7 +153,7 @@ function sessionRead($session_id)
  *
  * @param string $session_id
  * @param string $data
- * @return bool
+ * @return boolean
  */
 function sessionWrite($session_id, $data)
 {
@@ -190,7 +190,7 @@ function sessionWrite($session_id, $data)
  * Implementation of sessionDestroy() replacing the standard destroy handler.
  *
  * @param string $session_id
- * @return bool
+ * @return boolean
  */
 function sessionDestroy($session_id)
 {
@@ -214,7 +214,7 @@ function sessionDestroy($session_id)
  * Callback for garbage collection.
  *
  * @param int $max_lifetime
- * @return bool
+ * @return boolean
  */
 function sessionGC($max_lifetime)
 {

Sources/Subs-Admin.php

@@ -390,6 +390,8 @@ function updateSettingsFile($config_vars)
  * - Done separately from updateSettingsFile to avoid race conditions
  *   which can occur during a db error
  * - If it fails Settings.php will assume 0
+ *
+ * @param type $time
  */
 function updateDbLastError($time)
 {
@@ -441,6 +443,10 @@ function updateAdminPreferences()
  * - loads all users who are admins or have the admin forum permission.
  * - uses the email template and replacements passed in the parameters.
  * - sends them an email.
+ *
+ * @param string $template
+ * @param array $replacements
+ * @param array $additional_recipients
  */
 function emailAdmins($template, $replacements = array(), $additional_recipients = array())
 {

Sources/Subs-Auth.php

@@ -23,7 +23,7 @@ if (!defined('SMF'))
  * - sets the cookie and session to last the number of seconds specified by cookie_length.
  * - when logging out, if the globalCookies setting is enabled, attempts to clear the subdomain's cookie too.
  *
- * @param int $cookie_length,
+ * @param int $cookie_length
  * @param int $id The id of the member
  * @param string $password = ''
  */
@@ -110,7 +110,7 @@ function setLoginCookie($cookie_length, $id, $password = '')
  * - normally, local and global should be the localCookies and globalCookies settings, respectively.
  * - uses boardurl to determine these two things.
  *
- * @param bool $local,
+ * @param bool $local
  * @param bool $global
  * @return array an array to set the cookie on with domain and path in it, in that order
  */
@@ -250,8 +250,8 @@ function adminLogin($type = 'admin')
  * Used by the adminLogin() function.
  * if 'value' is an array, the function is called recursively.
  *
- * @param string $key
- * @param string $value
+ * @param string $k key
+ * @param string $v value
  * @return string 'hidden' HTML form fields, containing key-value-pairs
  */
 function adminLogin_outputPostVars($k, $v)
@@ -316,7 +316,7 @@ function construct_query_string($get)
  * - searches for members whose username, display name, or e-mail address match the given pattern of array names.
  * - searches only buddies if buddies_only is set.
  *
- * @param array $names,
+ * @param array $names
  * @param bool $use_wildcards = false, accepts wildcards ? and * in the patern if true
  * @param bool $buddies_only = false,
  * @param int $max = 500 retrieves a maximum of max members, if passed
@@ -588,8 +588,10 @@ function resetPassword($memID, $username = null)
 /**
  * Checks a username obeys a load of rules
  *
- * @param int $memID,
+ * @param int $memID
  * @param string $username
+ * @param boolean $return_error
+ * @param boolean $check_reserved_name
  * @return string Returns null if fine
  */
 function validateUsername($memID, $username, $return_error = false, $check_reserved_name = true)

Sources/Subs-Boards.php

@@ -1178,7 +1178,7 @@ function recursiveBoards(&$_boardList, &$_tree)
  * Returns whether the child board id is actually a child of the parent (recursive).
  * @param int $child
  * @param int $parent
- * @return bool
+ * @return boolean
  */
 function isChildOf($child, $parent)
 {

Sources/Subs-Calendar.php

@@ -16,30 +16,11 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/**
- void insertEvent(
- * inserts the passed event information into the calendar table.
- * allows to either set a time span (in days) or an end_date.
- * does not check any permissions of any sort.
- * @param array $eventOptions
-
- void modifyEvent(
- * modifies an event.
- * allows to either set a time span (in days) or an end_date.
- * does not check any permissions of any sort.
- * @param int $event_id
- * @param array $eventOptions
-
- void removeEvent(
- * removes an event.
- * does no permission checks.
- * @param int $event_id
-*/
-
 /**
  * Get all birthdays within the given time range.
  * finds all the birthdays in the specified range of days.
  * works with birthdays set for no year, or any other year, and respects month and year boundaries.
+ *
  * @param string $low_date inclusive, YYYY-MM-DD
  * @param string $high_date inclusive, YYYY-MM-DD
  * @return array days, each of which an array of birthday information for the context
@@ -109,8 +90,8 @@ function getBirthdayRange($low_date, $high_date)
  * - censors the posted event titles.
  * - uses the current user's permissions if use_permissions is true, otherwise it does nothing "permission specific"
  *
- * @param string $earliest_date
- * @param string $latest_date
+ * @param string $low_date
+ * @param string $high_date
  * @param bool $use_permissions = true
  * @return array contextual information if use_permissions is true, and an array of the data needed to build that otherwise
  */
@@ -214,6 +195,7 @@ function getEventRange($low_date, $high_date, $use_permissions = true)
 
 /**
  * Get all holidays within the given time range.
+ *
  * @param string $low_date YYYY-MM-DD
  * @param string $high_date YYYY-MM-DD
  * @return array an array of days, which are all arrays of holiday names.
@@ -608,6 +590,7 @@ function getCalendarWeek($month, $year, $day, $calendarOptions)
  * cache callback function used to retrieve the birthdays, holidays, and events between now and now + days_to_index.
  * widens the search range by an extra 24 hours to support time offset shifts.
  * used by the cache_getRecentEvents function to get the information needed to calculate the events taking the users time offset into account.
+ *
  * @param int $days_to_index
  * @return array
  */
@@ -842,6 +825,9 @@ function getEventPoster($event_id)
 
 /**
  * Consolidating the various INSERT statements into this function.
+ * inserts the passed event information into the calendar table.
+ * allows to either set a time span (in days) or an end_date.
+ * does not check any permissions of any sort.
  *
  * @param array $eventOptions
  */
@@ -898,8 +884,12 @@ function insertEvent(&$eventOptions)
 }
 
 /**
+ * modifies an event.
+ * allows to either set a time span (in days) or an end_date.
+ * does not check any permissions of any sort.
+ *
  * @param int $event_id
- * @param array &$eventOptions
+ * @param array $eventOptions
  */
 function modifyEvent($event_id, &$eventOptions)
 {
@@ -958,6 +948,9 @@ function modifyEvent($event_id, &$eventOptions)
 
 /**
  * Remove an event
+ * removes an event.
+ * does no permission checks.
+ *
  * @param int $event_id
  */
 function removeEvent($event_id)
@@ -980,6 +973,8 @@ function removeEvent($event_id)
 }
 
 /**
+ * Gets all the events properties
+ *
  * @param int $event_id
  * @return array
  */
@@ -1037,6 +1032,7 @@ function getEventProperties($event_id)
 }
 
 /**
+ * Gets all of the holidays for the listing
  *
  * @param int $start
  * @param int $items_per_page
@@ -1065,6 +1061,8 @@ function list_getHolidays($start, $items_per_page, $sort)
 }
 
 /**
+ * Helper function to get the total number of holidays
+ *
  * @return int
  */
 function list_getNumHolidays()
@@ -1084,6 +1082,8 @@ function list_getNumHolidays()
 }
 
 /**
+ * Remove a holdiay from the calendar
+ *
  * @param array $holiday_ids An array of
  */
 function removeHolidays($holiday_ids)

Sources/Subs-Categories.php

@@ -122,7 +122,6 @@ function modifyCategory($category_id, $catOptions)
  * allows (almost) the same options as the modifyCat() function.
  * returns the ID of the newly created category.
  *
- * @param int $createCategory
  * @param array $catOptions
  */
 function createCategory($catOptions)
@@ -147,7 +146,7 @@ function createCategory($catOptions)
 	$cat_parameters = array(
 		$catOptions['cat_name'],
 	);
-	
+
 	call_integration_hook('integrate_create_category', array(&$catOptions, &$cat_columns, &$cat_parameters));
 
 	// Add the category to the database.
@@ -178,8 +177,8 @@ function createCategory($catOptions)
  * deletes all information that's associated with the given categories.
  * updates the statistics to reflect the new situation.
  *
- * @param array $categories_to_remove
- * @param int $moveChildrenTo = null
+ * @param string $categories
+ * @param int $moveBoardsTo = null
  */
 function deleteCategories($categories, $moveBoardsTo = null)
 {

Sources/Subs-Db-mysql.php

@@ -19,11 +19,14 @@ if (!defined('SMF'))
 /**
  *  Maps the implementations in this file (smf_db_function_name)
  *  to the $smcFunc['db_function_name'] variable.
- *  @param string $db_server
- *  @param string $db_name
- *  @param string $db_user
- *  @param string $db_passwd
- *  @param array $db_options = array()
+ *
+ * @param string $db_server
+ * @param string $db_name
+ * @param string $db_user
+ * @param string $db_passwd
+ * @param string $db_prefix
+ * @param array $db_options
+ * @return null
  */
 function smf_db_initiate($db_server, $db_name, $db_user, $db_passwd, $db_prefix, $db_options = array())
 {
@@ -87,8 +90,7 @@ function smf_db_initiate($db_server, $db_name, $db_user, $db_passwd, $db_prefix,
  * Extend the database functionality. It calls the respective file's init
  * to add the implementations in that file to $smcFunc array.
  *
- * @param string $type, indicated which additional file to load.
- * ('extra', 'packages')
+ * @param string $type indicated which additional file to load. ('extra', 'packages')
  */
 function db_extend($type = 'extra')
 {
@@ -101,6 +103,7 @@ function db_extend($type = 'extra')
 
 /**
  * Fix up the prefix so it doesn't require the database to be selected.
+ *
  * @param string &db_prefix
  * @param string $db_name
  */
@@ -111,11 +114,9 @@ function db_fix_prefix(&$db_prefix, $db_name)
 
 /**
  * Callback for preg_replace_callback on the query.
- * It allows to replace on the fly a few pre-defined strings, for
- * convenience ('query_see_board', 'query_wanna_see_board'), with
+ * It allows to replace on the fly a few pre-defined strings, for convenience ('query_see_board', 'query_wanna_see_board'), with
  * their current values from $user_info.
- * In addition, it performs checks and sanitization on the values
- * sent to the database.
+ * In addition, it performs checks and sanitization on the values sent to the database.
  *
  * @param $matches
  */
@@ -224,8 +225,8 @@ function smf_db_replacement__callback($matches)
 }
 
 /**
- * Just like the db_query, escape and quote a string,
- * but not executing the query.
+ * Just like the db_query, escape and quote a string, but not executing the query.
+ *
  * @param string $db_string
  * @param array $db_values
  * @param resource $connection = null
@@ -252,6 +253,7 @@ function smf_db_quote($db_string, $db_values, $connection = null)
 
 /**
  * Do a query.  Takes care of errors too.
+ *
  * @param string $identifier
  * @param string $db_string
  * @param array $db_values = array()
@@ -650,7 +652,7 @@ function smf_db_error($db_string, $connection = null)
 /**
  * insert
  *
- * @param string $method, options 'replace', 'ignore', 'insert'
+ * @param string $method - options 'replace', 'ignore', 'insert'
  * @param $table
  * @param $columns
  * @param $data

Sources/Subs-Db-postgresql.php

@@ -17,9 +17,17 @@ if (!defined('SMF'))
 	die('Hacking attempt...');
 
 /**
- *  Maps the implementations in this file (smf_db_function_name)
- *  to the $smcFunc['db_function_name'] variable.
- *  @see Subs-Db-mysql.php#smf_db_initiate
+ * Maps the implementations in this file (smf_db_function_name)
+ * to the $smcFunc['db_function_name'] variable.
+ * @see Subs-Db-mysql.php#smf_db_initiate
+ *
+ * @param type $db_server
+ * @param type $db_name
+ * @param type $db_user
+ * @param type $db_passwd
+ * @param type $db_prefix
+ * @param type $db_options
+ * @return null
  */
 function smf_db_initiate($db_server, $db_name, $db_user, $db_passwd, &$db_prefix, $db_options = array())
 {
@@ -75,6 +83,7 @@ function smf_db_initiate($db_server, $db_name, $db_user, $db_passwd, &$db_prefix
 /**
  * Extend the database functionality. It calls the respective file's init
  * to add the implementations in that file to $smcFunc array.
+ *
  * @param string $type = 'extra'
  */
 function db_extend ($type = 'extra')
@@ -89,6 +98,10 @@ function db_extend ($type = 'extra')
 /**
  * Fix the database prefix if necessary.
  * Do nothing on postgreSQL
+ *
+ * @param type $db_prefix
+ * @param type $db_name
+ * @return type
  */
 function db_fix_prefix (&$db_prefix, $db_name)
 {
@@ -207,6 +220,11 @@ function smf_db_replacement__callback($matches)
 /**
  * Just like the db_query, escape and quote a string,
  * but not executing the query.
+ *
+ * @param string $db_string
+ * @param string $db_values
+ * @param type $connection
+ * @return type
  */
 function smf_db_quote($db_string, $db_values, $connection = null)
 {
@@ -232,6 +250,12 @@ function smf_db_quote($db_string, $db_values, $connection = null)
  * Do a query.  Takes care of errors too.
  * Special queries may need additional replacements to be appropriate
  * for PostgreSQL.
+ *
+ * @param string $identifier
+ * @param string $db_string
+ * @param string $db_values
+ * @param type $connection
+ * @return boolean
  */
 function smf_db_query($identifier, $db_string, $db_values = array(), $connection = null)
 {
@@ -644,7 +668,7 @@ function smf_db_unescape_string($string)
 /**
  * insert
  *
- * @param string $method, options 'replace', 'ignore', 'insert'
+ * @param string $method - options 'replace', 'ignore', 'insert'
  * @param $table
  * @param $columns
  * @param $data

Sources/Subs-Db-sqlite.php

@@ -19,6 +19,13 @@ if (!defined('SMF'))
 /**
  *  Maps the implementations in this file (smf_db_function_name)
  *  to the $smcFunc['db_function_name'] variable.
+ *
+ * @param string $db_server
+ * @param string $db_name
+ * @param string $db_user
+ * @param string $db_passwd
+ * @param string $db_prefix
+ * @param array $db_options
  */
 function smf_db_initiate($db_server, $db_name, $db_user, $db_passwd, $db_prefix, $db_options = array())
 {
@@ -90,7 +97,7 @@ function smf_db_initiate($db_server, $db_name, $db_user, $db_passwd, $db_prefix,
  * Extend the database functionality. It calls the respective file's init
  * to add the implementations in that file to $smcFunc array.
  *
- * @param string $type, indicated which additional file to load. ('extra', 'packages')
+ * @param string $type indicated which additional file to load. ('extra', 'packages')
  */
 function db_extend($type = 'extra')
 {
@@ -104,6 +111,9 @@ function db_extend($type = 'extra')
 /**
  * Fix db prefix if necessary.
  * SQLite doesn't actually need this!
+ *
+ * @param type $db_prefix
+ * @param type $db_name
  */
 function db_fix_prefix(&$db_prefix, $db_name)
 {
@@ -222,6 +232,10 @@ function smf_db_replacement__callback($matches)
 /**
  * Just like the db_query, escape and quote a string,
  * but not executing the query.
+ *
+ * @param string $db_string
+ * @param string $db_values
+ * @param resource $connection
  */
 function smf_db_quote($db_string, $db_values, $connection = null)
 {
@@ -245,6 +259,11 @@ function smf_db_quote($db_string, $db_values, $connection = null)
 
 /**
  * Do a query.  Takes care of errors too.
+ *
+ * @param string $identifier
+ * @param string $db_string
+ * @param string $db_values
+ * @param resource $connection
  */
 function smf_db_query($identifier, $db_string, $db_values = array(), $connection = null)
 {
@@ -391,6 +410,7 @@ function smf_db_query($identifier, $db_string, $db_values = array(), $connection
 
 /**
  * affected_rows
+ *
  * @param resource $connection
  */
 function smf_db_affected_rows($connection = null)

Sources/Subs-Editor.php

@@ -2232,6 +2232,11 @@ function AutoSuggest_Search_Member()
 	return $xml_data;
 }
 
+/**
+ * Provides a list of possible SMF versions to use in emulation
+ * 
+ * @return string
+ */
 function AutoSuggest_Search_SMFVersions()
 {
 

Sources/Subs-Graphics.php

@@ -29,11 +29,11 @@ if (!defined('SMF'))
  * - updates the database info for the member's avatar.
  * - returns whether the download and resize was successful.
  *
- * @param string $temporary_path, the full path to the temporary file
- * @param int $memID, member ID
+ * @param string $url the full path to the temporary file
+ * @param int $memID member ID
  * @param int $max_width
  * @param int $max_height
- * @return bool, whether the download and resize was successful.
+ * @return boolean whether the download and resize was successful.
  *
  */
 function downloadAvatar($url, $memID, $max_width, $max_height)
@@ -145,7 +145,7 @@ function downloadAvatar($url, $memID, $max_width, $max_height)
  * @param string $source
  * @param int $max_width
  * @param int $max_height
- * @return bool, whether the thumbnail creation was successful.
+ * @return boolean, whether the thumbnail creation was successful.
  */
 function createThumbnail($source, $max_width, $max_height)
 {
@@ -180,7 +180,7 @@ function createThumbnail($source, $max_width, $max_height)
  *
  * @param string $fileName
  * @param int $preferred_format = 0
- * @return bool, true on success, false on failure.
+ * @return boolean, true on success, false on failure.
  */
 function reencodeImage($fileName, $preferred_format = 0)
 {
@@ -277,6 +277,7 @@ function checkImagick()
 /**
  * See if we have enough memory to thumbnail an image
  *
+ * @param array $sizes image size
  * @return whether we do
  */
 function imageMemoryCheck($sizes)
@@ -733,7 +734,7 @@ if (!function_exists('imagecreatefrombmp'))
  * @param resource $gif
  * @param string $lpszFileName
  * @param int $background_color = -1
- * @return bool, whether it was successful or not.
+ * @return boolean, whether it was successful or not.
  */
 function gif_outputAsPng($gif, $lpszFileName, $background_color = -1)
 {

Sources/Subs-Membergroups.php

@@ -24,7 +24,7 @@ if (!defined('SMF'))
  * Deletes the permissions linked to the membergroup.
  * Takes members out of the deleted membergroups.
  * @param array $groups
- * @return bool
+ * @return boolean
  */
 function deleteMembergroups($groups)
 {
@@ -209,7 +209,7 @@ function deleteMembergroups($groups)
  * @param array $members
  * @param array $groups = null if groups is null, the specified members are stripped from all their membergroups.
  * @param bool $permissionCheckDone = false
- * @return bool
+ * @return boolean
  */
 function removeMembersFromGroups($members, $groups = null, $permissionCheckDone = false)
 {
@@ -434,7 +434,7 @@ function removeMembersFromGroups($members, $groups = null, $permissionCheckDone
  * 	- auto              - Assigns a membergroup to the primary group if it's still
  * 						  available. If not, assign it to the additional group.
  * @param bool $permissionCheckDone
- * @return bool success or failure
+ * @return boolean success or failure
  */
 function addMembersToGroup($members, $group, $type = 'auto', $permissionCheckDone = false)
 {
@@ -575,11 +575,13 @@ function addMembersToGroup($members, $group, $type = 'auto', $permissionCheckDon
 }
 
 /**
+ * Gets the members of a supplied membergroup
+ * Returns them as a link for display
  *
  * @param array &$members
  * @param int $membergroup
  * @param int $limit = null
- * @return bool
+ * @return boolean
  */
 function listMembergroupMembers_Href(&$members, $membergroup, $limit = null)
 {
@@ -609,7 +611,13 @@ function listMembergroupMembers_Href(&$members, $membergroup, $limit = null)
 		return false;
 }
 
-// Retrieve a list of (visible) membergroups used by the cache.
+/**
+ * Retrieve a list of (visible) membergroups used by the cache.
+ *
+ * @global type $scripturl
+ * @global type $smcFunc
+ * @return type
+ */
 function cache_getMembergroupList()
 {
 	global $scripturl, $smcFunc;
@@ -641,6 +649,15 @@ function cache_getMembergroupList()
 	);
 }
 
+/**
+ * Helper function to generate a list of membergroups for display
+ *
+ * @param type $start
+ * @param type $items_per_page
+ * @param type $sort
+ * @param type $membergroup_type
+ * @return type
+ */
 function list_getMembergroups($start, $items_per_page, $sort, $membergroup_type)
 {
 	global $txt, $scripturl, $context, $settings, $smcFunc;

Sources/Subs-Members.php

@@ -22,13 +22,13 @@ if (!defined('SMF'))
  * respectively removing your own account or any account.
  * Non-admins cannot delete admins.
  * The function:
- * - changes author of messages, topics and polls to guest authors.
- * - removes all log entries concerning the deleted members, except the
+ *   - changes author of messages, topics and polls to guest authors.
+ *   - removes all log entries concerning the deleted members, except the
  * error logs, ban logs and moderation logs.
- * - removes these members' personal messages (only the inbox), avatars,
+ *   - removes these members' personal messages (only the inbox), avatars,
  * ban entries, theme settings, moderator positions, poll votes, and
  * karma votes.
- * - updates member statistics afterwards.
+ *   - updates member statistics afterwards.
  *
  * @param array $users
  * @param bool $check_not_admin = false
@@ -1283,6 +1283,7 @@ function list_getNumMembers($where, $where_params = array())
 }
 
 /**
+ * Find potential duplicate registation members based on the same IP address
  *
  * @param $members
  */
@@ -1400,8 +1401,12 @@ function populateDuplicateMembers(&$members)
 		}
 }
 
-// Generate a random validation code.
-// @todo Err. Whatcha doin' here.
+/**
+ * Generate a random validation code.
+ * @todo Err. Whatcha doin' here.
+ *
+ * @return type
+ */
 function generateValidationCode()
 {
 	global $smcFunc, $modSettings;

Sources/Subs-Menu.php

@@ -20,7 +20,7 @@ if (!defined('SMF'))
  * Create a menu.
  * @param array $menuData
  * @param array $menuOptions = array()
- * @return bool|array
+ * @return boolean|array
  */
 function createMenu($menuData, $menuOptions = array())
 {
@@ -280,7 +280,7 @@ function createMenu($menuData, $menuOptions = array())
 /**
  * Delete a menu.
  * @param string $menu_id = 'last'
- * @return bool
+ * @return boolean
  */
 function destroyMenu($menu_id = 'last')
 {

Sources/Subs-MessageIndex.php

@@ -14,6 +14,13 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
+/**
+ * Generates the query to determine the list of available boards for a user
+ * Executes the query and returns the list
+ *
+ * @param type $boardListOptions
+ * @return type
+ */
 function getBoardList($boardListOptions = array())
 {
 	global $smcFunc, $user_info;

Sources/Subs-OpenID.php

@@ -81,7 +81,7 @@ function smf_openID_validate($openid_uri, $return = false, $save_fields = array(
 
 /**
  * Revalidate a user using OpenID. Note that this function will not return when authentication is required.
- * @return bool
+ * @return boolean
  */
 function smf_openID_revalidate()
 {
@@ -520,7 +520,7 @@ function smf_openid_generate_private_key()
  *
  * Enter description here ...
  * @param string $openid_url
- * @return bool|array
+ * @return boolean|array
  */
 function smf_openID_getServerInfo($openid_url)
 {

Sources/Subs-Package.php

@@ -22,7 +22,8 @@ if (!defined('SMF'))
 /**
  * Reads a .tar.gz file, filename, in and extracts file(s) from it.
  * essentially just a shortcut for read_tgz_data().
- * @param string $filename
+ *
+ * @param string $gzfilename
  * @param string $destination
  * @param bool $single_file = false
  * @param bool $overwrite = false
@@ -225,7 +226,16 @@ function read_tgz_data($data, $destination, $single_file = false, $overwrite = f
 		return $return;
 }
 
-// Extract zip data.  If destination is null, return a listing.
+/**
+ * Extract zip data.  If destination is null, return a listing.
+ *
+ * @param type $data
+ * @param type $destination
+ * @param type $single_file
+ * @param type $overwrite
+ * @param type $files_to_extract
+ * @return boolean
+ */
 function read_zip_data($data, $destination, $single_file = false, $overwrite = false, $files_to_extract = null)
 {
 	umask(0);
@@ -342,7 +352,7 @@ function read_zip_data($data, $destination, $single_file = false, $overwrite = f
  * Checks the existence of a remote file since file_exists() does not do remote.
  * will return false if the file is "moved permanently" or similar.
  * @param string url
- * @return bool true if the remote url exists.
+ * @return boolean true if the remote url exists.
  */
 function url_exists($url)
 {
@@ -432,7 +442,7 @@ function loadInstalledPackages()
  * - otherwise returns a basic array of id, version, filename, and similar information.
  * - an xmlArray is available in 'xml'.
  *
- * @param string $filename
+ * @param string $gzfilename
  * @return array
  */
 function getPackageInfo($gzfilename)
@@ -487,7 +497,14 @@ function getPackageInfo($gzfilename)
 	return $package;
 }
 
-// Create a chmod control for chmoding files.
+/**
+ * Create a chmod control for chmoding files.
+ *
+ * @param type $chmodFiles
+ * @param type $chmodOptions
+ * @param type $restore_write_status
+ * @return boolean
+ */
 function create_chmod_control($chmodFiles = array(), $chmodOptions = array(), $restore_write_status = false)
 {
 	global $context, $modSettings, $package_ftp, $boarddir, $txt, $sourcedir, $scripturl;
@@ -495,6 +512,15 @@ function create_chmod_control($chmodFiles = array(), $chmodOptions = array(), $r
 	// If we're restoring the status of existing files prepare the data.
 	if ($restore_write_status && isset($_SESSION['pack_ftp']) && !empty($_SESSION['pack_ftp']['original_perms']))
 	{
+		/**
+		 * Get a listing of files that will need to be set back to the original state
+		 *
+		 * @param type $dummy1
+		 * @param type $dummy2
+		 * @param type $dummy3
+		 * @param type $do_change
+		 * @return type
+		 */
 		function list_restoreFiles($dummy1, $dummy2, $dummy3, $do_change)
 		{
 			global $txt;
@@ -793,6 +819,8 @@ function create_chmod_control($chmodFiles = array(), $chmodOptions = array(), $r
 }
 
 /**
+ * Use FTP functions to work with a package download/install
+ *
  * @param string $destination_url
  * @param array $files = none
  * @param bool $return = false
@@ -1442,6 +1470,8 @@ function parsePackageInfo(&$packageXML, $testing_only = true, $method = 'install
  * - returns true if the version matched.
  *
  * @param string $versions
+ * @param boolean $reset
+ * @param type $the_version
  * @return highest install value string or false
  */
 function matchHighestPackageVersion($versions, $reset = false, $the_version)
@@ -1481,7 +1511,7 @@ function matchHighestPackageVersion($versions, $reset = false, $the_version)
  *
  * @param string $version
  * @param string $versions
- * @return bool
+ * @return boolean
  */
 function matchPackageVersion($version, $versions)
 {
@@ -1582,6 +1612,7 @@ function compareVersions($version1, $version2)
 
 /**
  * Parses special identifiers out of the specified path.
+ *
  * @param string $path
  * @return string The parsed path
  */
@@ -1617,8 +1648,9 @@ function parse_path($path)
 /**
  * Deletes a directory, and all the files and direcories inside it.
  * requires access to delete these files.
- * @param string $path
- * @param bool $delete_directory = true
+ *
+ * @param string $dir
+ * @param bool $delete_dir = true
  */
 function deltree($dir, $delete_dir = true)
 {
@@ -1692,9 +1724,10 @@ function deltree($dir, $delete_dir = true)
 /**
  * Creates the specified tree structure with the mode specified.
  * creates every directory in path until it finds one that already exists.
- * @param string $path
+ *
+ * @param string $strPath
  * @param int $mode
- * @return bool true if successful, false otherwise
+ * @return boolean true if successful, false otherwise
  */
 function mktree($strPath, $mode)
 {
@@ -1761,6 +1794,7 @@ function mktree($strPath, $mode)
 /**
  * Copies one directory structure over to another.
  * requires the destination to be writable.
+ *
  * @param string $source
  * @param string $destination
  */
@@ -1807,6 +1841,8 @@ function copytree($source, $destination)
 }
 
 /**
+ * Create a tree listing for a given directory path
+ *
  * @param string $path
  * @param string $sub_path = ''
  * @return array
@@ -1839,6 +1875,7 @@ function listtree($path, $sub_path = '')
 
 /**
  * Parses a xml-style modification file (file).
+ *
  * @param string $file
  * @param bool $testing = true tells it the modifications shouldn't actually be saved.
  * @param bool $undo = false specifies that the modifications the file requests should be undone; this doesn't work with everything (regular expressions.)
@@ -2534,6 +2571,12 @@ function parseBoardMod($file, $testing = true, $undo = false, $theme_paths = arr
 	return $actions;
 }
 
+/**
+ * Get the physical contents of a packages file
+ *
+ * @param type $filename
+ * @return boolean
+ */
 function package_get_contents($filename)
 {
 	global $package_cache, $modSettings;
@@ -2561,8 +2604,10 @@ function package_get_contents($filename)
  * uses FTP to create/chmod the file when necessary and available.
  * uses text mode for text mode file extensions.
  * returns the number of bytes written.
+ *
  * @param string $filename
  * @param string $data
+ * @param bool testing
  * @return int
  */
 function package_put_contents($filename, $data, $testing = false)
@@ -2618,6 +2663,12 @@ function package_put_contents($filename, $data, $testing = false)
 	return strlen($data);
 }
 
+/**
+ * Clears (removes the files) the current package cache (temp directory)
+ *
+ * @param type $trash
+ * @return type
+ */
 function package_flush_cache($trash = false)
 {
 	global $package_ftp, $package_cache;
@@ -2676,7 +2727,7 @@ function package_flush_cache($trash = false)
  * @param string $filename
  * @param string $perm_state = 'writable'
  * @param bool $track_change = false
- * @return bool True if it worked, false if it didn't
+ * @return boolean True if it worked, false if it didn't
  */
 function package_chmod($filename, $perm_state = 'writable', $track_change = false)
 {
@@ -3135,10 +3186,15 @@ function fetch_web_data($url, $post_data = '', $keep_alive = false, $redirection
 	return $data;
 }
 
-// crc32 doesn't work as expected on 64-bit functions - make our own.
-// http://www.php.net/crc32#79567
 if (!function_exists('smf_crc32'))
 {
+	/**
+	 * crc32 doesn't work as expected on 64-bit functions - make our own.
+	 * http://www.php.net/crc32#79567
+	 * 
+	 * @param type $number
+	 * @return type
+	 */
 	function smf_crc32($number)
 	{
 		$crc = crc32($number);

Sources/Subs-Post.php

@@ -517,7 +517,7 @@ function fixTag(&$message, $myTag, $protocols, $embeddedUrl = false, $hasEqualSi
  * @param int $priority = 3
  * @param bool $hotmail_fix = null
  * @param $is_private
- * @return bool, whether ot not the email was sent properly.
+ * @return boolean, whether ot not the email was sent properly.
  */
 function sendmail($to, $subject, $message, $from = null, $message_id = null, $send_html = false, $priority = 3, $hotmail_fix = null, $is_private = false)
 {
@@ -696,7 +696,7 @@ function sendmail($to, $subject, $message, $from = null, $message_id = null, $se
  * @param bool $send_html = false
  * @param int $priority = 3
  * @param $is_private
- * @return bool
+ * @return boolean
  */
 function AddMailQueue($flush = false, $to_array = array(), $subject = '', $message = '', $headers = '', $send_html = false, $priority = 3, $is_private = false)
 {
@@ -1265,18 +1265,16 @@ function mimespecialchars($string, $with_charset = true, $hotmail_fix = false, $
 		return array($charset, $string, '7bit');
 }
 
-// Send an email via SMTP.
-
 /**
  * Sends mail, like mail() but over SMTP.
  * It expects no slashes or entities.
  * @internal
  *
  * @param array $mail_to_array - array of strings (email addresses)
- * @param string $subject, email subject
- * @param string $message, email message
- * @param string  $headers
- * @return bool, whether it sent or not.
+ * @param string $subject email subject
+ * @param string $message email message
+ * @param string $headers
+ * @return boolean whether it sent or not.
  */
 function smtp_mail($mail_to_array, $subject, $message, $headers)
 {
@@ -2469,7 +2467,7 @@ function approvePosts($msgs, $approve = true)
  * Approve topics?
  * @todo shouldn't this be in topic
  *
- * @param array $topics, array of topics ids
+ * @param array $topics array of topics ids
  * @param bool $approve = true
  */
 function approveTopics($topics, $approve = true)
@@ -2780,7 +2778,7 @@ function updateLastMessages($setboards, $id_msg = 0)
  * Email is sent to all groups that have the moderate_forum permission.
  * The language set by each member is being used (if available).
  *
- * @param string $type, types supported are 'approval', 'activation', and 'standard'.
+ * @param string $type types supported are 'approval', 'activation', and 'standard'.
  * @param int $memberID
  * @param string $member_name = null
  * @uses the Login language file.
@@ -2930,6 +2928,13 @@ function loadEmailTemplate($template, $replacements = array(), $lang = '', $load
 	return $ret;
 }
 
+/**
+ * Callback function for loademaitemplate on subject and body
+ * Uses capture group 1 in array
+ *
+ * @param type $matches
+ * @return string
+ */
 function user_info_callback($matches)
 {
 	global $user_info;

Sources/Subs-Sound.php

@@ -24,7 +24,7 @@ if (!defined('SMF'))
  * Used by VerificationCode() (Register.php).
  *
  * @param string $word
- * @return bool false on failure
+ * @return boolean false on failure
  */
 
 function createWaveFile($word)

Sources/Subs.php

@@ -2987,7 +2987,7 @@ function setupThemeContext($forceload = false)
  *
  * @param string $needed The amount of memory to request, if needed, like 256M
  * @param bool $in_use Set to true to account for current memory usage of the script
- * @return bool, true if we have at least the needed memory
+ * @return boolean, true if we have at least the needed memory
  */
 function setMemoryLimit($needed, $in_use = false)
 {
@@ -3053,7 +3053,7 @@ function template_rawdata()
 }
 
 /**
- *
+ * The header template
  */
 function template_header()
 {
@@ -3196,7 +3196,7 @@ function theme_copyright()
 }
 
 /**
- *
+ * The template footer
  */
 function template_footer()
 {
@@ -3584,11 +3584,11 @@ function text2words($text, $max_chars = 20, $encrypt = false)
 /**
  * Creates an image/text button
  *
- * @param string $filename
+ * @param string $name
  * @param string $alt
  * @param string $label = ''
- * @param bool $custom = ''
- * @param bool $force_use = false
+ * @param boolean $custom = ''
+ * @param boolean $force_use = false
  * @return string
  */
 function create_button($name, $alt, $label = '', $custom = '', $force_use = false)
@@ -3732,6 +3732,9 @@ function loadClassFile($filename)
 }
 
 /**
+ * Sets up all of the top menu buttons
+ * Saves them in the cache if it is available and on
+ * Places the results in $context
  *
  */
 function setupMenuContext()
@@ -4041,7 +4044,7 @@ function smf_seed_generator()
  * supports static class method calls.
  *
  * @param string $hook
- * @param array $paramaters = array()
+ * @param array $parameters = array()
  * @return array the results of the functions
  */
 function call_integration_hook($hook, $parameters = array())

Sources/Themes.php

@@ -16,8 +16,7 @@
  * - any support website for the theme should be in website.
  * - layers and templates (non-default) should go in those elements ;).
  * - if the images dir isn't images, specify in the images element.
- * - any extra rows for themes should go in extra, serialized.
- * (as in array(variable => value).)
+ * - any extra rows for themes should go in extra, serialized. (as in array(variable => value).)
  * - tar and gzip the directory - and you're done!
  * - please include any special license in a license.txt file.
  *
@@ -1984,6 +1983,13 @@ function EditTheme()
 	createToken('admin-te-' . md5($_GET['th'] . '-' . $_REQUEST['filename']));
 }
 
+/**
+ * Generates a file listing for a given directory
+ *
+ * @param type $path
+ * @param type $relative
+ * @return type
+ */
 function get_file_listing($path, $relative)
 {
 	global $scripturl, $txt, $context;
@@ -2045,6 +2051,10 @@ function get_file_listing($path, $relative)
 	return array_merge($listing1, $listing2);
 }
 
+/**
+ * Makes a copy of a template file in a new location
+ * @uses Themes template, copy_template sub-template.
+ */
 function CopyTemplate()
 {
 	global $context, $settings, $smcFunc;

Sources/Who.php

@@ -250,7 +250,7 @@ function Who()
  * Adding actions to the Who's Online list:
  * Adding actions to this list is actually relatively easy...
  *  - for actions anyone should be able to see, just add a string named whoall_ACTION.
-*     (where ACTION is the action used in index.php.)
+ *    (where ACTION is the action used in index.php.)
  *  - for actions that have a subaction which should be represented differently, use whoall_ACTION_SUBACTION.
  *  - for actions that include a topic, and should be restricted, use whotopic_ACTION.
  *  - for actions that use a message, by msg or quote, use whopost_ACTION.
@@ -259,11 +259,9 @@ function Who()
  *    use whoallow_ACTION and add a list of possible permissions to the
  *    $allowedActions array, using ACTION as the key.
  *
- * @param mixed $urls, a single url (string) or an array of arrays, each
- * inner array being (serialized request data, id_member)
+ * @param mixed $urls  a single url (string) or an array of arrays, each inner array being (serialized request data, id_member)
  * @param string $preferred_prefix = false
- * @return array, an array of descriptions if you passed an array, otherwise
- * the string describing their current location.
+ * @return array, an array of descriptions if you passed an array, otherwise the string describing their current location.
  */
 function determineActions($urls, $preferred_prefix = false)
 {

attachments/index.php

@@ -1,6 +1,8 @@
 <?php
 
-// This file is here solely to protect your attachments directory.
+/**
+ * This file is here solely to protect your attachments directory.
+ */
 
 // Look for Settings.php....
 if (file_exists(dirname(dirname(__FILE__)) . '/Settings.php'))

avatars/index.php

@@ -1,6 +1,8 @@
 <?php
 
-// This file is here solely to protect your avatars directory.
+/**
+ * This file is here solely to protect your avatars directory.
+ */
 
 // Look for Settings.php....
 if (file_exists(dirname(dirname(__FILE__)) . '/Settings.php'))