! Some minor doc changes since I was there

Sources/Subs-Auth.php

@@ -18,10 +18,11 @@ if (!defined('SMF'))
 
 /**
  * sets the SMF-style login cookie and session based on the id_member and password passed.
- * password should be already encrypted with the cookie salt.
- * logs the user out if id_member is zero.
- * sets the cookie and session to last the number of seconds specified by cookie_length.
- * when logging out, if the globalCookies setting is enabled, attempts to clear the subdomain's cookie too.
+ * - password should be already encrypted with the cookie salt.
+ * - logs the user out if id_member is zero.
+ * - sets the cookie and session to last the number of seconds specified by cookie_length.
+ * - when logging out, if the globalCookies setting is enabled, attempts to clear the subdomain's cookie too.
+ *
  * @param int $cookie_length,
  * @param int $id The id of the member
  * @param string $password = ''
@@ -96,6 +97,7 @@ function setLoginCookie($cookie_length, $id, $password = '')
 
 		// Recreate and restore the new session.
 		loadSession();
+		// @todo should we use session_regenerate_id(true); now that we are 5.1+
 		session_regenerate_id();
 		$_SESSION = $oldSessionData;
 
@@ -114,8 +116,9 @@ function setLoginCookie($cookie_length, $id, $password = '')
 
 /**
  * Get the domain and path for the cookie
- * normally, local and global should be the localCookies and globalCookies settings, respectively.
- * uses boardurl to determine these two things.
+ * - normally, local and global should be the localCookies and globalCookies settings, respectively.
+ * - uses boardurl to determine these two things.
+ *
  * @param bool $local,
  * @param bool $global
  * @return array an array to set the cookie on with domain and path in it, in that order
@@ -151,8 +154,8 @@ function url_parts($local, $global)
 
 /**
  * Throws guests out to the login screen when guest access is off.
- * sets $_SESSION['login_url'] to $_SERVER['REQUEST_URL'].
- * uses the 'kick_guest' sub template found in Login.template.php.
+ * - sets $_SESSION['login_url'] to $_SERVER['REQUEST_URL'].
+ * - uses the 'kick_guest' sub template found in Login.template.php.
  */
 function KickGuest()
 {
@@ -170,8 +173,9 @@ function KickGuest()
 }
 
 /**
- * Display a message about being in maintenance mode.
- * display a login screen with sub template 'maintenance'.
+ * Display a message about the forum being in maintenance mode.
+ * - display a login screen with sub template 'maintenance'.
+ * - sends a 503 header, so search engines don't bother indexing while we're in maintenance mode.
  */
 function InMaintenance()
 {
@@ -191,10 +195,11 @@ function InMaintenance()
 }
 
 /**
- * Double check the verity of the admin by asking for his or her password.
- * loads Login.template.php and uses the admin_login sub template.
- * sends data to template so the admin is sent on to the page they
- *  wanted if their password is correct, otherwise they can try again.
+ * Question the verity of the admin by asking for his or her password.
+ * - loads Login.template.php and uses the admin_login sub template.
+ * - sends data to template so the admin is sent on to the page they
+ *   wanted if their password is correct, otherwise they can try again.
+ *
  * @param string $type = 'admin'
  */
 function adminLogin($type = 'admin')
@@ -253,6 +258,7 @@ function adminLogin($type = 'admin')
 /**
  * used by the adminLogin() function.
  * if 'value' is an array, the function is called recursively.
+ *
  * @param string $key
  * @param string $value
  * @return string 'hidden' HTML form fields, containing key-value-pairs
@@ -274,6 +280,13 @@ function adminLogin_outputPostVars($k, $v)
 	}
 }
 
+/**
+ * Properly urlencodes a string to be used in a query
+ *
+ * @global type $scripturl
+ * @param type $get
+ * @return our query string
+ */
 function construct_query_string($get)
 {
 	global $scripturl;
@@ -307,13 +320,14 @@ function construct_query_string($get)
 	return $query_string;
 }
 
