From c63d9afdec36f9ae320440b9b66783a3bad6e19c Mon Sep 17 00:00:00 2001 From: nacin Date: Wed, 29 Sep 2010 23:44:34 +0000 Subject: [PATCH] Some phpdoc for ms-functions.php. props boonebgorges. see #14953. git-svn-id: http://svn.automattic.com/wordpress/trunk@15675 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/ms-functions.php | 165 ++++++++++++++++++++++++++++++++++- 1 file changed, 163 insertions(+), 2 deletions(-) diff --git a/wp-includes/ms-functions.php b/wp-includes/ms-functions.php index 8cb2b0a87b..08153be9e9 100644 --- a/wp-includes/ms-functions.php +++ b/wp-includes/ms-functions.php @@ -7,6 +7,15 @@ * @since 3.0.0 */ +/** + * Gets the network's site and user counts. + * + * @since MU 1.0 + * @uses get_blog_count() + * @uses get_user_count() + * + * @return array Site and user count for the network. + */ function get_sitestats() { global $wpdb; @@ -16,6 +25,15 @@ function get_sitestats() { return $stats; } +/** + * Get the admin for a domain/path combination. + * + * @since MU 1.0 + * + * @param string $sitedomain Optional. Site domain. + * @param string $path Optional. Site path. + * @return array The network admins + */ function get_admin_users_for_domain( $sitedomain = '', $path = '' ) { global $wpdb; @@ -30,7 +48,28 @@ function get_admin_users_for_domain( $sitedomain = '', $path = '' ) { return false; } -function get_active_blog_for_user( $user_id ) { // get an active blog for user - either primary blog or from blogs list +/** + * Get one of a user's active blogs + * + * Returns the user's primary blog, if she has one and + * it is active. If it's inactive, function returns another + * active blog of the user. If none are found, the user + * is added as a Subscriber to the Dashboard Blog and that blog + * is returned. + * + * @since MU 1.0 + * @uses get_blogs_of_user() + * @uses get_dashboard_blog() + * @uses add_user_to_blog() + * @uses update_user_meta() + * @uses wp_cache_delete() + * @uses get_user_meta() + * @uses get_blog_details() + * + * @param int $user_id The unique ID of the user + * @return object The blog object + */ +function get_active_blog_for_user( $user_id ) { global $wpdb; $blogs = get_blogs_of_user( $user_id ); if ( empty( $blogs ) ) { @@ -44,7 +83,6 @@ function get_active_blog_for_user( $user_id ) { // get an active blog for user - $primary_blog = get_user_meta( $user_id, 'primary_blog', true ); $details = get_dashboard_blog(); if ( $primary_blog ) { - $blogs = get_blogs_of_user( $user_id ); if ( isset( $blogs[ $primary_blog ] ) == false ) { add_user_to_blog( $details->blog_id, $user_id, 'subscriber' ); update_user_meta( $user_id, 'primary_blog', $details->blog_id ); @@ -94,6 +132,16 @@ function get_active_blog_for_user( $user_id ) { // get an active blog for user - } } +/** + * Find out whether a user is a member of a given blog. + * + * @since MU 1.1 + * @uses get_blogs_of_user() + * + * @param int $user_id The unique ID of the user + * @param int $blog Optional. If no blog_id is provided, current site is used + * @return bool + */ function is_user_member_of_blog( $user_id, $blog_id = 0 ) { $user_id = (int) $user_id; $blog_id = (int) $blog_id; @@ -110,6 +158,17 @@ function is_user_member_of_blog( $user_id, $blog_id = 0 ) { return false; } +/** + * The number of active users in your installation. + * + * This function also saves the count as a site option, + * which speeds up future lookups. + * + * @since MU 2.7 + * @uses update_site_option() + * + * @return int + */ function get_user_count() { global $wpdb; @@ -125,6 +184,18 @@ function get_user_count() { return $count; } +/** + * The number of active sites on your installation. + * + * This function also saves the count as a site option, + * which speeds up future lookups. + * + * @since MU 1.0 + * @uses update_site_option() + * + * @param int $id Optional. A site_id. + * @return int + */ function get_blog_count( $id = 0 ) { global $wpdb; @@ -143,6 +214,15 @@ function get_blog_count( $id = 0 ) { return $count; } +/** + * Get a blog post from any site on the network. + * + * @since MU 1.0 + * + * @param int $blog_id ID of the blog. + * @param int $post_id ID of the post you're looking for. + * @return object The post. + */ function get_blog_post( $blog_id, $post_id ) { global $wpdb; @@ -156,6 +236,23 @@ function get_blog_post( $blog_id, $post_id ) { return $post; } +/** + * Add a user to a blog. + * + * Use the 'add_user_to_blog' action to fire an event when + * users are added to a blog. + * + * @since MU 1.0 + * @uses switch_to_blog() + * @uses update_user_meta() + * @uses wp_cache_delete() + * @uses restore_current_blog() + * + * @param int $blog_id ID of the blog you're adding the user to. + * @param int $user_id ID of the user you're adding. + * @param string $role The role you want the user to have + * @return bool + */ function add_user_to_blog( $blog_id, $user_id, $role ) { switch_to_blog($blog_id); @@ -178,6 +275,27 @@ function add_user_to_blog( $blog_id, $user_id, $role ) { return true; } +/** + * Remove a user from a blog. + * + * Use the 'remove_user_from_blog' action to fire an event when + * users are removed from a blog. + * + * Accepts an optional $reassign parameter, if you want to + * reassign the user's blog posts to another user upon removal. + * + * @since MU 1.0 + * @uses switch_to_blog() + * @uses get_user_meta() + * @uses get_blogs_of_user() + * @uses update_user_meta() + * @uses restore_current_blog() + * + * @param int $user_id ID of the user you're removing. + * @param int $blog_id ID of the blog you're removing the user from. + * @param string $reassign Optional. A user to whom to reassign posts. + * @return bool + */ function remove_user_from_blog($user_id, $blog_id = '', $reassign = '') { global $wpdb; switch_to_blog($blog_id); @@ -225,6 +343,20 @@ function remove_user_from_blog($user_id, $blog_id = '', $reassign = '') { restore_current_blog(); } +/** + * Create an empty blog. + * + * @since MU 1.0 + * @uses switch_to_blog() + * @uses install_blog() + * @uses restore_current_blog() + * + * @param string $domain The new blog's domain. + * @param string $path The new blog's path. + * @param string $string The new blog's title. + * @param int $site Optional. Defaults to 1. + * @return int $blog_id The ID of the newly created blog + */ function create_empty_blog( $domain, $path, $weblog_title, $site_id = 1 ) { $domain = addslashes( $domain ); $weblog_title = addslashes( $weblog_title ); @@ -250,6 +382,19 @@ function create_empty_blog( $domain, $path, $weblog_title, $site_id = 1 ) { return $blog_id; } +/** + * Get the permalink for a post on another blog. + * + * @since MU 1.0 + * @uses wp_cache_get() + * @uses switch_to_blog() + * @uses restore_current_blog() + * @uses wp_cache_add() + * + * @param int $_blog_id ID of the source blog. + * @param int $post_id ID of the desired post. + * @return string $link The post's permalink + */ function get_blog_permalink( $_blog_id, $post_id ) { $key = "{$_blog_id}-{$post_id}-blog_permalink"; $link = wp_cache_get( $key, 'site-options' ); @@ -262,6 +407,22 @@ function get_blog_permalink( $_blog_id, $post_id ) { return $link; } +/** + * Get a blog's numeric ID from its URL. + * + * On a subdirectory installation like example.com/blog1/, + * $domain will be the root 'example.com' and $path the + * subdirectory '/blog1/'. With subdomains like blog1.example.com, + * $domain is 'blog1.example.com' and $path is '/'. + * + * @since MU 2.6.5 + * @uses wp_cache_get() + * @uses wp_cache_set() + * + * @param string $domain + * @param string $path Optional. Not required for subdomain installations. + * @return int $id + */ function get_blog_id_from_url( $domain, $path = '/' ) { global $wpdb;