! Some more attempts to... read the SMF code documentation. :P (commits also known as "what do sleepless nights do to people")

! Code documentation refactoring for good ole' messy Display.php.
! More code doc refactoring.
! And some more code doc refactoring.
! And some more code doc refactoring, just because.
! More bits of code documentation standardization.

Sources/Class-Package.php

@@ -16,37 +16,9 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*
-	string xmlArray::name()
-		- retrieves the name of the current element, usually ''.
-
-	string xmlArray::fetch(string path, bool get_elements = false)
-		- retrieves the textual value of the specified path.
-		- children are parsed for text, but only textual data is returned
-		  unless get_elements is true.
-
-	xmlArray xmlArray::path(string path, bool return_set = false)
-		- finds any elements that match the path specified.
-		- will always return a set if there is more than one of the element
-		  or return_set is true.
-		- returns in the form of a new xmlArray.
-
-	bool xmlArray::exists(string path)
-		- returns whether the specified path matches at least one element.
-
-	int xmlArray::count(string path)
-		- returns the number of elements the path matches.
-
-	array xmlArray::set(string path)
-		- returns an array of xmlArray's matching the specified path.
-		- this differs from ->path(path, true) in that instead of an xmlArray
-		  of elements, an array of xmlArray's is returned for use with foreach.
-
-	string xmlArray::create_xml(string path = '.')
-		- returns the specified path as an xml file.
-*/
-
-// An xml array.  Reads in xml, allows you to access it simply.  Version 1.1.
+/**
+ * Class representing an xml array.  Reads in xml, allows you to access it simply.  Version 1.1.
+ */
 class xmlArray
 {
 	// The array and debugging output level.
@@ -56,11 +28,11 @@ class xmlArray
 	 * Constructor for the xml parser.
 	 * Example use:
 	 *  $xml = new xmlArray(file('data.xml'));
-	 * @param $data string the xml data or an array of, unless is_clone is true.
-	 * @param $auto_trim bool, default false, used to automatically trim textual data.
-	 * @param $level int, default null, the debug level, specifies whether notices
+	 * @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 $is_clone bool, default false. If is_clone is true, the
+	 * @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)
@@ -102,10 +74,12 @@ class xmlArray
 
 	/**
 	 * Get a specified element's value or attribute by path.
+	 * Children are parsed for text, but only textual data is returned
+	 * unless get_elements is true.
 	 * Example use:
 	 *  $data = $xml->fetch('html/head/title');
-	 * @param $path string - the path to the element to fetch
-	 * @param $get_elements - whether to include elements
+	 * @param string $path - the path to the element to fetch
+	 * @param bool $get_elements - whether to include elements
 	 */
 	public function fetch($path, $get_elements = false)
 	{
@@ -137,10 +111,14 @@ class xmlArray
 	}
 
 	/** Get an element, returns a new xmlArray.
+	 * It finds any elements that match the path specified.
+	 * It will always return a set if there is more than one of the element
+	 * or return_set is true.
 	 * Example use:
 	 *  $element = $xml->path('html/body');
 	 * @param $path string - the path to the element to get
 	 * @param $return_full bool - always return full result set
+	 * @return xmlArray, a new xmlArray.
 	 */
 	public function path($path, $return_full = false)
 	{
@@ -206,7 +184,8 @@ class xmlArray
 	 * Check if an element exists.
 	 * Example use,
 	 *  echo $xml->exists('html/body') ? 'y' : 'n';
-	 * @param $path string - the path to the element to get.
+	 * @param string $path - the path to the element to get.
+	 * @return bool
 	 */
 	public function exists($path)
 	{
@@ -239,10 +218,11 @@ class xmlArray
 	}
 
 	/**
-	 * Count the number of occurances of a path.
+	 * Count the number of occurences of a path.
 	 * Example use:
 	 *  echo $xml->count('html/head/meta');
-	 * @param $path string - the path to search for.
+	 * @param string $path - the path to search for.
+	 * @return int, the number of elements the path matches.
 	 */
 	public function count($path)
 	{
@@ -261,10 +241,13 @@ class xmlArray
 	}
 
 	/**
-	 * Get an array of xmlArray's for use with foreach.
+	 * Get an array of xmlArray's matching the specified path.
+	 * This differs from ->path(path, true) in that instead of an xmlArray
+	 * of elements, an array of xmlArray's is returned for use with foreach.
 	 * Example use:
 	 *  foreach ($xml->set('html/body/p') as $p)
 	 * @param $path string - the path to search for.
+	 * @return array, an array of xmlArray objects
 	 */
 	public function set($path)
 	{
@@ -289,10 +272,11 @@ class xmlArray
 	}
 
 	/**
-	 * Create an xml file from an xml array.
+	 * Create an xml file from an xmlArray, the specified path if any.
 	 * Example use:
 	 *  echo $this->create_xml();
-	 * @param $path string - the path to the element. (optional)
+	 * @param string $path - the path to the element. (optional)
+	 * @return string, xml-formatted string.
 	 */
 	public function create_xml($path = null)
 	{
@@ -319,7 +303,7 @@ class xmlArray
 	 * Output the xml in an array form.
 	 * Example use:
 	 *  print_r($xml->to_array());
-	 * @param $path string, the path to output.
+	 * @param string $path, the path to output.
 	 */
 	public function to_array($path = null)
 	{
@@ -343,7 +327,7 @@ class xmlArray
 
 	/**
 	 * Parse data into an array. (privately used...)
-	 * @param $data string to parse
+	 * @param string $data to parse
 	 */
 	protected function _parse($data)
 	{
@@ -613,7 +597,11 @@ class xmlArray
 		return $this->trim ? trim($data) : $data;
 	}
 
-	// Given an array, return the text from that array. (recursive and privately used.)
+	/**
+	 * Given an array, return the text from that array. (recursive and privately used.)
+	 *
+	 * @param array $array
+	 */
 	protected function _fetch($array)
 	{
 		// Don't return anything if this is just a string.
@@ -641,10 +629,10 @@ class xmlArray
 
 	/**
 	 * Get a specific array by path, one level down. (privately used...)
-	 * @param $array
-	 * @param $path
-	 * @param $level
-	 * @param $no_error
+	 * @param array $array
+	 * @param string $path
+	 * @param int $level
+	 * @param bool $no_error
 	 */
 	protected function _path($array, $path, $level, $no_error = false)
 	{

Sources/DbExtra-mysql.php

@@ -36,8 +36,8 @@ function db_extra_init()
 
 /**
  * Backup $table to $backup_table.
- * @param $table string
- * @param $backup_table string
+ * @param string $table
+ * @param string $backup_table
  * @return resource -the request handle to the table creation query
  */
 function smf_db_backup_table($table, $backup_table)
@@ -169,7 +169,7 @@ function smf_db_backup_table($table, $backup_table)
 
 /**
  * This function optimizes a table.
- * @param $table string - the table to be optimized
+ * @param string $table - the table to be optimized
  * @return how much it was gained
  */
 function smf_db_optimize_table($table)
@@ -216,8 +216,8 @@ function smf_db_optimize_table($table)
 /**
  * This function lists all tables in the database.
  * The listing could be filtered according to $filter.
- * @param $db mixed, string holding the table name, or false, default false
- * @param $filter mixed, 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,7 +248,7 @@ 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 $tableName string - the table to create the inserts for.
+ * @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.
  */
@@ -323,7 +323,7 @@ function smf_db_insert_sql($tableName)
 /**
  * Dumps the schema (CREATE) for a table.
  * @todo why is this needed for?
- * @param $tableName string - the table
+ * @param string $tableName - the table
  * @return string - the CREATE statement as string
  */
 function smf_db_table_sql($tableName)

Sources/DbExtra-postgresql.php

@@ -36,8 +36,8 @@ function db_extra_init()
 
 /**
  * Backup $table to $backup_table.
- * @param $table string
- * @param $backup_table string
+ * @param string $table
+ * @param string $backup_table
  * @return resource -the request handle to the table creation query
  */
 function smf_db_backup_table($table, $backup_table)
@@ -80,7 +80,7 @@ function smf_db_backup_table($table, $backup_table)
 
 /**
  * This function optimizes a table.
- * @param $table string - the table to be optimized
+ * @param string $table - the table to be optimized
  * @return how much it was gained
  */
 function smf_db_optimize_table($table)
@@ -110,8 +110,8 @@ function smf_db_optimize_table($table)
 /**
  * This function lists all tables in the database.
  * The listing could be filtered according to $filter.
- * @param $db mixed, string holding the table name, or false, default false
- * @param $filter mixed, 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)
@@ -141,7 +141,7 @@ 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 $tableName string - the table to create the inserts for.
+ * @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.
  */
@@ -204,7 +204,7 @@ function smf_db_insert_sql($tableName)
 /**
  * Dumps the schema (CREATE) for a table.
  * @todo why is this needed for?
- * @param $tableName string - the table
+ * @param string $tableName - the table
  * @return string - the CREATE statement as string
  */
 function smf_db_table_sql($tableName)

Sources/DbExtra-sqlite.php

@@ -2,7 +2,7 @@
 
 /**
  * This file contains rarely used extended database functionality.
- * 
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -37,8 +37,8 @@ function db_extra_init()
 
 /**
  * Backup $table to $backup_table.
- * @param $table string
- * @param $backup_table string
+ * @param string $table
+ * @param string $backup_table
  * @return resource -the request handle to the table creation query
  */
 function smf_db_backup_table($table, $backup_table)
@@ -130,7 +130,7 @@ function smf_db_backup_table($table, $backup_table)
 
 /**
  * This function optimizes a table.
- * @param $table string - the table to be optimized
+ * @param string $table - the table to be optimized
  * @return how much it was gained
  */
 function smf_db_optimize_table($table)
@@ -158,8 +158,8 @@ function smf_db_optimize_table($table)
 /**
  * This function lists all tables in the database.
  * The listing could be filtered according to $filter.
- * @param $db mixed, string holding the table name, or false, default false
- * @param $filter mixed, 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)
@@ -190,7 +190,7 @@ 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 $tableName string - the table to create the inserts for.
+ * @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.
  */
@@ -256,7 +256,7 @@ function smf_db_insert_sql($tableName)
 /**
  * Dumps the schema (CREATE) for a table.
  * @todo why is this needed for?
- * @param $tableName string - the table
+ * @param string $tableName - the table
  * @return string - the CREATE statement as string
  */
 function smf_db_table_sql($tableName)
@@ -318,7 +318,7 @@ function smf_db_get_version()
 	return sqlite_libversion();
 }
 
-/** 
+/**
  * Simply return the database - and die!
  * Used by DumpDatabase.php.
  */

Sources/DbPackages-mysql.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file contains database functionality specifically designed for packages (mods) to utilize.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,35 +16,9 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file contains database functionality specifically designed for packages to utilize.
-
-	bool smf_db_create_table(string table_name, array columns, array indexes = array(),
-		array parameters = array(), string if_exists = 'ignore')
-		- Can be used to create a table without worrying about schema compatabilities.
-		- If the table exists will, by default, do nothing.
-		- Builds table with columns as passed to it - at least one column must be sent.
-		  The columns array should have one sub-array for each column - these sub arrays contain:
-			+ 'name' = Column name
-			+ 'type' = Type of column - values from (smallint,mediumint,int,text,varchar,char,tinytext,mediumtext,largetext)
-			+ 'size' => Size of column (If applicable) - for example 255 for a large varchar, 10 for an int etc. If not
-						set SMF will pick a size.
-			+ 'default' = Default value - do not set if no default required.
-			+ 'null' => Can it be null (true or false) - if not set default will be false.
-			+ 'auto' => Set to true to make it an auto incrementing column. Set to a numerical value to set
-						from what it should begin counting.
-		- Adds indexes as specified within indexes parameter. Each index should be a member of $indexes. Values are:
-			+ 'name' => Index name (If left empty SMF will generate).
-			+ 'type' => Type of index. Choose from 'primary', 'unique' or 'index'. If not set will default to 'index'.
-			+ 'columns' => Array containing columns that form part of key - in the order the index is to be created.
-		- parameters: (None yet)
-		- if_exists values:
-			+ '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.
-
-*/
-
-// Add the file functions to the $smcFunc array.
+/**
+ * Add the file functions to the $smcFunc array.
+ */
 function db_packages_init()
 {
 	global $smcFunc, $reservedTables, $db_package_log, $db_prefix;
@@ -83,7 +59,36 @@ function db_packages_init()
 	db_extend('extra');
 }
 
-// Create a table.
+/**
+ * This function can be used to create a table without worrying about schema
+ *  compatabilities across supported database systems.
+ *  - If the table exists will, by default, do nothing.
+ *  - Builds table with columns as passed to it - at least one column must be sent.
+ *  The columns array should have one sub-array for each column - these sub arrays contain:
+ *  	'name' = Column name
+ *  	'type' = Type of column - values from (smallint, mediumint, int, text, varchar, char, tinytext, mediumtext, largetext)
+ *  	'size' => Size of column (If applicable) - for example 255 for a large varchar, 10 for an int etc.
+ *  		If not set SMF will pick a size.
+ *  	- 'default' = Default value - do not set if no default required.
+ *  	- 'null' => Can it be null (true or false) - if not set default will be false.
+ *  	- 'auto' => Set to true to make it an auto incrementing column. Set to a numerical value to set from what
+ *  		 it should begin counting.
+ *  - Adds indexes as specified within indexes parameter. Each index should be a member of $indexes. Values are:
+ *  	- 'name' => Index name (If left empty SMF will generate).
+ *  	- 'type' => Type of index. Choose from 'primary', 'unique' or 'index'. If not set will default to 'index'.
+ *  	- 'columns' => Array containing columns that form part of key - in the order the index is to be created.
+ *  - parameters: (None yet)
+ *  - if_exists values:
+ *  	- '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'
+ */
 function smf_db_create_table($table_name, $columns, $indexes = array(), $parameters = array(), $if_exists = 'ignore', $error = 'fatal')
 {
 	global $reservedTables, $smcFunc, $db_package_log, $db_prefix, $db_character_set;
@@ -173,7 +178,12 @@ function smf_db_create_table($table_name, $columns, $indexes = array(), $paramet
 	);
 }
 
-// Drop a table.
+/**
+ * Drop a table.
+ * @param string $table_name
+ * @param array $parameters, default array()
+ * @param string $error, default 'fatal'
+ */
 function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 {
 	global $reservedTables, $smcFunc, $db_prefix;
@@ -207,7 +217,14 @@ function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 	return false;
 }
 
-// Add a column.
+/**
+ * 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'
+ */
 function smf_db_add_column($table_name, $column_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
 	global $smcFunc, $db_package_log, $txt, $db_prefix;
@@ -254,7 +271,13 @@ function smf_db_add_column($table_name, $column_info, $parameters = array(), $if
 	return true;
 }
 
-// Remove a column.
+/**
+ * Removes a column.
+ * @param string $table_name
+ * @param string $column_name
+ * @param array $parameters, default array()
+ * @param string $error, default 'fatal'
+ */
 function smf_db_remove_column($table_name, $column_name, $parameters = array(), $error = 'fatal')
 {
 	global $smcFunc, $db_prefix;
@@ -281,7 +304,14 @@ function smf_db_remove_column($table_name, $column_name, $parameters = array(),
 	return false;
 }
 
-// Change a column.
+/**
+ * Change a column.
+ * @param string $table_name
+ * @param $old_column
+ * @param $column_info
+ * @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')
 {
 	global $smcFunc, $db_prefix;
@@ -334,7 +364,14 @@ function smf_db_change_column($table_name, $old_column, $column_info, $parameter
 	);
 }
 
-// Add an index.
+/**
+ * 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'
+ */
 function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
 	global $smcFunc, $db_package_log, $db_prefix;
@@ -399,7 +436,13 @@ function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_e
 	}
 }
 
-// Remove an index.
+/**
+ * Remove an index.
+ * @param string $table_name
+ * @param string $index_name
+ * @param array$parameters, default array()
+ * @param string $error, default 'fatal'
+ */
 function smf_db_remove_index($table_name, $index_name, $parameters = array(), $error = 'fatal')
 {
 	global $smcFunc, $db_prefix;
@@ -444,14 +487,23 @@ function smf_db_remove_index($table_name, $index_name, $parameters = array(), $e
 	return false;
 }
 
-// Get the schema formatted name for a type.
+/**
+ * Get the schema formatted name for a type.
+ * @param string $type_name
+ * @param $type_size
+ * @param $reverse
+ */
 function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 {
 	// MySQL is actually the generic baseline.
 	return array($type_name, $type_size);
 }
 
-// Get table structure.
+/**
+ * Get table structure.
+ * @param string $table_name
+ * @param array $parameters, default array()
+ */
 function smf_db_table_structure($table_name, $parameters = array())
 {
 	global $smcFunc, $db_prefix;
@@ -465,7 +517,13 @@ function smf_db_table_structure($table_name, $parameters = array())
 	);
 }
 
-// Return column information for a table.
+/**
+ * Return column information for a table.
+ * @param string $table_name
+ * @param bool $detail
+ * @param array $parameters, default array()
+ * @return mixed
+ */
 function smf_db_list_columns($table_name, $detail = false, $parameters = array())
 {
 	global $smcFunc, $db_prefix;
@@ -526,7 +584,13 @@ function smf_db_list_columns($table_name, $detail = false, $parameters = array()
 	return $columns;
 }
 
-// What about some index information?
+/**
+ * Get index information.
+ * @param string $table_name
+ * @param bool $detail
+ * @param array $parameters
+ * @return mixed
+ */
 function smf_db_list_indexes($table_name, $detail = false, $parameters = array())
 {
 	global $smcFunc, $db_prefix;

Sources/DbPackages-postgresql.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file contains database functionality specifically designed for packages (mods) to utilize.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,35 +16,9 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file contains database functionality specifically designed for packages to utilize.
-
-	bool smf_db_create_table(string table_name, array columns, array indexes = array(),
-		array parameters = array(), string if_exists = 'ignore')
-		- Can be used to create a table without worrying about schema compatabilities.
-		- If the table exists will, by default, do nothing.
-		- Builds table with columns as passed to it - at least one column must be sent.
-		  The columns array should have one sub-array for each column - these sub arrays contain:
-			+ 'name' = Column name
-			+ 'type' = Type of column - values from (smallint,mediumint,int,text,varchar,char,tinytext,mediumtext,largetext)
-			+ 'size' => Size of column (If applicable) - for example 255 for a large varchar, 10 for an int etc. If not
-						set SMF will pick a size.
-			+ 'default' = Default value - do not set if no default required.
-			+ 'null' => Can it be null (true or false) - if not set default will be false.
-			+ 'auto' => Set to true to make it an auto incrementing column. Set to a numerical value to set
-						from what it should begin counting.
-		- Adds indexes as specified within indexes parameter. Each index should be a member of $indexes. Values are:
-			+ 'name' => Index name (If left empty SMF will generate).
-			+ 'type' => Type of index. Choose from 'primary', 'unique' or 'index'. If not set will default to 'index'.
-			+ 'columns' => Array containing columns that form part of key - in the order the index is to be created.
-		- parameters: (None yet)
-		- if_exists values:
-			+ '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.
-
-*/
-
-// Add the file functions to the $smcFunc array.
+/**
+ * Add the file functions to the $smcFunc array.
+ */
 function db_packages_init()
 {
 	global $smcFunc, $reservedTables, $db_package_log, $db_prefix;
@@ -83,7 +59,36 @@ function db_packages_init()
 	db_extend('extra');
 }
 
-// Create a table.
+/**
+ * This function can be used to create a table without worrying about schema
+ *  compatabilities across supported database systems.
+ *  - If the table exists will, by default, do nothing.
+ *  - Builds table with columns as passed to it - at least one column must be sent.
+ *  The columns array should have one sub-array for each column - these sub arrays contain:
+ *  	'name' = Column name
+ *  	'type' = Type of column - values from (smallint, mediumint, int, text, varchar, char, tinytext, mediumtext, largetext)
+ *  	'size' => Size of column (If applicable) - for example 255 for a large varchar, 10 for an int etc.
+ *  		If not set SMF will pick a size.
+ *  	- 'default' = Default value - do not set if no default required.
+ *  	- 'null' => Can it be null (true or false) - if not set default will be false.
+ *  	- 'auto' => Set to true to make it an auto incrementing column. Set to a numerical value to set from what
+ *  		 it should begin counting.
+ *  - Adds indexes as specified within indexes parameter. Each index should be a member of $indexes. Values are:
+ *  	- 'name' => Index name (If left empty SMF will generate).
+ *  	- 'type' => Type of index. Choose from 'primary', 'unique' or 'index'. If not set will default to 'index'.
+ *  	- 'columns' => Array containing columns that form part of key - in the order the index is to be created.
+ *  - parameters: (None yet)
+ *  - if_exists values:
+ *  	- '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'
+ */
 function smf_db_create_table($table_name, $columns, $indexes = array(), $parameters = array(), $if_exists = 'ignore', $error = 'fatal')
 {
 	global $reservedTables, $smcFunc, $db_package_log, $db_prefix;
@@ -185,7 +190,12 @@ function smf_db_create_table($table_name, $columns, $indexes = array(), $paramet
 	$smcFunc['db_transaction']('commit');
 }
 
-// Drop a table.
+/**
+ * Drop a table.
+ * @param string $table_name
+ * @param array $parameters, default array()
+ * @param string $error, default 'fatal'
+ */
 function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 {
 	global $reservedTables, $smcFunc, $db_prefix;
@@ -236,7 +246,14 @@ function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 	return false;
 }
 
-// Add a column.
+/**
+ * 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'
+ */
 function smf_db_add_column($table_name, $column_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
 	global $smcFunc, $db_package_log, $txt, $db_prefix;
@@ -283,7 +300,13 @@ function smf_db_add_column($table_name, $column_info, $parameters = array(), $if
 		return true;
 }
 
-// Remove a column.
+/**
+ * Removes a column.
+ * @param string $table_name
+ * @param string $column_name
+ * @param array $parameters, default array()
+ * @param string $error, default 'fatal'
+ */
 function smf_db_remove_column($table_name, $column_name, $parameters = array(), $error = 'fatal')
 {
 	global $smcFunc, $db_prefix;
@@ -319,7 +342,14 @@ function smf_db_remove_column($table_name, $column_name, $parameters = array(),
 	return false;
 }
 
-// Change a column.
+/**
+ * Change a column.
+ * @param string $table_name
+ * @param $old_column
+ * @param $column_info
+ * @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')
 {
 	global $smcFunc, $db_prefix;
@@ -468,7 +498,14 @@ function smf_db_change_column($table_name, $old_column, $column_info, $parameter
 	}
 }
 
-// Add an index.
+/**
+ * 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'
+ */
 function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
 	global $smcFunc, $db_package_log, $db_prefix;
@@ -532,7 +569,13 @@ function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_e
 	}
 }
 
-// Remove an index.
+/**
+ * Remove an index.
+ * @param string $table_name
+ * @param string $index_name
+ * @param array$parameters, default array()
+ * @param string $error, default 'fatal'
+ */
 function smf_db_remove_index($table_name, $index_name, $parameters = array(), $error = 'fatal')
 {
 	global $smcFunc, $db_prefix;
@@ -578,7 +621,12 @@ function smf_db_remove_index($table_name, $index_name, $parameters = array(), $e
 	return false;
 }
 
-// Get the schema formatted name for a type.
+/**
+ * Get the schema formatted name for a type.
+ * @param string $type_name
+ * @param $type_size
+ * @param $reverse
+ */
 function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 {
 	// Generic => Specific.
@@ -617,7 +665,11 @@ function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 	return array($type_name, $type_size);
 }
 
-// Get table structure.
+/**
+ * Get table structure.
+ * @param string $table_name
+ * @param array $parameters, default array()
+ */
 function smf_db_table_structure($table_name, $parameters = array())
 {
 	global $smcFunc, $db_prefix;
@@ -631,7 +683,13 @@ function smf_db_table_structure($table_name, $parameters = array())
 	);
 }
 
-// Return column information for a table.
+/**
+ * Return column information for a table.
+ * @param string $table_name
+ * @param bool $detail
+ * @param array $parameters, default array()
+ * @return mixed
+ */
 function smf_db_list_columns($table_name, $detail = false, $parameters = array())
 {
 	global $smcFunc, $db_prefix;
@@ -686,7 +744,13 @@ function smf_db_list_columns($table_name, $detail = false, $parameters = array()
 	return $columns;
 }
 
-// What about some index information?
+/**
+ * Get index information.
+ * @param string $table_name
+ * @param bool $detail
+ * @param array $parameters
+ * @return mixed
+ */
 function smf_db_list_indexes($table_name, $detail = false, $parameters = array())
 {
 	global $smcFunc, $db_prefix;

Sources/DbPackages-sqlite.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file contains database functionality specifically designed for packages (mods) to utilize.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,35 +16,9 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file contains database functionality specifically designed for packages to utilize.
-
-	bool smf_db_create_table(string table_name, array columns, array indexes = array(),
-		array parameters = array(), string if_exists = 'ignore')
-		- Can be used to create a table without worrying about schema compatabilities.
-		- If the table exists will, by default, do nothing.
-		- Builds table with columns as passed to it - at least one column must be sent.
-		  The columns array should have one sub-array for each column - these sub arrays contain:
-			+ 'name' = Column name
-			+ 'type' = Type of column - values from (smallint,mediumint,int,text,varchar,char,tinytext,mediumtext,largetext)
-			+ 'size' => Size of column (If applicable) - for example 255 for a large varchar, 10 for an int etc. If not
-						set SMF will pick a size.
-			+ 'default' = Default value - do not set if no default required.
-			+ 'null' => Can it be null (true or false) - if not set default will be false.
-			+ 'auto' => Set to true to make it an auto incrementing column. Set to a numerical value to set
-						from what it should begin counting.
-		- Adds indexes as specified within indexes parameter. Each index should be a member of $indexes. Values are:
-			+ 'name' => Index name (If left empty SMF will generate).
-			+ 'type' => Type of index. Choose from 'primary', 'unique' or 'index'. If not set will default to 'index'.
-			+ 'columns' => Array containing columns that form part of key - in the order the index is to be created.
-		- parameters: (None yet)
-		- if_exists values:
-			+ '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.
-
-*/
-
-// Add the file functions to the $smcFunc array.
+/**
+ * Add the file functions to the $smcFunc array.
+ */
 function db_packages_init()
 {
 	global $smcFunc, $reservedTables, $db_package_log, $db_prefix;
@@ -84,7 +60,36 @@ function db_packages_init()
 	db_extend('extra');
 }
 
-// Create a table.
+/**
+ * This function can be used to create a table without worrying about schema
+ *  compatabilities across supported database systems.
+ *  - If the table exists will, by default, do nothing.
+ *  - Builds table with columns as passed to it - at least one column must be sent.
+ *  The columns array should have one sub-array for each column - these sub arrays contain:
+ *  	'name' = Column name
+ *  	'type' = Type of column - values from (smallint, mediumint, int, text, varchar, char, tinytext, mediumtext, largetext)
+ *  	'size' => Size of column (If applicable) - for example 255 for a large varchar, 10 for an int etc.
+ *  		If not set SMF will pick a size.
+ *  	- 'default' = Default value - do not set if no default required.
+ *  	- 'null' => Can it be null (true or false) - if not set default will be false.
+ *  	- 'auto' => Set to true to make it an auto incrementing column. Set to a numerical value to set from what
+ *  		 it should begin counting.
+ *  - Adds indexes as specified within indexes parameter. Each index should be a member of $indexes. Values are:
+ *  	- 'name' => Index name (If left empty SMF will generate).
+ *  	- 'type' => Type of index. Choose from 'primary', 'unique' or 'index'. If not set will default to 'index'.
+ *  	- 'columns' => Array containing columns that form part of key - in the order the index is to be created.
+ *  - parameters: (None yet)
+ *  - if_exists values:
+ *  	- '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'
+ */
 function smf_db_create_table($table_name, $columns, $indexes = array(), $parameters = array(), $if_exists = 'ignore', $error = 'fatal')
 {
 	global $reservedTables, $smcFunc, $db_package_log, $db_prefix;
@@ -189,7 +194,12 @@ function smf_db_create_table($table_name, $columns, $indexes = array(), $paramet
 		$smcFunc['db_transaction']('commit');
 }
 
-// Drop a table.
+/**
+ * Drop a table.
+ * @param string $table_name
+ * @param array $parameters, default array()
+ * @param string $error, default 'fatal'
+ */
 function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 {
 	global $reservedTables, $smcFunc, $db_prefix;
@@ -220,7 +230,14 @@ function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 	return false;
 }
 
-// Add a column.
+/**
+ * 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'
+ */
 function smf_db_add_column($table_name, $column_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
 	global $smcFunc, $db_package_log, $txt, $db_prefix;
@@ -249,7 +266,14 @@ function smf_db_add_column($table_name, $column_info, $parameters = array(), $if
 	return true;
 }
 
-// We can't reliably do this on SQLite - damn!
+/**
+ * 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'
+ */
 function smf_db_remove_column($table_name, $column_name, $parameters = array(), $error = 'fatal')
 {
 	global $smcFunc, $db_prefix;
@@ -262,7 +286,14 @@ function smf_db_remove_column($table_name, $column_name, $parameters = array(),
 		return false;
 }
 
-// Change a column.
+/**
+ * Change a column.
+ * @param string $table_name
+ * @param $old_column
+ * @param $column_info
+ * @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')
 {
 	global $smcFunc, $db_prefix;
@@ -275,7 +306,14 @@ function smf_db_change_column($table_name, $old_column, $column_info, $parameter
 		return false;
 }
 
-// Add an index.
+/**
+ * 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'
+ */
 function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
 	global $smcFunc, $db_package_log, $db_prefix;
@@ -333,7 +371,13 @@ function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_e
 	}
 }
 
-// Remove an index.
+/**
+ * Remove an index.
+ * @param string $table_name
+ * @param string $index_name
+ * @param array$parameters, default array()
+ * @param string $error, default 'fatal'
+ */
 function smf_db_remove_index($table_name, $index_name, $parameters = array(), $error = 'fatal')
 {
 	global $smcFunc, $db_prefix;
@@ -364,7 +408,12 @@ function smf_db_remove_index($table_name, $index_name, $parameters = array(), $e
 	return false;
 }
 
-// Get the schema formatted name for a type.
+/**
+ * Get the schema formatted name for a type.
+ * @param string $type_name
+ * @param $type_size
+ * @param $reverse
+ */
 function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 {
 	// Generic => Specific.
@@ -398,7 +447,11 @@ function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 	return array($type_name, $type_size);
 }
 
-// Get table structure.
+/**
+ * Get table structure.
+ * @param string $table_name
+ * @param array $parameters, default array()
+ */
 function smf_db_table_structure($table_name, $parameters = array())
 {
 	global $smcFunc, $db_prefix;
@@ -412,7 +465,14 @@ function smf_db_table_structure($table_name, $parameters = array())
 	);
 }
 
-// Harder than it should be on sqlite!
+/**
+ * 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()
+ * @return mixed
+ */
 function smf_db_list_columns($table_name, $detail = false, $parameters = array())
 {
 	global $smcFunc, $db_prefix;
@@ -471,7 +531,13 @@ function smf_db_list_columns($table_name, $detail = false, $parameters = array()
 	return $columns;
 }
 
-// What about some index information?
+/**
+ * Get index information.
+ * @param string $table_name
+ * @param bool $detail
+ * @param array $parameters
+ * @return mixed
+ */
 function smf_db_list_indexes($table_name, $detail = false, $parameters = array())
 {
 	global $smcFunc, $db_prefix;
@@ -526,6 +592,11 @@ function smf_db_list_indexes($table_name, $detail = false, $parameters = array()
 	return $indexes;
 }
 
+/**
+ * Alter table on SQLite.
+ * @param string $table_name
+ * @param array $columns
+ */
 function smf_db_alter_table($table_name, $columns)
 {
 	global $smcFunc, $db_prefix, $db_name, $boarddir;

Sources/DbSearch-mysql.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file contains database functions specific to search related activity.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,20 +16,9 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file contains database functions specific to search related activity.
-
-	void db_search_init()
-		- adds the functions in this file to the $smcFunc array
-
-	boolean smf_db_search_support($search_type)
-		- whether this database type support the search type $search_type
-
-	void smf_db_create_word_search($size)
- 		- create the custom word index table
-
-*/
-
-// Add the file functions to the $smcFunc array.
+/**
+ *  Add the file functions to the $smcFunc array.
+ */
 function db_search_init()
 {
 	global $smcFunc;
@@ -41,7 +32,11 @@ function db_search_init()
 		);
 }
 
-// Does this database type support this search type?
+/**
+ * This function will tell you whether this database type supports this search type.
+ *
+ * @param string $search_type
+ */
 function smf_db_search_support($search_type)
 {
 	$supported_types = array('fulltext');
@@ -49,7 +44,11 @@ function smf_db_search_support($search_type)
 	return in_array($search_type, $supported_types);
 }
 
-// Highly specific - create the custom word index table!
+/**
+ * Highly specific function, to create the custom word index table.
+ *
+ * @param $size
+ */
 function smf_db_create_word_search($size)
 {
 	global $smcFunc;

Sources/DbSearch-postgresql.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file contains database functions specific to search related activity.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,22 +16,9 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file contains database functions specific to search related activity.
-
-	void db_search_init()
-		- adds the functions in this file to the $smcFunc array
-
-	boolean smf_db_search_support($search_type)
-		- whether this database type support the search type $search_type
-
-	void smf_db_create_word_search($size)
- 		- create the custom word index table
-
-	resource smf_db_search_query($identifier, $db_string, $db_values = array(), $connection = null)
-		- returns the correct query for this search type.
-*/
-
-// Add the file functions to the $smcFunc array.
+/**
+ *  Add the file functions to the $smcFunc array.
+ */
 function db_search_init()
 {
 	global $smcFunc;
@@ -43,7 +32,11 @@ function db_search_init()
 		);
 }
 
-// Does this database type support this search type?
+/**
+ * This function will tell you whether this database type supports this search type.
+ *
+ * @param string $search_type
+ */
 function smf_db_search_support($search_type)
 {
 	$supported_types = array('custom');
@@ -51,7 +44,14 @@ function smf_db_search_support($search_type)
 	return in_array($search_type, $supported_types);
 }
 
-// Returns the correct query for this search type.
+/**
+ * Returns the correct query for this search type.
+ *
+ * @param string $identifier
+ * @param string $db_string
+ * @param array $db_values, default array()
+ * @param resource $connection
+ */
 function smf_db_search_query($identifier, $db_string, $db_values = array(), $connection = null)
 {
 	global $smcFunc;
@@ -99,7 +99,11 @@ function smf_db_search_query($identifier, $db_string, $db_values = array(), $con
 	return $return;
 }
 
-// Highly specific - create the custom word index table!
+/**
+ * Highly specific function, to create the custom word index table.
+ *
+ * @param $size
+ */
 function smf_db_create_word_search($size)
 {
 	global $smcFunc;

Sources/DbSearch-sqlite.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file contains database functions specific to search related activity.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,22 +16,9 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file contains database functions specific to search related activity.
-
-	void db_search_init()
-		- adds the functions in this file to the $smcFunc array
-
-	boolean smf_db_search_support($search_type)
-		- whether this database type support the search type $search_type
-
-	void smf_db_create_word_search($size)
- 		- create the custom word index table
-
- 	resource smf_db_search_query($identifier, $db_string, $db_values = array(), $connection = null)
-		- returns the correct query for this search type.
-*/
-
-// Add the file functions to the $smcFunc array.
+/**
+ *  Add the file functions to the $smcFunc array.
+ */
 function db_search_init()
 {
 	global $smcFunc;
@@ -43,7 +32,11 @@ function db_search_init()
 		);
 }
 
-// Does this database type support this search type?
+/**
+ * This function will tell you whether this database type supports this search type.
+ *
+ * @param string $search_type
+ */
 function smf_db_search_support($search_type)
 {
 	$supported_types = array('custom');
@@ -51,7 +44,14 @@ function smf_db_search_support($search_type)
 	return in_array($search_type, $supported_types);
 }
 
-// Returns the correct query for this search type.
+/**
+ * Returns the correct query for this search type.
+ *
+ * @param string $identifier
+ * @param string $db_string
+ * @param array $db_values, default array()
+ * @param resource $connection
+ */
 function smf_db_search_query($identifier, $db_string, $db_values = array(), $connection = null)
 {
 	global $smcFunc;
@@ -83,7 +83,11 @@ function smf_db_search_query($identifier, $db_string, $db_values = array(), $con
 	return $return;
 }
 
-// Highly specific - create the custom word index table!
+/**
+ * Highly specific function, to create the custom word index table.
+ *
+ * @param $size
+ */
 function smf_db_create_word_search($size)
 {
 	global $smcFunc;

Sources/Display.php

@@ -1,6 +1,9 @@
 <?php
 
 /**
+ * This is perhaps the most important and probably most accessed file in all
+ * of SMF.  This file controls topic, message, and attachment display.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,52 +17,16 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This is perhaps the most important and probably most accessed files in all
-	of SMF.  This file controls topic, message, and attachment display.  It
-	does so with the following functions:
-
-	void Display()
-		- loads the posts in a topic up so they can be displayed.
-		- supports wireless, using wap/wap2/imode and the Wireless templates.
-		- uses the main sub template of the Display template.
-		- requires a topic, and can go to the previous or next topic from it.
-		- jumps to the correct post depending on a number/time/IS_MSG passed.
-		- depends on the messages_per_page, defaultMaxMessages and enableAllMessages settings.
-		- is accessed by ?topic=id_topic.START.
-
-	array prepareDisplayContext(bool reset = false)
-		- actually gets and prepares the message context.
-		- starts over from the beginning if reset is set to true, which is
-		  useful for showing an index before or after the posts.
-
-	void Download()
-		- downloads an attachment or avatar, and increments the downloads.
-		- requires the view_attachments permission. (not for avatars!)
-		- disables the session parser, and clears any previous output.
-		- depends on the attachmentUploadDir setting being correct.
-		- is accessed via the query string ?action=dlattach.
-		- views to attachments and avatars do not increase hits and are not
-		  logged in the "Who's Online" log.
-
-	array loadAttachmentContext(int id_msg)
-		- loads an attachment's contextual data including, most importantly,
-		  its size if it is an image.
-		- expects the $attachments array to have been filled with the proper
-		  attachment data, as Display() does.
-		- requires the view_attachments permission to calculate image size.
-		- 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.
-
-	int approved_attach_sort(array a, array b)
-		- a sort function for putting unapproved attachments first.
-
-	void QuickInTopicModeration()
-		- in-topic quick moderation.
-
-*/
-
-// The central part of the board - topic display.
+/**
+ * The central part of the board - topic display.
+ * This function loads the posts in a topic up so they can be displayed.
+ * It supports wireless, using wap/wap2/imode and the Wireless templates.
+ * It uses the main sub template of the Display template.
+ * It requires a topic, and can go to the previous or next topic from it.
+ * It jumps to the correct post depending on a number/time/IS_MSG passed.
+ * It depends on the messages_per_page, defaultMaxMessages and enableAllMessages settings.
+ * It is accessed by ?topic=id_topic.START.
+ */
 function Display()
 {
 	global $scripturl, $txt, $modSettings, $context, $settings;
@@ -1088,7 +1055,13 @@ function Display()
 	}
 }
 
-// Callback for the message display.
+/**
+ * Callback for the message display.
+ * It actually gets and prepares the message context.
+ * This functionb 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.
+ */
 function prepareDisplayContext($reset = false)
 {
 	global $settings, $txt, $modSettings, $scripturl, $options, $user_info, $smcFunc;
@@ -1211,7 +1184,14 @@ function prepareDisplayContext($reset = false)
 	return $output;
 }
 
-// Download an attachment.
+/**
+ * This downloads an attachment or avatar, and increments the downloads.
+ * It requires the view_attachments permission. (not for avatars!)
+ * It disables the session parser, and clears any previous output.
+ * It depends on the attachmentUploadDir setting being correct.
+ * It is accessed via the query string ?action=dlattach.
+ * Views to attachments and avatars do not increase hits and are not logged in the "Who's Online" log.
+ */
 function Download()
 {
 	global $txt, $modSettings, $user_info, $scripturl, $context, $sourcedir, $topic, $smcFunc;
@@ -1445,7 +1425,14 @@ function Download()
 
 	obExit(false);
 }
-
+/**
+ * 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.
+ *  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.
+ */
 function loadAttachmentContext($id_msg)
 {
 	global $attachments, $modSettings, $txt, $scripturl, $topic, $sourcedir, $smcFunc;
@@ -1610,7 +1597,12 @@ function loadAttachmentContext($id_msg)
 	return $attachmentData;
 }
 
-// A sort function for putting unapproved attachments first.
+/**
+ * A sort function for putting unapproved attachments first.
+ * @param $a
+ * @param $b
+ * @return int, -1, 0, 1
+ */
 function approved_attach_sort($a, $b)
 {
 	if ($a['is_approved'] == $b['is_approved'])
@@ -1619,7 +1611,9 @@ function approved_attach_sort($a, $b)
 	return $a['is_approved'] > $b['is_approved'] ? -1 : 1;
 }
 
-// In-topic quick moderation.
+/**
+ * In-topic quick moderation.
+ */
 function QuickInTopicModeration()
 {
 	global $sourcedir, $topic, $board, $user_info, $smcFunc, $modSettings, $context;

Sources/Errors.php

@@ -1,6 +1,10 @@
 <?php
 
 /**
+ * The purpose of this file is... errors. (hard to guess, I guess?)  It takes
+ * care of logging, error messages, error handling, database errors, and
+ * error log administration.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,57 +18,13 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	The purpose of this file is... errors. (hard to guess, huh?)  It takes
-	care of logging, error messages, error handling, database errors, and
-	error log administration.  It does this with:
-
-	bool db_fatal_error(bool loadavg = false)
-		- calls show_db_error().
-		- this is used for database connection error handling.
-		- loadavg means this is a load average problem, not a database error.
-
-	string log_error(string error_message, string error_type = general,
-			string filename = none, int line = none)
-		- logs an error, if error logging is enabled.
-		- depends on the enableErrorLogging setting.
-		- filename and line should be __FILE__ and __LINE__, respectively.
-		- returns the error message. (ie. die(log_error($msg));)
-
-	void fatal_error(string error_message, mixed (bool or string) log = general)
-		- stops execution and displays an error message.
-		- logs the error message if log is missing or true.
-
-	void fatal_lang_error(string error_message_key, mixed (bool or string) log = general,
-			array sprintf = array())
-		- stops execution and displays an error message by key.
-		- uses the string with the error_message_key key.
-		- loads the Errors language file.
-		- applies the sprintf information if specified.
-		- the information is logged if log is true or missing.
-		- logs the error in the forum's default language while displaying the error
-		  message in the user's language
-
-	void error_handler(int error_level, string error_string, string filename,
-			int line)
-		- this is a standard PHP error handler replacement.
-		- dies with fatal_error() if the error_level matches with
-		  error_reporting.
-
-	void setup_fatal_error_context(string error_message)
-		- uses the fatal_error sub template of the Errors template - or the
-		  error sub template in the Wireless template.
-		- used by fatal_error() and fatal_lang_error()
-
-	void show_db_error(bool loadavg = false)
-		- called by db_fatal_error() function
-		- shows a complete page independent of language files or themes.
-		- used only if there's no way to connect to the database or the
-		  load averages are too high to do so.
-		- loadavg means this is a load average problem, not a database error.
-		- stops further execution of the script.
-*/
-
-// Handle fatal errors - like connection errors or load average problems
+/**
+ * Handle fatal errors - like connection errors or load average problems.
+ * This calls show_db_error(), which is used for database connection error handling.
+ * @todo when awake: clean up this terrible terrible ugliness.
+ *
+ * @param bool $loadavg - whether it's a load average problem...
+ */
 function db_fatal_error($loadavg = false)
 {
 	global $sourcedir;
@@ -75,7 +35,17 @@ function db_fatal_error($loadavg = false)
 	return false;
 }
 
-// Log an error, if the option is on.
+/**
+ * Log an error, if the error logging is enabled.
+ * 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
+ * @param int $line = null
+ * @return string, the error message
+ */
 function log_error($error_message, $error_type = 'general', $file = null, $line = null)
 {
 	global $txt, $modSettings, $sc, $user_info, $smcFunc, $scripturl, $last_error;
@@ -149,7 +119,12 @@ function log_error($error_message, $error_type = 'general', $file = null, $line
 	return $error_message;
 }
 
-// An irrecoverable error.
+/**
+ * An irrecoverable error. This function stops execution and displays an error message.
+ * It logs the error message if $log is specified.
+ * @param string $error
+ * @param string $log = 'general'
+ */
 function fatal_error($error, $log = 'general')
 {
 	global $txt, $context, $modSettings;
@@ -161,7 +136,18 @@ function fatal_error($error, $log = 'general')
 	setup_fatal_error_context($log || (!empty($modSettings['enableErrorLogging']) && $modSettings['enableErrorLogging'] == 2) ? log_error($error, $log) : $error);
 }
 
-// A fatal error with a message stored in the language file.
+/**
+ * A fatal error with a message stored in the language file.
+ * This function stops executing and displays an error message by key.
+ * It uses the string with the error_message_key key.
+ * It logs the error in the forum's default language while displaying the error
+ * message in the user's language.
+ * @uses Errors language file and applies the $sprintf information if specified.
+ * the information is logged if log is specified.
+ * @param $error
+ * @param $log
+ * @param $sprintf
+ */
 function fatal_lang_error($error, $log = 'general', $sprintf = array())
 {
 	global $txt, $language, $modSettings, $user_info, $context;
@@ -198,7 +184,14 @@ function fatal_lang_error($error, $log = 'general', $sprintf = array())
 	setup_fatal_error_context($error_message);
 }
 
-// Handler for standard error messages.
+/**
+ * Handler for standard error messages, standard PHP error handler replacement.
+ * It dies with fatal_error() if the error_level matches with error_reporting.
+ * @param int $error_level
+ * @param string $error_string
+ * @param string $file
+ * @param int $line
+ */
 function error_handler($error_level, $error_string, $file, $line)
 {
 	global $settings, $modSettings, $db_show_debug;
@@ -273,6 +266,12 @@ function error_handler($error_level, $error_string, $file, $line)
 		die('Hacking attempt...');
 }
 
+/**
+ * It is called by fatal_error() and fatal_lang_error().
+ * @uses Errors template, fatal_error sub template, or Wireless template,
+ * error sub template.
+ * @param string $error_message
+ */
 function setup_fatal_error_context($error_message)
 {
 	global $context, $txt, $ssi_on_error_method;
@@ -332,7 +331,15 @@ function setup_fatal_error_context($error_message)
 	trigger_error('Hacking attempt...', E_USER_ERROR);
 }
 
-// Show an error message for the connection problems.
+/**
+ * Show an error message for the connection problems... or load average.
+ * It is called by db_fatal_error() function.
+ * It shows a complete page independent of language files or themes.
+ * It is used only if there's no way to connect to the database or the load averages
+ * are too high to do so.
+ * It stops further execution of the script.
+ * @param bool $loadavg - whether it's a load average problem...
+ */
 function show_db_error($loadavg = false)
 {
 	global $sourcedir, $mbname, $maintenance, $mtitle, $mmessage, $modSettings;

Sources/Groups.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file currently just shows group info, and allows certain priviledged members to add/remove members.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,39 +16,11 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/* This file currently just shows group info, and allows certain privaledged members to add/remove members.
-
-	void Groups()
-		- allows moderators and users to access the group showing functions.
-		- handles permission checks, and puts the moderation bar on as required.
-
-	void MembergroupMembers()
-		- can be called from ManageMembergroups if it needs templating within the admin environment.
-		- show a list of members that are part of a given membergroup.
-		- called by ?action=moderate;area=viewgroups;sa=members;group=x
-		- requires the manage_membergroups permission.
-		- uses the group_members sub template of ManageMembergroups.
-		- allows to add and remove members from the selected membergroup.
-		- allows sorting on several columns.
-		- redirects to itself.
-
-	int list_getGroupRequestCount(string where)
-		- callback function for createList()
-		- returns the count of group requests
-
-	array list_getGroupRequests(int start, int items_per_page, string sort, string where)
-		- callback function for createList()
-		- returns an array of group requests
-		- each group request has:
-			'id'
-			'member_link'
-			'group_link'
-			'reason'
-			'time_submitted'
-
-*/
-
-// Entry point, permission checks, admin bars, etc.
+/**
+ * Entry point function, permission checks, admin bars, etc.
+ * It allows moderators and users to access the group showing functions.
+ * It handles permission checks, and puts the moderation bar on as required.
+ */
 function Groups()
 {
 	global $context, $txt, $scripturl, $sourcedir, $user_info;
@@ -88,7 +62,9 @@ function Groups()
 	$subActions[$_REQUEST['sa']][0]();
 }
 
-// This very simply lists the groups, nothing snazy.
+/**
+ * This very simply lists the groups, nothing snazy.
+ */
 function GroupList()
 {
 	global $txt, $scripturl, $user_profile, $user_info, $context, $settings, $modSettings, $smcFunc, $sourcedir;
@@ -246,7 +222,12 @@ function GroupList()
 	$context['default_list'] = 'group_lists';
 }
 
-// Get the group information for the list.
+/**
+ * Get the group information for the list.
+ * @param int $start
+ * @param int $items_per_page
+ * @param int $sort
+ */
 function list_getGroups($start, $items_per_page, $sort)
 {
 	global $smcFunc, $txt, $scripturl, $user_info, $settings;
@@ -355,7 +336,11 @@ function list_getGroups($start, $items_per_page, $sort)
 	return $groups;
 }
 
-// How many groups are there that are visible?
+/**
+ * How many groups are there that are visible?
+ *
+ * @return int, the groups count.
+ */
 function list_getGroupCount()
 {
 	global $smcFunc;
@@ -378,7 +363,17 @@ function list_getGroupCount()
 	return $group_count;
 }
 
-// Display members of a group, and allow adding of members to a group. Silly function name though ;)
+/**
+ * Display members of a group, and allow adding of members to a group. Silly function name though ;)
+ * It can be called from ManageMembergroups if it needs templating within the admin environment.
+ * It shows a list of members that are part of a given membergroup.
+ * It is called by ?action=moderate;area=viewgroups;sa=members;group=x
+ * It requires the manage_membergroups permission.
+ * It allows to add and remove members from the selected membergroup.
+ * It allows sorting on several columns.
+ * It redirects to itself.
+ * @uses ManageMembergroups template, group_members sub template.
+ */
 function MembergroupMembers()
 {
 	global $txt, $scripturl, $context, $modSettings, $sourcedir, $user_info, $settings, $smcFunc;
@@ -620,7 +615,9 @@ function MembergroupMembers()
 	$context['page_title'] = $txt['membergroups_members_title'] . ': ' . $context['group']['name'];
 }
 
-// Show and manage all group requests.
+/**
+ * Show and manage all group requests.
+ */
 function GroupRequests()
 {
 	global $txt, $context, $scripturl, $user_info, $sourcedir, $smcFunc, $modSettings, $language;
@@ -914,6 +911,13 @@ function GroupRequests()
 	$context['default_list'] = 'group_request_list';
 }
 
+/**
+ * Callback function for createList().
+ *
+ * @param $where
+ * @param $where_parameters
+ * @return int, the count of group requests
+ */
 function list_getGroupRequestCount($where, $where_parameters)
 {
 	global $smcFunc;
@@ -931,6 +935,22 @@ function list_getGroupRequestCount($where, $where_parameters)
 	return $totalRequests;
 }
 
+/**
+ * Callback function for createList()
+ *
+ * @param int $start
+ * @param int $items_per_page
+ * @param string $sort
+ * @param string $where
+ * @param string $where_parameters
+ * @return array, an array of group requests
+ * Each group request has:
+ * 		'id'
+ * 		'member_link'
+ * 		'group_link'
+ * 		'reason'
+ * 		'time_submitted'
+ */
 function list_getGroupRequests($start, $items_per_page, $sort, $where, $where_parameters)
 {
 	global $smcFunc, $txt, $scripturl;

Sources/Help.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file has the important job of taking care of help messages and the help center.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,25 +16,19 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file has the important job of taking care of help messages and the
-	help center.  It does this with two simple functions:
+/*
 
-	void ShowHelp()
-		- loads information needed for the help section.
-		- accesed by ?action=help.
-		- uses the Help template and Manual language file.
 
 	void ShowAdminHelp()
-		- shows a popup for administrative or user help.
-		- uses the help parameter to decide what string to display and where
-		  to get the string from. ($helptxt or $txt?)
-		- loads the ManagePermissions language file if the help starts with
-		  permissionhelp.
-		- uses the Help template, popup sub template, no layers.
-		- accessed via ?action=helpadmin;help=??.
+
 */
 
-// Redirect to the user help ;).
+/**
+ * Redirect to the user help ;).
+ * It loads information needed for the help section.
+ * It is accessed by ?action=help.
+ * @uses Help template and Manual language file.
+ */
 function ShowHelp()
 {
 	global $scripturl, $context, $txt;
@@ -69,6 +65,15 @@ function ShowHelp()
 }
 
 // Show some of the more detailed help to give the admin an idea...
+/**
+ * Show some of the more detailed help to give the admin an idea...
+ * It shows a popup for administrative or user help.
+ * It uses the help parameter to decide what string to display and where to get
+ * the string from. ($helptxt or $txt?)
+ * It is accessed via ?action=helpadmin;help=?.
+ * @uses ManagePermissions language file, if the help starts with permissionhelp.
+ * @uses Help template, popup sub template, no layers.
+ */
 function ShowAdminHelp()
 {
 	global $txt, $helptxt, $context, $scripturl;

Sources/Karma.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file contains one humble function, which applauds or smites a user.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,19 +16,13 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file contains one humble function, which applauds or smites a user.
-
-	void ModifyKarma()
-		- gives or takes karma from a user.
-		- redirects back to the referrer afterward, whether by javascript or
-		  the passed parameters.
-		- requires the karma_edit permission, and that the user isn't a guest.
-		- depends on the karmaMode, karmaWaitTime, and karmaTimeRestrictAdmins
-		  settings.
-		- is accessed via ?action=modifykarma.
-*/
-
-// Modify a user's karma.
+/**
+ * Modify a user's karma.
+ * It redirects back to the referrer afterward, whether by javascript or the passed parameters.
+ * Requires the karma_edit permission, and that the user isn't a guest.
+ * It depends on the karmaMode, karmaWaitTime, and karmaTimeRestrictAdmins settings.
+ * It is accessed via ?action=modifykarma.
+ */
 function ModifyKarma()
 {
 	global $modSettings, $txt, $user_info, $topic, $smcFunc, $context;
@@ -154,7 +150,9 @@ function ModifyKarma()
 	}
 }
 
-// What's this?  I dunno, what are you talking about?  Never seen this before, nope.  No siree.
+/**
+ *  What's this?  I dunno, what are you talking about?  Never seen this before, nope.  No sir.
+ */
 function BookOfUnknown()
 {
 	global $context;