Browse Source

Merge pull request #207 from Spuds/docblock

! Fix many of the phpdocumentor errors with our docblock's
emanuele45 12 năm trước cách đây
mục cha
commit
54a72eb11e
72 tập tin đã thay đổi với 1004 bổ sung329 xóa
  1. 3 1
      Packages/index.php
  2. 3 1
      Smileys/index.php
  3. 21 6
      Sources/Class-BrowserDetect.php
  4. 27 21
      Sources/Class-CurlFetchWeb.php
  5. 145 12
      Sources/Class-Package.php
  6. 6 4
      Sources/DbExtra-mysql.php
  7. 7 5
      Sources/DbExtra-postgresql.php
  8. 7 5
      Sources/DbExtra-sqlite.php
  9. 40 23
      Sources/DbPackages-mysql.php
  10. 34 23
      Sources/DbPackages-postgresql.php
  11. 36 23
      Sources/DbPackages-sqlite.php
  12. 1 1
      Sources/DbSearch-postgresql.php
  13. 1 1
      Sources/DbSearch-sqlite.php
  14. 10 6
      Sources/Display.php
  15. 2 1
      Sources/Drafts.php
  16. 4 2
      Sources/Errors.php
  17. 3 1
      Sources/Karma.php
  18. 2 2
      Sources/Load.php
  19. 1 1
      Sources/LogInOut.php
  20. 3 2
      Sources/Logging.php
  21. 5 3
      Sources/ManageAttachments.php
  22. 8 3
      Sources/ManageBans.php
  23. 4 3
      Sources/ManageBoards.php
  24. 7 1
      Sources/ManageLanguages.php
  25. 3 1
      Sources/ManageMaintenance.php
  26. 5 0
      Sources/ManageNews.php
  27. 1 1
      Sources/ManagePermissions.php
  28. 4 0
      Sources/ManageSearch.php
  29. 7 0
      Sources/ManageSearchEngines.php
  30. 40 0
      Sources/ManageSettings.php
  31. 14 1
      Sources/MoveTopic.php
  32. 18 3
      Sources/News.php
  33. 43 0
      Sources/Packages.php
  34. 2 2
      Sources/PersonalMessage.php
  35. 2 0
      Sources/Post.php
  36. 2 5
      Sources/PostModeration.php
  37. 3 3
      Sources/Profile-Actions.php
  38. 3 3
      Sources/Profile-Modify.php
  39. 17 0
      Sources/Profile-View.php
  40. 8 4
      Sources/QueryString.php
  41. 6 2
      Sources/RemoveTopic.php
  42. 3 1
      Sources/RepairBoards.php
  43. 1 1
      Sources/Reports.php
  44. 14 1
      Sources/ScheduledTasks.php
  45. 77 11
      Sources/SearchAPI-Custom.php
  46. 37 9
      Sources/SearchAPI-Fulltext.php
  47. 24 4
      Sources/SearchAPI-Standard.php
  48. 7 7
      Sources/Security.php
  49. 5 5
      Sources/Session.php
  50. 6 0
      Sources/Subs-Admin.php
  51. 8 6
      Sources/Subs-Auth.php
  52. 1 1
      Sources/Subs-Boards.php
  53. 23 23
      Sources/Subs-Calendar.php
  54. 3 4
      Sources/Subs-Categories.php
  55. 16 14
      Sources/Subs-Db-mysql.php
  56. 28 4
      Sources/Subs-Db-postgresql.php
  57. 21 1
      Sources/Subs-Db-sqlite.php
  58. 5 0
      Sources/Subs-Editor.php
  59. 7 6
      Sources/Subs-Graphics.php
  60. 22 5
      Sources/Subs-Membergroups.php
  61. 11 6
      Sources/Subs-Members.php
  62. 2 2
      Sources/Subs-Menu.php
  63. 7 0
      Sources/Subs-MessageIndex.php
  64. 2 2
      Sources/Subs-OpenID.php
  65. 69 13
      Sources/Subs-Package.php
  66. 15 10
      Sources/Subs-Post.php
  67. 1 1
      Sources/Subs-Sound.php
  68. 10 7
      Sources/Subs.php
  69. 12 2
      Sources/Themes.php
  70. 3 5
      Sources/Who.php
  71. 3 1
      attachments/index.php
  72. 3 1
      avatars/index.php

+ 3 - 1
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'))

+ 3 - 1
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'))

+ 21 - 6
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;
 
 	/**

+ 27 - 21
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 = '')

+ 145 - 12
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!

+ 6 - 4
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)
 {

+ 7 - 5
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)
 {

+ 7 - 5
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)
 {

+ 40 - 23
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;

+ 34 - 23
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

+ 36 - 23
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
  */

+ 1 - 1
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)

+ 1 - 1
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)

+ 10 - 6
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)
 {

+ 2 - 1
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)
 {

+ 4 - 2
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)
 {

+ 3 - 1
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;

+ 2 - 2
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)
 {

+ 1 - 1
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)

+ 3 - 2
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')
 {

+ 5 - 3
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;

+ 8 - 3
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 = '')
 {

+ 4 - 3
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;

+ 7 - 1
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)
 		{

+ 3 - 1
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;

+ 5 - 0
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;

+ 1 - 1
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')
 {

+ 4 - 0
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;

+ 7 - 0
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()

+ 40 - 0
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;

+ 14 - 1
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;

+ 18 - 3
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 = '')

+ 43 - 0
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;

+ 2 - 2
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')
 {

+ 2 - 0
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())
 {

+ 2 - 5
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)
 {

+ 3 - 3
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)
 {

+ 3 - 3
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)
 {

+ 17 - 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;

+ 8 - 4
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

+ 6 - 2
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)
 {

+ 3 - 1
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;

+ 1 - 1
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)
 {

+ 14 - 1
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)
 {

+ 77 - 11
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)
 	{

+ 37 - 9
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()
 	 *

+ 24 - 4
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.

+ 7 - 7
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)
 {

+ 5 - 5
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)
 {

+ 6 - 0
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())
 {

+ 8 - 6
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)

+ 1 - 1
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)
 {

+ 23 - 23
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)

+ 3 - 4
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)
 {

+ 16 - 14
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

+ 28 - 4
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

+ 21 - 1
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)

+ 5 - 0
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()
 {
 

+ 7 - 6
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)
 {

+ 22 - 5
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;

+ 11 - 6
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;

+ 2 - 2
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')
 {

+ 7 - 0
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;

+ 2 - 2
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)
 {

+ 69 - 13
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);

+ 15 - 10
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;

+ 1 - 1
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)

+ 10 - 7
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())

+ 12 - 2
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;

+ 3 - 5
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)
 {

+ 3 - 1
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'))

+ 3 - 1
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'))