Ticket #14953: ALT switch_to_blog and restore_current_blog inline docs.diff

Index: /Users/simon/Projects/WordPress-Bleeding/site/wp-includes/ms-blogs.php
===================================================================
--- /Users/simon/Projects/WordPress-Bleeding/site/wp-includes/ms-blogs.php      (revision 15675)
+++ /Users/simon/Projects/WordPress-Bleeding/site/wp-includes/ms-blogs.php      (working copy)
@@ -370,6 +370,29 @@
        wp_cache_set( $id."-".$key."-blog_option", $value, 'site-options');
 }
 
+/**
+ * Switches the blog (also referred to as a site) currently in use 
+ * by WordPress.
+ * 
+ * Beware: If you are running a WP Object cache you may find some
+ * options retain their values from the old blog, you could hook 
+ * the switch_blog action and delete or switch caches to 
+ * address this.
+ * 
+ * @since 3.0.0
+ * @uses get_blog_details() If validation is required
+ * @uses $wpdb To change the DB tables being queried
+ * @uses do_action()
+ * @uses did_action()
+ * @uses wp_get_current_user()
+ * @uses wp_cache_init()
+ * @uses wp_cache_add_global_groups()
+ * @uses wp_cache_add_non_persistent_groups()
+ *
+ * @param int $blog_id The ID of the blog/site to switch to
+ * @param bool $validate Whether to check the existence of the blog before switching
+ * @return bool True if the switch was successful, otherwise false
+ **/
 function switch_to_blog( $new_blog, $validate = false ) {
        global $wpdb, $table_prefix, $blog_id, $switched, $switched_stack, $wp_roles, $wp_object_cache;
 
@@ -432,6 +455,21 @@
        return true;
 }
 
+/**
+ * Restores the previous blog (also referred to as a site) that was in use 
+ * by WordPress.
+ * 
+ * @since 3.0.0
+ * @uses $wpdb To change the DB tables being queried
+ * @uses do_action()
+ * @uses did_action()
+ * @uses wp_get_current_user()
+ * @uses wp_cache_init()
+ * @uses wp_cache_add_global_groups()
+ * @uses wp_cache_add_non_persistent_groups()
+ *
+ * @return bool True if the restoration has been successful, otherwise false
+ **/
 function restore_current_blog() {
        global $table_prefix, $wpdb, $blog_id, $switched, $switched_stack, $wp_roles, $wp_object_cache;