Ticket #2477: inline-docs-pluggable-funcs.diff

wp-includes/pluggable-functions.php

@@ -4 +4 @@
          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 +36 @@
 
 
 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 +65 @@
 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 +117 @@
 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 +179 @@
 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 +199 @@
 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 +238 @@
 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 +252 @@
 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 +268 @@
 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 +283 @@
 // 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 +300 @@
 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 +342 @@
 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 +354 @@
 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 +432 @@
 }
 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 +476 @@
 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);