-// Find members by email address, username, or real name.
 /**
- * searches for members whose username, display name, or e-mail address match the given pattern of array names.
- * searches only buddies if buddies_only is set.
- * @param array $names, 
+ * Finds members by email address, username, or real name.
+ * - searches for members whose username, display name, or e-mail address match the given pattern of array names.
+ * - searches only buddies if buddies_only is set.
+ *
+ * @param array $names,
  * @param bool $use_wildcards = false, accepts wildcards ? and * in the patern if true
- * @param bool $buddies_only = false, 
+ * @param bool $buddies_only = false,
  * @param int $max = 500 retrieves a maximum of max members, if passed
  * @return array containing information about the matching members
  */
@@ -395,9 +409,9 @@ function findMembers($names, $use_wildcards = false, $buddies_only = false, $max
 
 /**
  * called by index.php?action=findmember.
- * is used as a popup for searching members.
- * uses sub template find_members of the Help template.
- * also used to add members for PM's sent using wap2/imode protocol.
+ * - is used as a popup for searching members.
+ * - uses sub template find_members of the Help template.
+ * - also used to add members for PM's sent using wap2/imode protocol.
  */
 function JSMembers()
 {
@@ -467,7 +481,7 @@ function JSMembers()
 
 /**
  * outputs each member name on its own line.
- * used by javascript to find members matching the request.
+ * - used by javascript to find members matching the request.
  */
 function RequestMembers()
 {
@@ -529,11 +543,12 @@ function RequestMembers()
 
 /**
  * Generates a random password for a user and emails it to them.
- * called by Profile.php when changing someone's username.
- * checks the validity of the new username.
- * generates and sets a new password for the given user.
- * mails the new password to the email address of the user.
- * if username is not set, only a new password is generated and sent.
+ * - called by Profile.php when changing someone's username.
+ * - checks the validity of the new username.
+ * - generates and sets a new password for the given user.
+ * - mails the new password to the email address of the user.
+ * - if username is not set, only a new password is generated and sent.
+ *
  * @param int $memID
  * @param string $username = null
  */
@@ -593,6 +608,7 @@ function resetPassword($memID, $username = null)
 
 /**
  * Checks a username obeys a load of rules
+ *
  * @param int $memID,
  * @param string $username
  * @return string Returns null if fine
@@ -621,10 +637,11 @@ function validateUsername($memID, $username)
 
 /**
  * Checks whether a password meets the current forum rules
- * called when registering/choosing a password.
- * checks the password obeys the current forum settings for password strength.
- * if password checking is enabled, will check that none of the words in restrict_in appear in the password.
- * returns an error identifier if the password is invalid, or null.
+ * - called when registering/choosing a password.
+ * - checks the password obeys the current forum settings for password strength.
+ * - if password checking is enabled, will check that none of the words in restrict_in appear in the password.
+ * - returns an error identifier if the password is invalid, or null.
+ *
  * @param string $password
  * @param string $username
  * @param array $restrict_in = array()
@@ -648,8 +665,6 @@ function validatePassword($password, $username, $restrict_in = array())
 	elseif ($smcFunc['strpos']($password, $username) !== false)
 		return 'restricted_words';
 
-	// @todo If pspell is available, use it on the word, and return restricted_words if it doesn't give "bad spelling"?
-
 	// If just medium, we're done.
 	if ($modSettings['password_strength'] == 1)
 		return null;
@@ -662,8 +677,9 @@ function validatePassword($password, $username, $restrict_in = array())
 }
 
 /**
- * Quickly find out what this user can and cannot do.
- * stores some useful information on the current users moderation powers in the session.
+ * Quickly find out what moderation authority this user has
+ * - builds the moderator, group and board level querys for the user
+ * - stores the information on the current users moderation powers in $user_info['mod_cache'] and $_SESSION['mc']
  */
 function rebuildModCache()
 {
@@ -745,6 +761,7 @@ function rebuildModCache()
 
 /**
  * The same thing as setcookie but gives support for HTTP-Only cookies in PHP < 5.2
+ *
  * @param string $name
  * @param string $value = ''
  * @param int $expire = 0
@@ -762,7 +779,7 @@ function smf_setcookie($name, $value = '', $expire = 0, $path = '', $domain = ''
 		$httponly = !empty($modSettings['httponlyCookies']);
 	if ($secure === null)
 		$secure = !empty($modSettings['secureCookies']);
-		
+
 	// This function is pointless if we have PHP >= 5.2.
 	if (version_compare(PHP_VERSION, '5.2', '>='))
 		return setcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

Sources/Subs-Compat.php

@@ -19,6 +19,15 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
+/**
+ * Available since: (PHP 5)
+ * Find the position of the first occurrence of a case-insensitive substring in a string
+ *
+ * @param type $haystack
+ * @param type $needle
+ * @param int $offset
+ * @return positon of needle in haystack or false
+ */
 if (!function_exists('stripos'))
 {
 	function stripos($haystack, $needle, $offset = 0)
@@ -27,6 +36,13 @@ if (!function_exists('stripos'))
 	}
 }
 
+/**
+ * Available since: (PHP 4 >= 4.2.0, PHP 5)
+ * Calculates the md5 hash of a given file
+ *
+ * @param type $filename
+ * @return type
+ */
 if (!function_exists('md5_file'))
 {
 	function md5_file($filename)
@@ -36,13 +52,15 @@ if (!function_exists('md5_file'))
 	}
 }
 
+/**
+ * Available since: (PHP 5)
+ * Convert a string to an array
+ *
+ * @param $str the string to split
+ * @param $str_length
+ */
 if (!function_exists('str_split'))
 {
-	/**
-	 * Split a string into an array.
-	 * @param $str the string to split
-	 * @param $str_length
-	 */
 	function str_split($str, $str_length = 1)
 	{
 		if ($str_length < 1)
@@ -65,6 +83,15 @@ if (!function_exists('str_split'))
 	}
 }
 
+/**
+ * Available since: (PHP 4 >= 4.3.0, PHP 5)
+ * 5.1.0 Added the offset and maxlen parameters.
+ * 5.0.0 Added context support.
+ *
+ * @param type $filename
+ * @param type $include_path
+ * @return string|boolean
+ */
 if (!function_exists('file_get_contents'))
 {
 	function file_get_contents($filename, $include_path = false)
@@ -159,6 +186,9 @@ function sha1_core($x, $len)
 	return sprintf('%08x%08x%08x%08x%08x', $a, $b, $c, $d, $e);
 }
 
+/*
+ * Helper function for the core SHA-1 calculation
+ */
 function sha1_ft($t, $b, $c, $d)
 {
 	if ($t < 20)
@@ -171,11 +201,17 @@ function sha1_ft($t, $b, $c, $d)
 	return $b ^ $c ^ $d;
 }
 
+/*
+ * Helper function for the core SHA-1 calculation
+ */
 function sha1_kt($t)
 {
 	return $t < 20 ? 1518500249 : ($t < 40 ? 1859775393 : ($t < 60 ? -1894007588 : -899497514));
 }
 
+/*
+ * Helper function for the core SHA-1 calculation
+ */
 function sha1_rol($num, $cnt)
 {
 	// Unfortunately, PHP uses unsigned 32-bit longs only.  So we have to kludge it a bit.
@@ -188,6 +224,7 @@ function sha1_rol($num, $cnt)
 }
 
 /**
+ * Available since: (PHP 4 >= 4.3.0, PHP 5)
  * Still on old PHP - bad boy! (the built in one would be faster.)
  */
 if (!function_exists('sha1'))
@@ -198,6 +235,14 @@ if (!function_exists('sha1'))
 	}
 }
 
