Index: pluggable.php
===================================================================
--- pluggable.php	(revision 6473)
+++ pluggable.php	(working copy)
@@ -1,15 +1,50 @@
 <?php
+/**
+ * These functions can be replaced via plugins.  They are loaded after
+ * plugins are loaded.
+ *
+ * @package WordPress
+ */
 
-	/* These functions can be replaced via plugins.  They are loaded after
-	 plugins are loaded. */
-
 if ( !function_exists('set_current_user') ) :
+/**
+ * set_current_user() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description
+ *		Documentation must describe why set_current_user() would be override
+ *		instead of wp_set_current_user(). There is a reason and must look for it.
+ *		If exists on the codex, then link to that instead.
+ * }}
+ *
+ * @since 2.0.1
+ * @see wp_set_current_user() An alias of wp_set_current_user()
+ *
+ * @param int $id
+ * @param string $name
+ * @return object returns wp_set_current_user()
+ */
 function set_current_user($id, $name = '') {
 	return wp_set_current_user($id, $name);
 }
 endif;
 
 if ( !function_exists('wp_set_current_user') ) :
+/**
+ * wp_set_current_user() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description
+ *		Documentation must describe why wp_set_current_user() would be override
+ *		instead of set_current_user(). There is a reason and must look for it.
+ *		If exists on the codex, then link to that instead.
+ * }}
+ *
+ * @since 
+ * @global object $current_user The current user object which holds the user data.
+ *
+ * @param int $id
+ * @param string $name
+ * @return object
+ */
 function wp_set_current_user($id, $name = '') {
 	global $current_user;
 
@@ -27,6 +62,13 @@
 endif;
 
 if ( !function_exists('wp_get_current_user') ) :
+/**
+ * wp_get_current_user() - 
+ *
+ * @since 
+ *
+ * @return unknown
+ */
 function wp_get_current_user() {
 	global $current_user;
 
@@ -37,6 +79,13 @@
 endif;
 
 if ( !function_exists('get_currentuserinfo') ) :
+/**
+ * get_currentuserinfo() - 
+ *
+ * @since 
+ *
+ * @return unknown
+ */
 function get_currentuserinfo() {
 	global $current_user;
 
@@ -56,6 +105,14 @@
 endif;
 
 if ( !function_exists('get_userdata') ) :
+/**
+ * get_userdata() - 
+ *
+ * @since 
+ *
+ * @param unknown_type $user_id
+ * @return unknown
+ */
 function get_userdata( $user_id ) {
 	global $wpdb;
 
@@ -82,12 +139,27 @@
 endif;
 
 if ( !function_exists('update_user_cache') ) :
+/**
+ * update_user_cache() - 
+ *
+ * @since 
+ *
+ * @return bool Only returns true
+ */
 function update_user_cache() {
 	return true;
 }
 endif;
 
 if ( !function_exists('get_userdatabylogin') ) :
+/**
+ * get_userdatabylogin() - 
+ *
+ * @since 
+ *
+ * @param unknown_type $user_login
+ * @return unknown
+ */
 function get_userdatabylogin($user_login) {
 	global $wpdb;
 	$user_login = sanitize_user( $user_login );
@@ -118,6 +190,14 @@
 endif;
 
 if ( !function_exists('get_user_by_email') ) :
+/**
+ * get_user_by_email() - 
+ *
+ * @since 
+ *
+ * @param unknown_type $email
+ * @return unknown
+ */
 function get_user_by_email($email) {
 	global $wpdb;
 
@@ -145,6 +225,17 @@
 endif;
 
 if ( !function_exists( 'wp_mail' ) ) :
+/**
+ * wp_mail() - 
+ *
+ * @since 
+ *
+ * @param unknown_type $to
+ * @param unknown_type $subject
+ * @param unknown_type $message
+ * @param unknown_type $headers
+ * @return unknown
+ */
 function wp_mail( $to, $subject, $message, $headers = '' ) {
 	// Compact the input, apply the filters, and extract them back out
 	extract( apply_filters( 'wp_mail', compact( 'to', 'subject', 'message', 'headers' ) ) );
@@ -291,6 +382,16 @@
 endif;
 
 if ( !function_exists('wp_login') ) :
+/**
+ * wp_login() - 
+ *
+ * @since 
+ *
+ * @param unknown_type $username
+ * @param unknown_type $password
+ * @param unknown_type $deprecated
+ * @return unknown
+ */
 function wp_login($username, $password, $deprecated = false) {
 	global $wpdb, $error;
 
@@ -325,6 +426,14 @@
 endif;
 
 if ( !function_exists('wp_validate_auth_cookie') ) :
+/**
+ * wp_validate_auth_cookie() - 
+ *
+ * @since 
+ *
+ * @param unknown_type $cookie
+ * @return unknown
+ */
 function wp_validate_auth_cookie($cookie = '') {
 	if ( empty($cookie) ) {
 		if ( empty($_COOKIE[AUTH_COOKIE]) )
@@ -358,6 +467,14 @@
 endif;
 
 if ( !function_exists('wp_set_auth_cookie') ) :
+/**
+ * wp_set_auth_cookie() - 
+ *
+ * @since 
+ *
+ * @param unknown_type $user_id
+ * @param unknown_type $remember
+ */
 function wp_set_auth_cookie($user_id, $remember = false) {
 	$user = get_userdata($user_id);
 
@@ -380,6 +497,12 @@
 endif;
 
 if ( !function_exists('wp_clear_auth_cookie') ) :
+/**
+ * wp_clear_auth_cookie() - 
+ *
+ * @since 
+ *
+ */
 function wp_clear_auth_cookie() {
 	setcookie(AUTH_COOKIE, ' ', time() - 31536000, COOKIEPATH, COOKIE_DOMAIN);
 	setcookie(AUTH_COOKIE, ' ', time() - 31536000, SITECOOKIEPATH, COOKIE_DOMAIN);
@@ -393,6 +516,13 @@
 endif;
 
 if ( !function_exists('is_user_logged_in') ) :
+/**
+ * is_user_logged_in() - 
+ *
+ * @since 
+ *
+ * @return bool
+ */
 function is_user_logged_in() {
 	$user = wp_get_current_user();
 
@@ -404,6 +534,12 @@
 endif;
 
 if ( !function_exists('auth_redirect') ) :
+/**
+ * auth_redirect() - 
+ *
+ * @since 
+ *
+ */
 function auth_redirect() {
 	// Checks if a user is logged in, if not redirects them to the login page
 	if ( (!empty($_COOKIE[AUTH_COOKIE]) &&
@@ -418,6 +554,11 @@
 endif;
 
 if ( !function_exists('check_admin_referer') ) :
+/**
+ * check_admin_referer() - 
+ *
+ * @param unknown_type $action
+ */
 function check_admin_referer($action = -1) {
 	$adminurl = strtolower(get_option('siteurl')).'/wp-admin';
 	$referer = strtolower(wp_get_referer());
@@ -430,6 +571,13 @@
 }endif;
 
 if ( !function_exists('check_ajax_referer') ) :
+/**
+ * check_ajax_referer() - 
+ *
+ * @since 
+ *
+ * @param unknown_type $action
+ */
 function check_ajax_referer( $action = -1 ) {
 	$nonce = $_REQUEST['_ajax_nonce'] ? $_REQUEST['_ajax_nonce'] : $_REQUEST['_wpnonce'];
 	if ( !wp_verify_nonce( $nonce, $action ) ) {
@@ -462,6 +610,15 @@
 // Cookie safe redirect.  Works around IIS Set-Cookie bug.
 // http://support.microsoft.com/kb/q176113/
 if ( !function_exists('wp_redirect') ) :
+/**
+ * wp_redirect() - 
+ *
+ * @since 
+ *
+ * @param unknown_type $location
+ * @param unknown_type $status
+ * @return unknown
+ */
 function wp_redirect($location, $status = 302) {
 	global $is_IIS;
 
@@ -484,7 +641,10 @@
 
 if ( !function_exists('wp_sanitize_redirect') ) :
 /**
- * sanitizes a URL for use in a redirect
+ * wp_sanitize_redirect() - Sanitizes a URL for use in a redirect
+ *
+ * @since 
+ *
  * @return string redirect-sanitized URL
  **/
 function wp_sanitize_redirect($location) {
@@ -509,7 +669,10 @@
 
 if ( !function_exists('wp_safe_redirect') ) :
 /**
- * performs a safe (local) redirect, using wp_redirect()
+ * wp_safe_redirect() - Performs a safe (local) redirect, using wp_redirect()
+ *
+ * @since 2.3
+ *
  * @return void
  **/
 function wp_safe_redirect($location, $status = 302) {
@@ -534,6 +697,15 @@
 endif;
 
 if ( ! function_exists('wp_notify_postauthor') ) :
+/**
+ * wp_notify_postauthor() - Notify an author of a comment/trackback/pingback to one of their posts
+ *
+ * @since 1.0.1
+ *
+ * @param int $comment_id Comment ID
+ * @param string $comment_type Optional. The comment type either 'comment' (default), 'trackback', or 'pingback'
+ * @return bool False if user email does not exist. True on completion.
+ */
 function wp_notify_postauthor($comment_id, $comment_type='') {
 	$comment = get_comment($comment_id);
 	$post    = get_post($comment->comment_post_ID);
@@ -603,12 +775,16 @@
 }
 endif;
 
-/* wp_notify_moderator
-   notifies the moderator of the blog (usually the admin)
-   about a new comment that waits for approval
-   always returns true
+if ( !function_exists('wp_notify_moderator') ) :
+/**
+ * wp_notify_moderator() - Notifies the moderator of the blog about a new comment that is awaiting approval
+ *
+ * @since 1.0.1
+ * @uses $wpdb
+ *
+ * @param int $comment_id Comment ID
+ * @return bool Always returns true
  */
-if ( !function_exists('wp_notify_moderator') ) :
 function wp_notify_moderator($comment_id) {
 	global $wpdb;
 
@@ -648,6 +824,14 @@
 endif;
 
 if ( !function_exists('wp_new_user_notification') ) :
+/**
+ * wp_new_user_notification() - Notify the blog admin of a new user, normally via email
+ *
+ * @since 2.0
+ *
+ * @param int $user_id User ID
+ * @param string $plaintext_pass Optional. The user's plaintext password
+ */
 function wp_new_user_notification($user_id, $plaintext_pass = '') {
 	$user = new WP_User($user_id);
 
@@ -673,6 +857,18 @@
 endif;
 
 if ( !function_exists('wp_verify_nonce') ) :
+/**
+ * wp_verify_nonce() - Verify that correct nonce was used with time limit
+ *
+ * The user is given an amount of time to use the token, so therefore, since
+ * the UID and $action remain the same, the independent variable is the time.
+ *
+ * @since 2.0.4
+ *
+ * @param string $nonce
+ * @param string|int $action Should give context to what is taking place and be the same when nonce was created.
+ * @return bool Whether the nonce check passed or failed.
+ */
 function wp_verify_nonce($nonce, $action = -1) {
 	$user = wp_get_current_user();
 	$uid = (int) $user->id;
@@ -687,6 +883,14 @@
 endif;
 
 if ( !function_exists('wp_create_nonce') ) :
+/**
+ * wp_create_nonce() - Creates a random, one use token
+ *
+ * @since 2.0.4
+ *
+ * @param string|int $action Scalar value to add context to the nonce.
+ * @return string The one use form token
+ */
 function wp_create_nonce($action = -1) {
 	$user = wp_get_current_user();
 	$uid = (int) $user->id;
@@ -698,6 +902,39 @@
 endif;
 
 if ( !function_exists('wp_salt') ) :
+/**
+ * wp_salt() - Get salt to add to hashes to help prevent attacks
+ *
+ * You can set the salt by defining two areas. One is in the database and
+ * the other is in your wp-config.php file. The database location is defined
+ * in the option named 'secret', but most likely will not need to be changed.
+ *
+ * The second, located in wp-config.php, is a constant named 'SECRET_KEY', but
+ * is not required. If the constant is not defined then the database constants
+ * will be used, since they are most likely given to be unique. However, given
+ * that the salt will be added to the password and can be seen, the constant
+ * is recommended to be set manually.
+ *
+ * <code>
+ * define('SECRET_KEY', 'mAry1HadA15|\/|b17w55w1t3asSn09w');
+ * </code>
+ *
+ * Attention: Do not use above example!
+ *
+ * Salting passwords helps against tools which has stored hashed values
+ * of common dictionary strings. The added values makes it harder to crack
+ * if given salt string is not weak.
+ *
+ * Salting only helps if the string is not predictable and should be
+ * made up of various characters. Think of the salt as a password for
+ * securing your passwords, but common among all of your passwords.
+ * Therefore the salt should be as long as possible as as difficult as
+ * possible, because you will not have to remember it.
+ *
+ * @since 2.4
+ *
+ * @return unknown
+ */
 function wp_salt() {
 
 	if ( defined('SECRET_KEY') && '' != SECRET_KEY )
@@ -714,6 +951,15 @@
 endif;
 
 if ( !function_exists('wp_hash') ) :
+/**
+ * wp_hash() - Get hash of given string
+ *
+ * @since 2.0.4
+ * @uses wp_salt() Get WordPress salt
+ *
+ * @param string $data Plain text to hash
+ * @return string Hash of $data
+ */
 function wp_hash($data) {
 	$salt = wp_salt();
 
@@ -726,6 +972,20 @@
 endif;
 
 if ( !function_exists('wp_hash_password') ) :
+/**
+ * wp_hash_password() - Create a hash (encrypt) of a plain text password
+ *
+ * For integration with other applications, this function can be
+ * overwritten to instead use the other package password checking
+ * algorithm.
+ *
+ * @since 2.4
+ * @global object $wp_hasher PHPass object
+ * @uses PasswordHash::HashPassword
+ *
+ * @param string $password Plain text user password to hash
+ * @return string The hash string of the password
+ */
 function wp_hash_password($password) {
 	global $wp_hasher;
 
@@ -740,6 +1000,28 @@
 endif;
 
 if ( !function_exists('wp_check_password') ) :
+/**
+ * wp_check_password() - Checks the plaintext password against the encrypted Password
+ *
+ * Maintains compatibility between old version and the new cookie
+ * authentication protocol using PHPass library. The $hash parameter
+ * is the encrypted password and the function compares the plain text
+ * password when encypted similarly against the already encrypted
+ * password to see if they match.
+ *
+ * For integration with other applications, this function can be
+ * overwritten to instead use the other package password checking
+ * algorithm.
+ *
+ * @since 2.4
+ * @global object $wp_hasher PHPass object used for checking the password
+ *	against the $hash + $password
+ * @uses PasswordHash::CheckPassword
+ *
+ * @param string $password
+ * @param string $hash
+ * @return bool False, if the $password does not match the hashed password
+ */
 function wp_check_password($password, $hash) {
 	global $wp_hasher;
 
@@ -760,8 +1042,11 @@
 
 if ( !function_exists('wp_generate_password') ) :
 /**
- * Generates a random password drawn from the defined set of characters
- * @return string the password
+ * wp_generate_password() - Generates a random password drawn from the defined set of characters
+ *
+ * @since 2.4
+ *
+ * @return string The random password
  **/
 function wp_generate_password() {
 	$chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
@@ -774,6 +1059,20 @@
 endif;
 
 if ( !function_exists('wp_set_password') ) :
+/**
+ * wp_set_password() - Updates the user's password with a new encrypted one
+ *
+ * For integration with other applications, this function can be
+ * overwritten to instead use the other package password checking
+ * algorithm.
+ *
+ * @since 2.4
+ * @uses $wpdb WordPress database object for queries
+ * @uses wp_hash_password() Used to encrypt the user's password before passing to the database
+ *
+ * @param string $password The plaintext new user password
+ * @param int $user_id User ID
+ */
 function wp_set_password( $password, $user_id ) {
 	global $wpdb;
 
@@ -784,23 +1083,49 @@
 }
 endif;
 
-// Deprecated. Use wp_set_auth_cookie()
 if ( !function_exists('wp_setcookie') ) :
+/**
+ * wp_setcookie() - Sets a cookie for a user who just logged in
+ *
+ * @since 1.5
+ * @deprecated Use wp_set_auth_cookie()
+ * @see wp_set_auth_cookie()
+ *
+ * @param string  $username The user's username
+ * @param string  $password Optional. The user's password
+ * @param bool $already_md5 Optional. Whether the password has already been through MD5
+ * @param string $home Optional. Will be used instead of COOKIEPATH if set
+ * @param string $siteurl Optional. Will be used instead of SITECOOKIEPATH if set
+ * @param bool $remember Optional. Remember that the user is logged in
+ */
 function wp_setcookie($username, $password = '', $already_md5 = false, $home = '', $siteurl = '', $remember = false) {
 	$user = get_userdatabylogin($username);
 	wp_set_auth_cookie($user->ID, $remember);
 }
 endif;
 
-// Deprecated. Use wp_clear_auth_cookie()
 if ( !function_exists('wp_clearcookie') ) :
+/**
+ * wp_clearcookie() - Clears the authentication cookie, logging the user out
+ *
+ * @since 1.5
+ * @deprecated Use wp_clear_auth_cookie()
+ * @see wp_clear_auth_cookie()
+ */
 function wp_clearcookie() {
 	wp_clear_auth_cookie();
 }
 endif;
 
-// Deprecated.  No alternative.
 if ( !function_exists('wp_get_cookie_login') ):
+/**
+ * wp_get_cookie_login() - {@internal Missing Short Description}}
+ *
+ * @since 2.0.4
+ * @deprecated No alternative
+ *
+ * @return bool Always returns false
+ */
 function wp_get_cookie_login() {
 	return false;
 }