Index: wp-includes/pluggable-functions.php
===================================================================
--- wp-includes/pluggable-functions.php	(revision 3544)
+++ wp-includes/pluggable-functions.php	(working copy)
@@ -4,6 +4,13 @@
 	 plugins are loaded. */
 
 if ( !function_exists('set_current_user') ) :
+/**
+ * Populates global user information for any user
+ * Set $id to null and specify a name if you do not know a user's ID
+ * @param int $id ID of the user you would like to include
+ * @param string $name (optional) Name of the user to populate data with
+ * @return object WP_User instance
+ */
 function set_current_user($id, $name = '') {
 	global $user_login, $userdata, $user_level, $user_ID, $user_email, $user_url, $user_pass_md5, $user_identity, $current_user;
 
@@ -29,6 +36,9 @@
 
 
 if ( !function_exists('get_currentuserinfo') ) :
+/**
+ * Populate global variables with information about the currently logged in user
+ */
 function get_currentuserinfo() {
 	global $user_login, $userdata, $user_level, $user_ID, $user_email, $user_url, $user_pass_md5, $user_identity, $current_user;
 
@@ -55,6 +65,11 @@
 endif;
 
 if ( !function_exists('get_userdata') ) :
+/**
+ * Get an object containing data about a user
+ * @param int $user_id
+ * @return object user data
+ */
 function get_userdata( $user_id ) {
 	global $wpdb;
 	$user_id = (int) $user_id;
@@ -102,12 +117,20 @@
 endif;
 
 if ( !function_exists('update_user_cache') ) :
+/**
+ * Updates a users cache when overridden by a plugin, core function does nothing
+ */
 function update_user_cache() {
 	return true;
 }
 endif;
 
 if ( !function_exists('get_userdatabylogin') ) :
+/**
+ * Grabs some info about a user based on their login name
+ * @param string $user_login
+ * @return object user info
+ */
 function get_userdatabylogin($user_login) {
 	global $wpdb;
 	$user_login = sanitize_user( $user_login );
@@ -156,6 +179,14 @@
 endif;
 
 if ( !function_exists('wp_mail') ) :
+/**
+ * Function to send mail, similar to PHP's mail
+ * @param string $to outgoing email address
+ * @param string $subject subjecct of the mail
+ * @param string $message body of the mail
+ * @param string $headers (optional) Additional headers
+ * @return bool
+ */
 function wp_mail($to, $subject, $message, $headers = '') {
 	if( $headers == '' ) {
 		$headers = "MIME-Version: 1.0\n" .
@@ -168,6 +199,13 @@
 endif;
 
 if ( !function_exists('wp_login') ) :
+/**
+ * Checks a users login information and logs them in if it checks out
+ * @param string $username
+ * @param string $password
+ * @param bool $already_md5 (optional, default false) if the password has already been md5 hashed
+ * @return bool
+ */
 function wp_login($username, $password, $already_md5 = false) {
 	global $wpdb, $error;
 
@@ -200,6 +238,10 @@
 endif;
 
 if ( !function_exists('is_user_logged_in') ) :
+/**
+ * Function to check if the current visitor is a logged in user
+ * @return bool
+ */
 function is_user_logged_in() {
 	global $current_user;
 
@@ -210,8 +252,10 @@
 endif;
 
 if ( !function_exists('auth_redirect') ) :
+/**
+ * Checks if a user is logged in, if not it redirects them to the login page
+ */
 function auth_redirect() {
-	// Checks if a user is logged in, if not redirects them to the login page
 	if ( (!empty($_COOKIE[USER_COOKIE]) && 
 				!wp_login($_COOKIE[USER_COOKIE], $_COOKIE[PASS_COOKIE], true)) ||
 			 (empty($_COOKIE[USER_COOKIE])) ) {
@@ -224,6 +268,9 @@
 endif;
 
 if ( !function_exists('check_admin_referer') ) :
+/**
+ * Makes sure that a user was referred from another admin page, to avoid security exploits
+ */
 function check_admin_referer() {
 	$adminurl = strtolower(get_settings('siteurl')).'/wp-admin';
 	$referer = strtolower($_SERVER['HTTP_REFERER']);
@@ -236,6 +283,10 @@
 // Cookie safe redirect.  Works around IIS Set-Cookie bug.
 // http://support.microsoft.com/kb/q176113/
 if ( !function_exists('wp_redirect') ) :
+/**
+ * Redirects to another page, with a workaround for the ISS Set-Cookie bug
+ * @param string $location
+ */
 function wp_redirect($location) {
 	global $is_IIS;
 
@@ -249,6 +300,15 @@
 endif;
 
 if ( !function_exists('wp_setcookie') ) :
+/**
+ * Sets a cookie for a user who just logged in
+ * @param string $username
+ * @param string $password
+ * @param bool $already_md5 if the password has already been md5 hashed
+ * @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 remember that the user is logged in
+ */
 function wp_setcookie($username, $password, $already_md5 = false, $home = '', $siteurl = '', $remember = false) {
 	if ( !$already_md5 )
 		$password = md5( md5($password) ); // Double hash the password in the cookie.
@@ -282,6 +342,9 @@
 endif;
 
 if ( !function_exists('wp_clearcookie') ) :
+/**
+ * Unsets a user's login cookies, effectively logging them out
+ */
 function wp_clearcookie() {
 	setcookie(USER_COOKIE, ' ', time() - 31536000, COOKIEPATH, COOKIE_DOMAIN);
 	setcookie(PASS_COOKIE, ' ', time() - 31536000, COOKIEPATH, COOKIE_DOMAIN);
@@ -291,6 +354,12 @@
 endif;
 
 if ( ! function_exists('wp_notify_postauthor') ) :
+/**
+ * Notify an author of a comment/trackback/pingback to one of their posts
+ * @param int $comment_id
+ * @param string $comment_type
+ * @return bool success
+ */
 function wp_notify_postauthor($comment_id, $comment_type='') {
 	global $wpdb;
     
@@ -363,12 +432,12 @@
 }
 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') ) :
+/**
+ * Notifies the moderator of the blog about a new comment that is awaiting approval
+ * @param int $comment_id
+ * @return true
  */
-if ( !function_exists('wp_notify_moderator') ) :
 function wp_notify_moderator($comment_id) {
 	global $wpdb;
 
@@ -407,6 +476,11 @@
 endif;
 
 if ( !function_exists('wp_new_user_notification') ) :
+/**
+ * Notify the blog admin of a new user, normally via email
+ * @param int $user_id
+ * @param string $plaintext_pass (optional)
+ */
 function wp_new_user_notification($user_id, $plaintext_pass = '') {
 	$user = new WP_User($user_id);