+/**
+ * Available since: (PHP 5)
+ * Creates an array by using one array for keys and another for its values
+ *
+ * @param type $keys
+ * @param type $values
+ * @return new array or boolean on failure
+ */
 if (!function_exists('array_combine'))
 {
 	function array_combine($keys, $values)
@@ -223,6 +268,10 @@ if (!function_exists('array_combine'))
 	}
 }
 
+/**
+ * Available since: (PHP 5 >= 5.1.0)
+ * Computes the difference of arrays using keys for comparison
+ */
 if (!function_exists('array_diff_key'))
 {
 	function array_diff_key()
@@ -243,6 +292,10 @@ if (!function_exists('array_diff_key'))
 	}
 }
 
+/**
+ * Available since: (PHP 4 >= 4.3.0, PHP 5)
+ * Escapes special characters in a string for use in an SQL statement
+ */
 if (!function_exists('mysql_real_escape_string'))
 {
 	function mysql_real_escape_string($string, $connection = null)
@@ -251,14 +304,14 @@ if (!function_exists('mysql_real_escape_string'))
 	}
 }
 
+/**
+ * Compatibility function.
+ * crc32 doesn't work as expected on 64-bit functions - make our own.
+ * http://www.php.net/crc32#79567
+ * @param $number
+ */
 if (!function_exists('smf_crc32'))
 {
-	/**
-	 * Compatibility function.
-	 * crc32 doesn't work as expected on 64-bit functions - make our own.
-	 * http://www.php.net/crc32#79567
-	 * @param $number
-	 */
 	function smf_crc32($number)
 	{
 		$crc = crc32($number);
@@ -274,7 +327,11 @@ if (!function_exists('smf_crc32'))
 	}
 }
 
