! phpDoc updates

Sources/Avatar.php

@@ -17,6 +17,9 @@
 if (!defined('SMF'))
 	die('No direct access...');
 
+/**
+ * Shows an avatar based on $_GET['attach']
+ */
 function showAvatar()
 {
 	global $smcFunc, $modSettings, $maintenance;

Sources/Calendar.php

@@ -166,8 +166,8 @@ function CalendarMain()
 /**
  * This function processes posting/editing/deleting a calendar event.
  *
- * 	- calls Post() function if event is linked to a post.
- *  - calls insertEvent() to insert the event if not linked to post.
+ * 	- calls {@link Post.php|Post() Post()} function if event is linked to a post.
+ *  - calls {@link Subs-Calendar.php|insertEvent() insertEvent()} to insert the event if not linked to post.
  *
  * It requires the calendar_post permission to use.
  * It uses the event_post sub template in the Calendar template.

Sources/Class-BrowserDetect.php

@@ -37,7 +37,7 @@ class browser_detector
 	/**
 	 * Holds if the detected device may be a mobile one
 	 *
-	 * @var type
+	 * @var boolean
 	 */
 	private $_is_mobile = null;
 

Sources/Class-CurlFetchWeb.php

@@ -41,7 +41,7 @@ class curl_fetch_web_data
 	/**
 	 * Set the default items for this class
 	 *
-	 * @var type
+	 * @var array
 	 */
 	private $default_options = array(
 		CURLOPT_RETURNTRANSFER	=> 1, // Get returned value as a string (don't output it)
@@ -61,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 array $options cURL options as an array
+	* @param int $max_redirect use to overide the default of 3
 	*/
 	public function __construct($options = array(), $max_redirect = 3)
 	{
@@ -78,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 string $url the site we are going to fetch
+	* @param array $post_data any post data as form name => value
 	*/
 	public function get_url_data($url, $post_data = array())
 	{
@@ -101,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 string $url site to fetch
+	* @param boolean $redirect flag to indicate if this was a redirect request or not
 	* @return boolean
 	*/
 	private function curl_request($url, $redirect = false)
@@ -157,9 +157,9 @@ 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
-	* @return new url location
+	* @param string $last_url where we went to
+	* @param string $new_url where we were redirected to
+	* @return string new url location
 	*/
 	private function get_redirect_url($last_url = '', $new_url = '')
 	{
@@ -182,8 +182,8 @@ 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
-	* @return type
+	* @param string $area used to return an area such as body, header, error
+	* @return string
 	*/
 	public function result($area = '')
 	{
@@ -201,8 +201,8 @@ class curl_fetch_web_data
 	*  - Can be called as ->result_raw(x) where x is a specific loop results.
 	*  - Call as ->result_raw() for everything.
 	*
-	* @param type $response_number
-	* @return type
+	* @param string $response_number
+	* @return array|string The entire response array or just the specified response
 	*/
 	public function result_raw($response_number = '')
 	{
@@ -220,8 +220,8 @@ class curl_fetch_web_data
 	*  - forms the date (for post) in to a string var=xyz&var2=abc&var3=123
 	*  - drops vars with @ since we don't support sending files (uploading)
 	*
-	* @param type $post_data
-	* @return type
+	* @param array|string $post_data
+	* @return string A string of post data
 	*/
 	private function build_post_data($post_data)
 	{
@@ -273,8 +273,8 @@ class curl_fetch_web_data
 	* Called to initiate a redirect from a 301, 302 or 307 header
 	*  - resets the cURL options for the loop, sets the referrer flag
 	*
-	* @param type $target_url
-	* @param type $referer_url
+	* @param string $target_url
+	* @param string $referer_url
 	*/
 	private function redirect($target_url, $referer_url)
 	{
@@ -289,8 +289,8 @@ class curl_fetch_web_data
 	*  - lowercases everything to make it consistent
 	*
 	* @param type $cr
-	* @param type $header
-	* @return type
+	* @param string $header
+	* @return int The length of the header
 	*/
 	private function header_callback($cr, $header)
 	{

Sources/Class-Graphics.php

@@ -22,6 +22,9 @@
 if (!defined('SMF'))
 	die('No direct access...');
 
+/**
+ * An implementation of the LZW compression algorithm
+ */
 class gif_lzw_compression
 {
 	public $MAX_LZW_BITS;

Sources/Class-Package.php

@@ -29,7 +29,7 @@ class xmlArray
 
 	/**
 	 * holds debugging level
-	 * @var type
+	 * @var int
 	 */
 	public $debug_level;
 
@@ -80,6 +80,7 @@ class xmlArray
 	 * Get the root element's name.
 	 * Example use:
 	 *  echo $element->name();
+	 * @return string The root element's name
 	 */
 	public function name()
 	{
@@ -94,6 +95,7 @@ class xmlArray
 	 *  $data = $xml->fetch('html/head/title');
 	 * @param string $path - the path to the element to fetch
 	 * @param bool $get_elements - whether to include elements
+	 * @return string The value or attribute of the specified element
 	 */
 	public function fetch($path, $get_elements = false)
 	{
@@ -315,6 +317,7 @@ class xmlArray
 	 *  print_r($xml->to_array());
 	 *
 	 * @param string $path the path to output.
+	 * @return array An array of XML data
 	 */
 	public function to_array($path = null)
 	{
@@ -340,6 +343,7 @@ class xmlArray
 	 * Parse data into an array. (privately used...)
 	 *
 	 * @param string $data to parse
+	 * @return array The parsed array
 	 */
 	protected function _parse($data)
 	{
@@ -487,8 +491,8 @@ class xmlArray
 	/**
 	 * Get a specific element's xml. (privately used...)
 	 *
-	 * @param $array
-	 * @param $indent
+	 * @param array $array An array of element data
+	 * @param null|int $indent How many levels to indent the elements (null = no indent)
 	 */
 	protected function _xml($array, $indent)
 	{
@@ -540,8 +544,8 @@ class xmlArray
 	/**
 	 * Return an element as an array
 	 *
-	 * @param type $array
-	 * @return type
+	 * @param array $array
+	 * @return string|array A string with the element's value or an array of element datas
 	 */
 	protected function _array($array)
 	{
@@ -567,7 +571,8 @@ class xmlArray
 	/**
 	 * Parse out CDATA tags. (htmlspecialchars them...)
 	 *
-	 * @param $data
+	 * @param string $data The data with CDATA tags included
+	 * @return string The data contained within CDATA tags
 	 */
 	function _to_cdata($data)
 	{
@@ -604,7 +609,8 @@ class xmlArray
 	/**
 	 * Turn the CDATAs back to normal text.
 	 *
-	 * @param $data
+	 * @param string $data
+	 * @return string The transformed data	 
 	 */
 	protected function _from_cdata($data)
 	{
@@ -621,6 +627,7 @@ class xmlArray
 	 * Given an array, return the text from that array. (recursive and privately used.)
 	 *
 	 * @param array $array
+	 * @return string The text from the array
 	 */
 	protected function _fetch($array)
 	{
@@ -654,6 +661,7 @@ class xmlArray
 	 * @param string $path
 	 * @param int $level
 	 * @param bool $no_error
+	 * @return string|array The specified array (or the contents of said array if there's only one result) 
 	 */
 	protected function _path($array, $path, $level, $no_error = false)
 	{
@@ -725,29 +733,29 @@ class ftp_connection
 
 	/**
 	 * holds any errors
-	 * @var type
+	 * @var string
 	 */
 	public $error;
 
 	/**
 	 * holds last message from the server
-	 * @var type
+	 * @var string
 	 */
 	public $last_message;
 
 	/**
 	 * Passive connection
-	 * @var type
+	 * @var boolean
 	 */
 	public $pasv;
 
 	/**
 	 * Create a new FTP connection...
 	 *
-	 * @param type $ftp_server
-	 * @param type $ftp_port
-	 * @param type $ftp_user
-	 * @param type $ftp_pass
+	 * @param string $ftp_server
+	 * @param int $ftp_port
+	 * @param string $ftp_user
+	 * @param string $ftp_pass
 	 */
 	public function __construct($ftp_server, $ftp_port = 21, $ftp_user = 'anonymous', $ftp_pass = 'ftpclient@simplemachines.org')
 	{
@@ -763,11 +771,10 @@ class ftp_connection
 	/**
 	 * Connects to a server
 	 *
-	 * @param type $ftp_server
-	 * @param type $ftp_port
-	 * @param type $ftp_user
-	 * @param type $ftp_pass
-	 * @return type
+	 * @param string $ftp_server
+	 * @param int $ftp_port
+	 * @param string $ftp_user
+	 * @param string $ftp_pass
 	 */
 	public function connect($ftp_server, $ftp_port = 21, $ftp_user = 'anonymous', $ftp_pass = 'ftpclient@simplemachines.org')
 	{
@@ -814,8 +821,8 @@ class ftp_connection
 	/**
 	 * Changes to a directory (chdir) via the ftp connection
 	 *
-	 * @param type $ftp_path
-	 * @return boolean
+	 * @param string $ftp_path The path to the directory we want to change to
+	 * @return boolean Whether or not the operation was successful
 	 */
 	public function chdir($ftp_path)
 	{
@@ -839,9 +846,9 @@ class ftp_connection
 	/**
 	 * Changes a files atrributes (chmod)
 	 *
-	 * @param string $ftp_file
-	 * @param type $chmod
-	 * @return boolean
+	 * @param string $ftp_file The file to CHMOD
+	 * @param int|string $chmod The value for the CHMOD operation
+	 * @return boolean Whether or not the operation was successful
 	 */
 	public function chmod($ftp_file, $chmod)
 	{
@@ -865,8 +872,8 @@ class ftp_connection
 	/**
 	 * Deletes a file
 	 *
-	 * @param type $ftp_file
-	 * @return boolean
+	 * @param string $ftp_file The file to delete
+	 * @return boolean Whether or not the operation was successful
 	 */
 	public function unlink($ftp_file)
 	{
@@ -894,8 +901,8 @@ class ftp_connection
 	/**
 	 * Reads the response to the command from the server
 	 *
-	 * @param type $desired
-	 * @return type
+	 * @param string $desired The desired response
+	 * @return boolean Whether or not we got the desired response
 	 */
 	public function check_response($desired)
 	{
@@ -912,7 +919,7 @@ class ftp_connection
 	/**
 	 * Used to create a passive connection
 	 *
-	 * @return boolean
+	 * @return boolean Whether the passive connection was created successfully
 	 */
 	public function passive()
 	{
@@ -950,8 +957,8 @@ class ftp_connection
 	/**
 	 * Creates a new file on the server
 	 *
-	 * @param type $ftp_file
-	 * @return boolean
+	 * @param string $ftp_file The file to create
+	 * @return boolean Whether or not the file was created successfully
 	 */
 	public function create_file($ftp_file)
 	{
@@ -989,9 +996,9 @@ class ftp_connection
 	/**
 	 * Generates a direcotry listing for the current directory
 	 *
-	 * @param type $ftp_path
-	 * @param type $search
-	 * @return boolean
+	 * @param string $ftp_path The path to the directory
+	 * @param type $search Whether or not to get a recursive directory listing
+	 * @return string|boolean The results of the command or false if unsuccessful
 	 */
 	public function list_dir($ftp_path = '', $search = false)
 	{
@@ -1034,8 +1041,8 @@ class ftp_connection
 	/**
 	 * Determins the current dirctory we are in
 	 *
-	 * @param type $file
-	 * @param type $listing
+	 * @param string $file The name of a file
+	 * @param string $listing A directory listing or null to generate one
 	 * @return string|boolean
 	 */
 	public function locate($file, $listing = null)
@@ -1081,8 +1088,8 @@ class ftp_connection
 	/**
 	 * Creates a new directory on the server
 	 *
-	 * @param type $ftp_dir
-	 * @return boolean
+	 * @param string $ftp_dir The name of the directory to create
+	 * @return boolean Whether or not the operation was successful
 	 */
 	public function create_dir($ftp_dir)
 	{
@@ -1104,9 +1111,9 @@ class ftp_connection
 	/**
 	 * Detects the current path
 	 *
-	 * @param type $filesystem_path
-	 * @param type $lookup_file
-	 * @return type
+	 * @param string $filesystem_path The full path from the filesystem
+	 * @param string $lookup_file The name of a file in the specified path
+	 * @return array An array of detected info - username, path from FTP root and whether or not the current path was found
 	 */
 	public function detect_path($filesystem_path, $lookup_file = null)
 	{
@@ -1156,7 +1163,7 @@ class ftp_connection
 	/**
 	 * Close the ftp connection
 	 *
-	 * @return boolean
+	 * @return boolean Always returns true
 	 */
 	public function close()
 	{

Sources/DbExtra-mysql.php

@@ -36,8 +36,8 @@ function db_extra_init()
 
 /**
  * Backup $table to $backup_table.
- * @param string $table
- * @param string $backup_table
+ * @param string $table The name of the table to backup
+ * @param string $backup_table The name of the backup table for this table
  * @return resource -the request handle to the table creation query
  */
 function smf_db_backup_table($table, $backup_table)
@@ -169,8 +169,8 @@ function smf_db_backup_table($table, $backup_table)
 
 /**
  * This function optimizes a table.
- * @param string $table - the table to be optimized
- * @return how much it was gained
+ * @param string $table The table to be optimized
+ * @return int How much space was gained
  */
 function smf_db_optimize_table($table)
 {
@@ -217,9 +217,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
- * @return array, an array of table names. (strings)
+ * @param string|boolean $db string The database name or false to use the current DB
+ * @param string|boolean $filter String to filter by or false to list all tables
+ * @return array An array of table names
  */
 function smf_db_list_tables($db = false, $filter = false)
 {
@@ -250,9 +250,9 @@ 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.
- * @param bool $new_table
- * @return string the query to insert the data back in, or an empty string if the table was empty.
+ * @param string $tableName The table to create the inserts for.
+ * @param boolean $new_table Whether or not this is a new table (resets $start and $limit)
+ * @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)
 {
@@ -326,8 +326,8 @@ function smf_db_insert_sql($tableName, $new_table = false)
 /**
  * Dumps the schema (CREATE) for a table.
  * @todo why is this needed for?
- * @param string $tableName - the table
- * @return string - the CREATE statement as string
+ * @param string $tableName The name of the table
+ * @return string The "CREATE TABLE" SQL string for this table
  */
 function smf_db_table_sql($tableName)
 {
@@ -436,7 +436,7 @@ function smf_db_table_sql($tableName)
 
 /**
  *  Get the version number.
- *  @return string - the version
+ *  @return string The version
  */
 function smf_db_get_version()
 {

Sources/DbExtra-postgresql.php

@@ -36,8 +36,8 @@ function db_extra_init()
 
 /**
  * Backup $table to $backup_table.
- * @param string $table
- * @param string $backup_table
+ * @param string $table The name of the table to backup
+ * @param string $backup_table The name of the backup table for this table
  * @return resource -the request handle to the table creation query
  */
 function smf_db_backup_table($table, $backup_table)
@@ -82,8 +82,8 @@ function smf_db_backup_table($table, $backup_table)
 
 /**
  * This function optimizes a table.
- * @param string $table - the table to be optimized
- * @return how much it was gained
+ * @param string $table The table to be optimized
+ * @return int How much space was gained
  */
 function smf_db_optimize_table($table)
 {
@@ -113,9 +113,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
- * @return array an array of table names. (strings)
+ * @param string|boolean $db string The database name or false to use the current DB
+ * @param string|boolean $filter String to filter by or false to list all tables
+ * @return array An array of table names
  */
 function smf_db_list_tables($db = false, $filter = false)
 {
@@ -145,9 +145,9 @@ 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.
- * @param bool new_table
- * @return string the query to insert the data back in, or an empty string if the table was empty.
+ * @param string $tableName The table to create the inserts for.
+ * @param boolean $new_table Whether or not this a new table (resets $start and $limit)
+ * @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)
 {
@@ -223,8 +223,8 @@ function smf_db_insert_sql($tableName, $new_table = false)
 /**
  * Dumps the schema (CREATE) for a table.
  * @todo why is this needed for?
- * @param string $tableName - the table
- * @return string - the CREATE statement as string
+ * @param string $tableName The name of the table
+ * @return string The "CREATE TABLE" SQL string for this table
  */
 function smf_db_table_sql($tableName)
 {
@@ -326,7 +326,7 @@ function smf_db_table_sql($tableName)
 
 /**
  *  Get the version number.
- *  @return string - the version
+ *  @return string The version
  */
 function smf_db_get_version()
 {

Sources/DbExtra-sqlite.php

@@ -37,8 +37,8 @@ function db_extra_init()
 
 /**
  * Backup $table to $backup_table.
- * @param string $table
- * @param string $backup_table
+ * @param string $table The name of the table to backup
+ * @param string $backup_table The name of the backup table for this table
  * @return resource -the request handle to the table creation query
  */
 function smf_db_backup_table($table, $backup_table)
@@ -130,8 +130,8 @@ function smf_db_backup_table($table, $backup_table)
 
 /**
  * This function optimizes a table.
- * @param string $table - the table to be optimized
- * @return how much it was gained
+ * @param string $table The table to be optimized
+ * @return int How much space was gained
  */
 function smf_db_optimize_table($table)
 {
@@ -159,9 +159,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
- * @return array an array of table names. (strings)
+ * @param string|boolean $db string The database name or false to use the current DB
+ * @param string|boolean $filter String to filter by or false to list all tables
+ * @return array An array of table names
  */
 function smf_db_list_tables($db = false, $filter = false)
 {
@@ -192,9 +192,9 @@ 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.
- * @param bool new_table
- * @return string the query to insert the data back in, or an empty string if the table was empty.
+ * @param string $tableName The table to create the inserts for.
+ * @param boolean $new_table Whether or not this a 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)
 {
@@ -276,8 +276,8 @@ function smf_db_insert_sql($tableName, $new_table = false)
 /**
  * Dumps the schema (CREATE) for a table.
  * @todo why is this needed for?
- * @param string $tableName - the table
- * @return string - the CREATE statement as string
+ * @param string $tableName The name of the table
+ * @return string The "CREATE TABLE" SQL string for this table
  */
 function smf_db_table_sql($tableName)
 {
@@ -331,7 +331,7 @@ function smf_db_table_sql($tableName)
 
 /**
  *  Get the version number.
- *  @return string - the version
+ *  @return string The version
  */
 function smf_db_get_version()
 {
@@ -340,7 +340,7 @@ function smf_db_get_version()
 
 /**
  * Simply return the database - and die!
- * Used by DumpDatabase.php.
+ * Used by {@link DumpDatabase.php}.
  */
 function smf_db_get_backup()
 {

Sources/DbExtra-sqlite3.php

@@ -37,8 +37,8 @@ function db_extra_init()
 
 /**
  * Backup $table to $backup_table.
- * @param string $table
- * @param string $backup_table
+ * @param string $table The name of the table to backup
+ * @param string $backup_table The name of the backup table for this table
  * @return resource -the request handle to the table creation query
  */
 function smf_db_backup_table($table, $backup_table)
@@ -130,8 +130,8 @@ function smf_db_backup_table($table, $backup_table)
 
 /**
  * This function optimizes a table.
- * @param string $table - the table to be optimized
- * @return how much it was gained
+ * @param string $table The table to be optimized
+ * @return int How much space was gained
  */
 function smf_db_optimize_table($table)
 {
@@ -159,9 +159,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
- * @return array an array of table names. (strings)
+ * @param string|boolean $db string The database name or false to use the current DB
+ * @param string|boolean $filter String to filter by or false to list all tables
+ * @return array An array of table names
  */
 function smf_db_list_tables($db = false, $filter = false)
 {
@@ -192,9 +192,9 @@ 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.
- * @param bool new_table
- * @return string the query to insert the data back in, or an empty string if the table was empty.
+ * @param string $tableName The table to create the inserts for.
+ * @param boolean $new_table Whether or not this a 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)
 {
@@ -276,8 +276,8 @@ function smf_db_insert_sql($tableName, $new_table = false)
 /**
  * Dumps the schema (CREATE) for a table.
  * @todo why is this needed for?
- * @param string $tableName - the table
- * @return string - the CREATE statement as string
+ * @param string $tableName The name of the table
+ * @return string The "CREATE TABLE" SQL string for this table
  */
 function smf_db_table_sql($tableName)
 {
@@ -331,7 +331,7 @@ function smf_db_table_sql($tableName)
 
 /**
  *  Get the version number.
- *  @return string - the version
+ *  @return string The version
  */
 function smf_db_get_version()
 {
@@ -341,7 +341,7 @@ function smf_db_get_version()
 
 /**
  * Simply return the database - and die!
- * Used by DumpDatabase.php.
+ * Used by {@link DumpDatabase.php}.
  */
 function smf_db_get_backup()
 {

Sources/DbPackages-mysql.php

@@ -83,12 +83,13 @@ function db_packages_init()
  *  	- '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 string $table_name The name of the table to create
+ * @param array $columns An array of column info in the specified format
+ * @param array $indexes An array of index info in the specified format
+ * @param array $parameters Currently not used
+ * @param string $if_exists What to do if the table exists.
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_create_table($table_name, $columns, $indexes = array(), $parameters = array(), $if_exists = 'ignore', $error = 'fatal')
 {
@@ -159,9 +160,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 string $table_name The name of the table to drop
+ * @param array $parameters Not used at the moment
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 {
@@ -199,11 +201,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 to add the column to
+ * @param array $column_info An array of column info ({@see smf_db_create_table})
+ * @param array $parameters Not used?
+ * @param string $if_exists What to do if the column exists. If 'update', column is updated.
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_add_column($table_name, $column_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -252,10 +255,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 string $table_name The name of the table to drop the column from
+ * @param string $column_name The name of the column to drop
+ * @param array $parameters Not used?
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_remove_column($table_name, $column_name, $parameters = array(), $error = 'fatal')
 {
@@ -286,11 +290,11 @@ 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 string $table_name The name of the table this column is in
+ * @param string $old_column The name of the column we want to change
+ * @param array $column_info An array of info about the "new" column definition (see {@link smf_db_create_table()})
+ * @param array $parameters Not used?
+ * @param string $error
  */
 function smf_db_change_column($table_name, $old_column, $column_info, $parameters = array(), $error = 'fatal')
 {
@@ -347,11 +351,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 string $table_name The name of the table to add the index to
+ * @param array $index_info An array of index info (see {@link smf_db_create_table()})
+ * @param array $parameters Not used?
+ * @param string $if_exists What to do if the index exists. If 'update', the definition will be updated.
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -420,10 +425,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 string $table_name The name of the table to remove the index from
+ * @param string $index_name The name of the index to remove
+ * @param array $parameters Not used?
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_remove_index($table_name, $index_name, $parameters = array(), $error = 'fatal')
 {
@@ -472,9 +478,10 @@ 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
+ * @param string $type_name The data type (int, varchar, smallint, etc.)
+ * @param int $type_size The size (8, 255, etc.)
+ * @param boolean $reverse
+ * @return An array containing the appropriate type and size for this DB type
  */
 function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 {
@@ -485,8 +492,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 string $table_name The name of the table
+ * @param array $parameters Not used?
+ * @return An array of table structure - the name, the column info from {@link smf_db_list_columns()} and the index info from {@link smf_db_list_indexes()}
  */
 function smf_db_table_structure($table_name, $parameters = array())
 {
@@ -504,10 +512,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()
- * @return mixed
+ * @param string $table_name The name of the table to get column info for
+ * @param bool $detail Whether or not to return detailed info. If true, returns the column info. If false, just returns the column names.
+ * @param array $parameters Not used?
+ * @return array An array of column names or detailed column info, depending on $detail
  */
 function smf_db_list_columns($table_name, $detail = false, $parameters = array())
 {
@@ -572,10 +580,10 @@ function smf_db_list_columns($table_name, $detail = false, $parameters = array()
 /**
  * Get index information.
  *
- * @param string $table_name
- * @param bool $detail
- * @param array $parameters
- * @return mixed
+ * @param string $table_name The name of the table to get indexes for
+ * @param bool $detail Whether or not to return detailed info.
+ * @param array $parameters Not used?
+ * @return array An array of index names or a detailed array of index info, depending on $detail
  */
 function smf_db_list_indexes($table_name, $detail = false, $parameters = array())
 {
@@ -632,8 +640,8 @@ function smf_db_list_indexes($table_name, $detail = false, $parameters = array()
 /**
  * Creates a query for a column
  *
- * @param array $column
- * @return type
+ * @param array $column An array of column info
+ * @return string The column definition
  */
 function smf_db_create_query_column($column)
 {

Sources/DbPackages-postgresql.php

@@ -83,12 +83,12 @@ function db_packages_init()
  *  	- '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 string $table_name The name of the table to create
+ * @param array $columns An array of column info in the specified format
+ * @param array $indexes An array of index info in the specified format
+ * @param array $parameters Currently not used
+ * @param string $if_exists What to do if the table exists.
+ * @param string $error
  */
 function smf_db_create_table($table_name, $columns, $indexes = array(), $parameters = array(), $if_exists = 'ignore', $error = 'fatal')
 {
@@ -192,11 +192,12 @@ function smf_db_create_table($table_name, $columns, $indexes = array(), $paramet
 }
 
 /**
- * Drop a table.
+ * Drop a table and its associated sequences.
  *
- * @param string $table_name
- * @param array $parameters default array()
- * @param string $error default 'fatal'
+ * @param string $table_name The name of the table to drop
+ * @param array $parameters Not used at the moment
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 {
@@ -251,11 +252,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 to add the column to
+ * @param array $column_info An array of column info (see {@link smf_db_create_table()})
+ * @param array $parameters Not used?
+ * @param string $if_exists What to do if the column exists. If 'update', column is updated.
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_add_column($table_name, $column_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -306,10 +308,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 string $table_name The name of the table to drop the column from
+ * @param string $column_name The name of the column to drop
+ * @param array $parameters Not used?
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_remove_column($table_name, $column_name, $parameters = array(), $error = 'fatal')
 {
@@ -349,11 +352,11 @@ 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 string $table_name The name of the table this column is in
+ * @param $old_column The name of the column we want to change
+ * @param $column_info An array of info about the "new" column definition (see {@link smf_db_create_table()})
+ * @param array $parameters Not used?
+ * @param string $error
  */
 function smf_db_change_column($table_name, $old_column, $column_info, $parameters = array(), $error = 'fatal')
 {
@@ -506,11 +509,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 string $table_name The name of the table to add the index to
+ * @param array $index_info An array of index info (see {@link smf_db_create_table()})
+ * @param array $parameters Not used?
+ * @param string $if_exists What to do if the index exists. If 'update', the definition will be updated.
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -578,10 +582,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 string $table_name The name of the table to remove the index from
+ * @param string $index_name The name of the index to remove
+ * @param array $parameters Not used?
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_remove_index($table_name, $index_name, $parameters = array(), $error = 'fatal')
 {
@@ -631,9 +636,10 @@ 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
+ * @param string $type_name The data type (int, varchar, smallint, etc.)
+ * @param int $type_size The size (8, 255, etc.)
+ * @param boolean $reverse If true, returns specific types for a generic type
+ * @return array An array containing the appropriate type and size for this DB type
  */
 function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 {
@@ -678,8 +684,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 string $table_name The name of the table
+ * @param array $parameters Not used?
+ * @return An array of table structure - the name, the column info from {@link smf_db_list_columns()} and the index info from {@link smf_db_list_indexes()}
  */
 function smf_db_table_structure($table_name, $parameters = array())
 {
@@ -697,10 +704,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()
- * @return mixed
+ * @param string $table_name The name of the table to get column info for
+ * @param bool $detail Whether or not to return detailed info. If true, returns the column info. If false, just returns the column names.
+ * @param array $parameters Not used?
+ * @return array An array of column names or detailed column info, depending on $detail
  */
 function smf_db_list_columns($table_name, $detail = false, $parameters = array())
 {
@@ -759,10 +766,10 @@ function smf_db_list_columns($table_name, $detail = false, $parameters = array()
 /**
  * Get index information.
  *
- * @param string $table_name
- * @param bool $detail
- * @param array $parameters
- * @return mixed
+ * @param string $table_name The name of the table to get indexes for
+ * @param bool $detail Whether or not to return detailed info.
+ * @param array $parameters Not used?
+ * @return array An array of index names or a detailed array of index info, depending on $detail
  */
 function smf_db_list_indexes($table_name, $detail = false, $parameters = array())
 {

Sources/DbPackages-sqlite.php

@@ -84,12 +84,12 @@ function db_packages_init()
  *  	- '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 string $table_name The name of the table to create
+ * @param array $columns An array of column info in the specified format
+ * @param array $indexes An array of index info in the specified format
+ * @param array $parameters Currently not used
+ * @param string $if_exists What to do if the table exists.
+ * @param string $error
  */
 function smf_db_create_table($table_name, $columns, $indexes = array(), $parameters = array(), $if_exists = 'ignore', $error = 'fatal')
 {
@@ -198,10 +198,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 bool $error
- * @param string $error default 'fatal'
+ * @param string $table_name The name of the table to drop
+ * @param array $parameters Not used at the moment
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 {
@@ -236,11 +236,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 to add the column to
+ * @param array $column_info An array of column info ({@see smf_db_create_table})
+ * @param array $parameters Not used?
+ * @param string $if_exists What to do if the column exists. If 'update', column is updated.
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_add_column($table_name, $column_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -274,10 +275,11 @@ 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 string $table_name The name of the table to drop the column from
+ * @param string $column_name The name of the column to drop
+ * @param array $parameters Not used?
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_remove_column($table_name, $column_name, $parameters = array(), $error = 'fatal')
 {
@@ -294,11 +296,11 @@ 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 string $table_name The name of the table this column is in
+ * @param string $old_column The name of the column we want to change
+ * @param array $column_info An array of info about the "new" column definition (see {@link smf_db_create_table()})
+ * @param array $parameters Not used?
+ * @param string $error
  */
 function smf_db_change_column($table_name, $old_column, $column_info, $parameters = array(), $error = 'fatal')
 {
@@ -315,11 +317,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 string $table_name The name of the table to add the index to
+ * @param array $index_info An array of index info (see {@link smf_db_create_table()})
+ * @param array $parameters Not used?
+ * @param string $if_exists What to do if the index exists. If 'update', the definition will be updated.
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -381,10 +384,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 string $table_name The name of the table to remove the index from
+ * @param string $index_name The name of the index to remove
+ * @param array $parameters Not used?
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_remove_index($table_name, $index_name, $parameters = array(), $error = 'fatal')
 {
@@ -419,9 +423,10 @@ 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
+ * @param string $type_name The data type (int, varchar, smallint, etc.)
+ * @param int $type_size The size (8, 255, etc.)
+ * @param boolean $reverse If true, returns specific types for a generic type
+ * @return An array containing the appropriate type and size for this DB type
  */
 function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 {
@@ -461,8 +466,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 string $table_name The name of the table
+ * @param array $parameters Not used?
+ * @return An array of table structure - the name, the column info from {@link smf_db_list_columns()} and the index info from {@link smf_db_list_indexes()}
  */
 function smf_db_table_structure($table_name, $parameters = array())
 {
@@ -481,10 +487,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()
- * @return mixed
+ * @param string $table_name The name of the table to get column info for
+ * @param bool $detail Whether or not to return detailed info. If true, returns the column info. If false, just returns the column names.
+ * @param array $parameters Not used?
+ * @return array An array of column names or detailed column info, depending on $detail
  */
 function smf_db_list_columns($table_name, $detail = false, $parameters = array())
 {
@@ -547,10 +553,10 @@ function smf_db_list_columns($table_name, $detail = false, $parameters = array()
 /**
  * Get index information.
  *
- * @param string $table_name
- * @param bool $detail
- * @param array $parameters
- * @return mixed
+ * @param string $table_name The name of the table to get indexes for
+ * @param bool $detail Whether or not to return detailed info.
+ * @param array $parameters Not used?
+ * @return array An array of index names or a detailed array of index info, depending on $detail
  */
 function smf_db_list_indexes($table_name, $detail = false, $parameters = array())
 {
@@ -609,8 +615,9 @@ function smf_db_list_indexes($table_name, $detail = false, $parameters = array()
 /**
  * Alter table on SQLite.
  *
- * @param string $table_name
- * @param array $columns
+ * @param string $table_name The name of the table
+ * @param array $columns An array of arrays of column info and what to do. Can contain 'remove', an array of names of columns to remove, and/or 'add', an array of details of columns to add (see {@link smf_db_list_columns()})
+ * @return boolean Whether or not the operations were successful
  */
 function smf_db_alter_table($table_name, $columns)
 {

Sources/DbPackages-sqlite3.php

@@ -84,12 +84,12 @@ function db_packages_init()
  *  	- '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 string $table_name The name of the table to create
+ * @param array $columns An array of column info in the specified format
+ * @param array $indexes An array of index info in the specified format
+ * @param array $parameters Currently not used
+ * @param string $if_exists What to do if the table exists.
+ * @param string $error
  */
 function smf_db_create_table($table_name, $columns, $indexes = array(), $parameters = array(), $if_exists = 'ignore', $error = 'fatal')
 {
@@ -198,10 +198,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 bool $error
- * @param string $error default 'fatal'
+ * @param string $table_name The name of the table to drop
+ * @param array $parameters Not used at the moment
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_drop_table($table_name, $parameters = array(), $error = 'fatal')
 {
@@ -236,11 +236,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 to add the column to
+ * @param array $column_info An array of column info (see {@link smf_db_create_table()})
+ * @param array $parameters Not used?
+ * @param string $if_exists What to do if the column exists. If 'update', column is updated.
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_add_column($table_name, $column_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -274,10 +275,11 @@ 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 string $table_name The name of the table to drop the column from
+ * @param string $column_name The name of the column to drop
+ * @param array $parameters Not used?
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_remove_column($table_name, $column_name, $parameters = array(), $error = 'fatal')
 {
@@ -294,11 +296,11 @@ 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 string $table_name The name of the table this column is in
+ * @param $old_column The name of the column we want to change
+ * @param $column_info An array of info about the "new" column definition (see {@link smf_db_create_table()})
+ * @param array $parameters Not used?
+ * @param string $error
  */
 function smf_db_change_column($table_name, $old_column, $column_info, $parameters = array(), $error = 'fatal')
 {
@@ -315,11 +317,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 string $table_name The name of the table to add the index to
+ * @param array $index_info An array of index info (see {@link smf_db_create_table()})
+ * @param array $parameters Not used?
+ * @param string $if_exists What to do if the index exists. If 'update', the definition will be updated.
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_add_index($table_name, $index_info, $parameters = array(), $if_exists = 'update', $error = 'fatal')
 {
@@ -381,10 +384,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 string $table_name The name of the table to remove the index from
+ * @param string $index_name The name of the index to remove
+ * @param array $parameters Not used?
+ * @param string $error
+ * @return boolean Whether or not the operation was successful
  */
 function smf_db_remove_index($table_name, $index_name, $parameters = array(), $error = 'fatal')
 {
@@ -419,9 +423,10 @@ 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
+ * @param string $type_name The data type (int, varchar, smallint, etc.)
+ * @param int $type_size The size (8, 255, etc.)
+ * @param boolean $reverse If true, returns specific types for a generic type
+ * @return array An array containing the appropriate type and size for this DB type
  */
 function smf_db_calculate_type($type_name, $type_size = null, $reverse = false)
 {
@@ -461,8 +466,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 string $table_name The name of the table
+ * @param array $parameters Not used?
+ * @return An array of table structure - the name, the column info from {@link smf_db_list_columns()} and the index info from {@link smf_db_list_indexes()}
  */
 function smf_db_table_structure($table_name, $parameters = array())
 {
@@ -481,10 +487,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()
- * @return mixed
+ * @param string $table_name The name of the table to get column info for
+ * @param bool $detail Whether or not to return detailed info. If true, returns the column info. If false, just returns the column names.
+ * @param array $parameters Not used?
+ * @return array An array of column names or detailed column info, depending on $detail
  */
 function smf_db_list_columns($table_name, $detail = false, $parameters = array())
 {
@@ -547,10 +553,10 @@ function smf_db_list_columns($table_name, $detail = false, $parameters = array()
 /**
  * Get index information.
  *
- * @param string $table_name
- * @param bool $detail
- * @param array $parameters
- * @return mixed
+ * @param string $table_name The name of the table to get indexes for
+ * @param bool $detail Whether or not to return detailed info.
+ * @param array $parameters Not used?
+ * @return array An array of index names or a detailed array of index info, depending on $detail
  */
 function smf_db_list_indexes($table_name, $detail = false, $parameters = array())
 {
@@ -609,8 +615,9 @@ function smf_db_list_indexes($table_name, $detail = false, $parameters = array()
 /**
  * Alter table on SQLite.
  *
- * @param string $table_name
- * @param array $columns
+ * @param string $table_name The name of the table
+ * @param array $columns An array of arrays of column info and what to do. Can contain 'remove', an array of names of columns to remove, and/or 'add', an array of details of columns to add (see {@link smf_db_list_columns()})
+ * @return boolean Whether or not the operations were successful
  */
 function smf_db_alter_table($table_name, $columns)
 {

Sources/DbSearch-mysql.php

@@ -35,7 +35,8 @@ function db_search_init()
 /**
  * This function will tell you whether this database type supports this search type.
  *
- * @param string $search_type
+ * @param string $search_type The search type.
+ * @return boolean Whether or not the specified search type is supported by this db system
  */
 function smf_db_search_support($search_type)
 {
@@ -47,7 +48,7 @@ function smf_db_search_support($search_type)
 /**
  * Highly specific function, to create the custom word index table.
  *
- * @param $size
+ * @param string $size The size of the desired index.
  */
 function smf_db_create_word_search($size)
 {

Sources/DbSearch-postgresql.php

@@ -35,7 +35,8 @@ function db_search_init()
 /**
  * This function will tell you whether this database type supports this search type.
  *
- * @param string $search_type
+ * @param string $search_type The search type
+ * @return boolean Whether or not the specified search type is supported by this DB system.
  */
 function smf_db_search_support($search_type)
 {
@@ -47,10 +48,11 @@ function smf_db_search_support($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
+ * @param string $identifier A query identifier
+ * @param string $db_string The query text
+ * @param array $db_values An array of values to pass to $smcFunc['db_query']
+ * @param resource $connection The current DB connection resource
+ * @return resource The query result resource from $smcFunc['db_query']
  */
 function smf_db_search_query($identifier, $db_string, $db_values = array(), $connection = null)
 {
@@ -106,7 +108,7 @@ function smf_db_search_query($identifier, $db_string, $db_values = array(), $con
 /**
  * Highly specific function, to create the custom word index table.
  *
- * @param $size
+ * @param string $size The column size type (int, mediumint (8), etc.). Not used here.
  */
 function smf_db_create_word_search($size)
 {

Sources/DbSearch-sqlite.php

@@ -35,7 +35,8 @@ function db_search_init()
 /**
  * This function will tell you whether this database type supports this search type.
  *
- * @param string $search_type
+ * @param string $search_type The search type.
+ * @return boolean Whether or not the specified search type is supported by this DB system.
  */
 function smf_db_search_support($search_type)
 {
@@ -47,10 +48,11 @@ function smf_db_search_support($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
+ * @param string $identifier A query identifier
+ * @param string $db_string The query text
+ * @param array $db_values An array of values to pass to $smcFunc['db_query']
+ * @param resource $connection The current DB connection resource
+ * @return resource The query result resource from $smcFunc['db_query']
  */
 function smf_db_search_query($identifier, $db_string, $db_values = array(), $connection = null)
 {
@@ -86,7 +88,7 @@ function smf_db_search_query($identifier, $db_string, $db_values = array(), $con
 /**
  * Highly specific function, to create the custom word index table.
  *
- * @param $size
+ * @param string $size The column size type (int, mediumint (8), etc.). Not used here.
  */
 function smf_db_create_word_search($size)
 {

Sources/DbSearch-sqlite3.php

@@ -35,7 +35,8 @@ function db_search_init()
 /**
  * This function will tell you whether this database type supports this search type.
  *
- * @param string $search_type
+ * @param string $search_type The search type.
+ * @return boolean Whether or not the specified search type is supported by this DB system.
  */
 function smf_db_search_support($search_type)
 {
@@ -47,10 +48,11 @@ function smf_db_search_support($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
+ * @param string $identifier A query identifier
+ * @param string $db_string The query text
+ * @param array $db_values An array of values to pass to $smcFunc['db_query']
+ * @param resource $connection The current DB connection resource
+ * @return resource The query result resource from $smcFunc['db_query']
  */
 function smf_db_search_query($identifier, $db_string, $db_values = array(), $connection = null)
 {
@@ -86,7 +88,7 @@ function smf_db_search_query($identifier, $db_string, $db_values = array(), $con
 /**
  * Highly specific function, to create the custom word index table.
  *
- * @param $size
+ * @param string $size The column size type (int, mediumint (8), etc.). Not used here.
  */
 function smf_db_create_word_search($size)
 {

Sources/Display.php

@@ -1205,7 +1205,8 @@ function Display()
  * 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 Whether or not to reset the db seek pointer
+ * @return array A large array of contextual data for the posts
  */
 function prepareDisplayContext($reset = false)
 {
@@ -1550,8 +1551,8 @@ function Download()
  * 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
+ * @param int $id_msg ID of the post to load attachments for
+ * @return array An array of attachemnt info
  */
 function loadAttachmentContext($id_msg)
 {
@@ -1719,9 +1720,9 @@ function loadAttachmentContext($id_msg)
 
 /**
  * A sort function for putting unapproved attachments first.
- * @param $a
- * @param $b
- * @return int, -1, 0, 1
+ * @param $a An array of info about one attachment
+ * @param $b An array of info about a second attachment
+ * @return int -1 if $a is approved but $b isn't, 0 if both are approved/unapproved, 1 if $b is approved but a isn't
  */
 function approved_attach_sort($a, $b)
 {
@@ -1854,6 +1855,11 @@ function QuickInTopicModeration()
 	redirectexit(!empty($topicGone) ? 'board=' . $board : 'topic=' . $topic . '.' . $_REQUEST['start']);
 }
 
+/**
+ * Prepares an array of "likes" info for the topic specified by $topic
+ * @uses $topic and $context['user']['id']
+ * @return Array an array of IDs of messages in the specified topic that the current user likes
+ */
 function prepareLikesContext()
 {
 	global $context, $smcFunc, $topic;

Sources/Drafts.php

@@ -25,8 +25,8 @@ loadLanguage('Drafts');
  * 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
+ * @param string $post_errors Any errors encountered trying to save this draft
+ * @return boolean Always returns true
  */
 function SaveDraft(&$post_errors)
 {
@@ -170,13 +170,9 @@ function SaveDraft(&$post_errors)
  * The core draft feature must be enabled, as well as the pm draft option
  * Determines if this is a new or and update to an existing pm draft
  *
- * @global type $context
- * @global type $user_info
- * @global type $smcFunc
- * @global type $modSettings
- * @param string $post_errors
- * @param type $recipientList
- * @return boolean
+ * @param string $post_errors A string of info about errors encountered trying to save this draft
+ * @param array $recipientList An array of data about who this PM is being sent to
+ * @return boolean false if you can't save the draft, true if we're doing this via XML more than 5 seconds after the last save, nothing otherwise
  */
 function SavePMDraft(&$post_errors, $recipientList)
 {
@@ -302,15 +298,14 @@ function SavePMDraft(&$post_errors, $recipientList)
 
 /**
  * Reads a draft in from the user_drafts table
- * Only loads the draft of a given type 0 for post, 1 for pm draft
- * validates that the draft is the users draft
+ * Validates that the draft is the user''s draft
  * Optionally loads the draft in to context or superglobal for loading in to the form
  *
- * @param type $id_draft - draft to load
- * @param type $type - type of draft
- * @param type $check - validate the user
- * @param type $load - load it for use in a form
- * @return boolean
+ * @param int $id_draft ID of the draft to load
+ * @param int $type Type of draft - 0 for post or 1 for PM
+ * @param boolean $check Validate that this draft belongs to the current user
+ * @param boolean $load Whether or not to load the data into variables for use on a form
+ * @return boolean|array False if the data couldn't be loaded, true if it's a PM draft or an array of info about the draft if it's a post draft
  */
 function ReadDraft($id_draft, $type = 0, $check = true, $load = false)
 {
@@ -392,9 +387,9 @@ function ReadDraft($id_draft, $type = 0, $check = true, $load = false)
  * Validates the drafts are from the user
  * is supplied an array of drafts will attempt to remove all of them
  *
- * @param type $id_draft
- * @param type $check
- * @return boolean
+ * @param int $id_draft The ID of the draft to delete
+ * @param boolean $check Whether or not to check that the draft belongs to the current user
+ * @return boolean False if it couldn't be deleted (doesn't return anything otherwise)
  */
 function DeleteDraft($id_draft, $check = true)
 {
@@ -423,12 +418,12 @@ function DeleteDraft($id_draft, $check = true)
  * Loads in a group of drafts for the user of a given type (0/posts, 1/pm's)
  * loads a specific draft for forum use if selected.
  * Used in the posting screens to allow draft selection
- * WIll load a draft if selected is supplied via post
+ * Will load a draft if selected is supplied via post
  *
- * @param type $member_id
- * @param type $topic
- * @param type $draft_type
- * @return boolean
+ * @param int $member_id ID of the member to show drafts for
+ * @param boolean|integer If $type is 1, this can be set to only load drafts for posts in the specific topic
+ * @param int $draft_type The type of drafts to show - 0 for post drafts, 1 for PM drafts
+ * @return boolean False if the drafts couldn't be loaded, nothing otherwise
  */
 function ShowDrafts($member_id, $topic = false, $draft_type = 0)
 {

Sources/Errors.php

@@ -24,11 +24,11 @@ if (!defined('SMF'))
  * 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
+ * @param string $error_message The message to log
+ * @param string $error_type The type of error
+ * @param string $file The name of the file where this error occurred
+ * @param int $line The line where the error occurred
+ * @return string The message that was logged
  */
 function log_error($error_message, $error_type = 'general', $file = null, $line = null)
 {
@@ -116,8 +116,8 @@ function log_error($error_message, $error_type = 'general', $file = null, $line
 /**
  * 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'
+ * @param string $error The error message
+ * @param string $log = 'general' What type of error to log this as (false to not log it))
  */
 function fatal_error($error, $log = 'general')
 {
@@ -140,9 +140,9 @@ function fatal_error($error, $log = 'general')
  *  - 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
+ * @param string $error The error message
+ * @param string $log The type of error, or false to not log it
+ * @param array $sprintf An array of data to be sprintf()'d into the specified message
  */
 function fatal_lang_error($error, $log = 'general', $sprintf = array())
 {
@@ -183,10 +183,10 @@ function fatal_lang_error($error, $log = 'general', $sprintf = array())
 /**
  * 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
+ * @param int $error_level A pre-defined error-handling constant (see {@link http://www.php.net/errorfunc.constants})
+ * @param string $error_string The error message
+ * @param string $file The file where the error occurred
+ * @param int $line The line where the error occurred
  */
 function error_handler($error_level, $error_string, $file, $line)
 {
@@ -258,11 +258,11 @@ function error_handler($error_level, $error_string, $file, $line)
 }
 
 /**
- * It is called by fatal_error() and fatal_lang_error().
+ * It is called by {@link fatal_error()} and {@link fatal_lang_error()}.
  * @uses Errors template, fatal_error sub template, or Wireless template, error sub template.
  *
- * @param string $error_message
- * @param type $error_code
+ * @param string $error_message The error message
+ * @param string $error_code An error code
  */
 function setup_fatal_error_context($error_message, $error_code)
 {