-// PHP < 4.3.2 doesn't have this function
+/**
+ * Available since: (PHP 4 >= 4.3.2, PHP 5)
+ * Update the current session id with a newly generated one
+ * 5.1.0 Added the delete_old_session parameter.
+ */
 if (!function_exists('session_regenerate_id'))
 {
 	function session_regenerate_id()
@@ -288,8 +345,13 @@ if (!function_exists('session_regenerate_id'))
 	}
 }
 
-// @author [Unknown] [email protected]
-// @link http://www.simplemachines.org/community/index.php?msg=2420295
+/**
+ * Available since: (PHP 5)
+ * Case-insensitive version of str_replace().
+ *
+ * @author [Unknown] [email protected]
+ * @link http://www.simplemachines.org/community/index.php?msg=2420295
+ */
 if (!function_exists('str_ireplace'))
 {
 	function str_ireplace($search, $replace, $subject, $count = -1)
@@ -312,7 +374,7 @@ if (!function_exists('str_ireplace'))
 
 /**
  * Load a < PHP 5 class file
- * 
+ *
  * @param string $filename
  */
 function loadOldClassFile($filename)
@@ -348,7 +410,8 @@ function loadOldClassFile($filename)
 }
 
 /**
- * PHP 4 didn't have bcpowmod.
+ * Available since: (PHP 5)
+ * Raise an arbitrary precision number to another, reduced by a specified modulus
  */
 if (!function_exists('bcpowmod') && function_exists('bcpow'))
 {
@@ -360,6 +423,8 @@ if (!function_exists('bcpowmod') && function_exists('bcpow'))
 
 /**
  * Random seed generator
+ * As of PHP 4.2.0, there is no need to seed the random number generator with srand() or mt_srand()
+ * as this is now done automatically.
  */
 if (version_compare(PHP_VERSION, '4.2.0', '<'))
 {
@@ -367,4 +432,26 @@ if (version_compare(PHP_VERSION, '4.2.0', '<'))
 	mt_srand($seed);
 }
 
+/**
+ * Available since: (PHP 5)
+ * If the optional raw_output is set to TRUE, then the sha1 digest is instead returned in raw binary format with a length of 20,
+ * otherwise the returned value is a 40-character hexadecimal number.
+ */
+function sha1_raw($text)
+{
+	if (version_compare(PHP_VERSION, '5.0.0', '>='))
+		return sha1($text, true);
+
+	$hex = sha1($text);
+	$raw = '';
+	for ($i = 0; $i < 40; $i += 2)
+	{
+		$hexcode = substr($hex, $i, 2);
+		$charcode = (int) base_convert($hexcode, 16, 10);
+		$raw .= chr($charcode);
+	}
+
+	return $raw;
+}
+
 ?>