WordPress.org

Make WordPress Core

Ticket #30483: 30483.diff

File 30483.diff, 8.9 KB (added by dustyf, 7 years ago)

Adds docblocks for functions missing them. Fixes missed parameters, descriptions, and some formatting.

  • wp-admin/includes/ms.php

     
    169169                restore_current_blog();
    170170}
    171171
    172 // @todo Merge with wp_delete_user() ?
     172/**
     173 * Delete a user from the network and remove from all sites.
     174 *
     175 * @since 3.0.0
     176 * @todo Merge with wp_delete_user() ?
     177 *
     178 * @param $id The ID of the user.
     179 *
     180 * @return bool True if the user was deleted, otherwise false.
     181 */
    173182function wpmu_delete_user( $id ) {
    174183        global $wpdb;
    175184
     
    225234        return true;
    226235}
    227236
     237/**
     238 * Sends an email when a site administrator email address is changed.
     239 *
     240 * @since 3.0.0
     241 *
     242 * @param $old_value The old email address. Not currently used.
     243 * @param $value The new email address
     244 */
    228245function update_option_new_admin_email( $old_value, $value ) {
    229246        if ( $value == get_option( 'admin_email' ) || !is_email( $value ) )
    230247                return;
     
    278295add_action( 'update_option_new_admin_email', 'update_option_new_admin_email', 10, 2 );
    279296add_action( 'add_option_new_admin_email', 'update_option_new_admin_email', 10, 2 );
    280297
     298/**
     299 * Sends an email when an email address change is requested.
     300 *
     301 * @since 3.0.0
     302 */
    281303function send_confirmation_on_profile_email() {
    282304        global $errors, $wpdb;
    283305        $current_user = wp_get_current_user();
     
    348370}
    349371add_action( 'personal_options_update', 'send_confirmation_on_profile_email' );
    350372
     373/**
     374 * Adds an admin notice alterting the user to check for confirmation email after email address change.
     375 *
     376 * @since 3.0.0
     377 */
    351378function new_user_email_admin_notice() {
    352379        if ( strpos( $_SERVER['PHP_SELF'], 'profile.php' ) && isset( $_GET['updated'] ) && $email = get_option( get_current_user_id() . '_new_email' ) )
    353380                echo "<div class='update-nag'>" . sprintf( __( "Your email address has not been updated yet. Please check your inbox at %s for a confirmation email." ), $email['newemail'] ) . "</div>";
     
    360387 * @since MU
    361388 *
    362389 * @param bool $echo Optional. If $echo is set and the quota is exceeded, a warning message is echoed. Default is true.
    363  * @return int
     390 * @return bool True if user is over upload space quota, otherwise false.
    364391 */
    365392function upload_is_user_over_quota( $echo = true ) {
    366393        if ( get_site_option( 'upload_space_check_disabled' ) )
     
    422449        return min( $size, $available );
    423450}
    424451
    425 // Edit blog upload space setting on Edit Blog page
     452/**
     453 * Displays the edit blog upload space setting form on Edit Blog page.
     454 *
     455 * @since 3.0.0
     456 *
     457 * @param $id The ID of the blog to display the setting for.
     458 */
    426459function upload_space_setting( $id ) {
    427460        switch_to_blog( $id );
    428461        $quota = get_option( 'blog_upload_space' );
     
    440473}
    441474add_action( 'wpmueditblogaction', 'upload_space_setting' );
    442475
     476/**
     477 * Update the status of a user in the database.
     478 *
     479 * Used in core to mark a user as spam or "ham" (not spam) on multisite installs.
     480 *
     481 * @since 3.0.0
     482 *
     483 * @param int    $id         The ID of the user.
     484 * @param string $pref       The column in the wp_users table to update the user's status in (presumably
     485 *                           user_status, spam or deleted).
     486 * @param int    $value      The new status for the user.
     487 * @param null   $deprecated Deprecated as of 3.0.2 and should not be used.
     488 *
     489 * @return mixed
     490 */
    443491function update_user_status( $id, $pref, $value, $deprecated = null ) {
    444492        global $wpdb;
    445493
     
    476524        return $value;
    477525}
    478526
     527/**
     528 * Cleans the user cache for a specific user.
     529 *
     530 * @since 3.0.0
     531 *
     532 * @param $id The user ID.
     533 *
     534 * @return bool|int The ID of the refreshed user.
     535 */
    479536function refresh_user_details( $id ) {
    480537        $id = (int) $id;
    481538
     
    487544        return $id;
    488545}
    489546
     547/**
     548 * Returns the language for a language code.
     549 *
     550 * @since 3.0.0
     551 *
     552 * @param string $code Optional. The two-letter language code.
     553 *
     554 * @return string The language corresponding to $code if it exists. If it does not exist, then the first
     555 *                two letters of $code is returned.
     556 */
    490557function format_code_lang( $code = '' ) {
    491558        $code = strtolower( substr( $code, 0, 2 ) );
    492559        $lang_codes = array(
     
    514581        return strtr( $code, $lang_codes );
    515582}
    516583
     584/**
     585 * Synchronize category and post tag slugs when global terms are enabled.
     586 *
     587 * @since 3.0.0
     588 *
     589 * @param $term     The term.
     590 * @param $taxonomy The taxonomy for $term. Should be 'category' or 'post_tag', as these are the only
     591 *                  taxonomies which are processed by this function; anything else will be returned untouched.
     592 *
     593 * @return object|array Returns $term, after filtering the 'slug' field with sanitize_title() if $taxonomy
     594 *                      is 'category' or 'post_tag'.
     595 */
    517596function sync_category_tag_slugs( $term, $taxonomy ) {
    518597        if ( global_terms_enabled() && ( $taxonomy == 'category' || $taxonomy == 'post_tag' ) ) {
    519598                if ( is_object( $term ) ) {
     
    526605}
    527606add_filter( 'get_term', 'sync_category_tag_slugs', 10, 2 );
    528607
     608/**
     609 * Displays an access denied message when a user tries to view a site's dashboard they do not have access to.
     610 *
     611 * @since 3.2.0
     612 */
    529613function _access_denied_splash() {
    530614        if ( ! is_user_logged_in() || is_network_admin() )
    531615                return;
     
    560644}
    561645add_action( 'admin_page_access_denied', '_access_denied_splash', 99 );
    562646
     647/**
     648 * Checks if the current user has permissions to import new users.
     649 *
     650 * @since 3.0.0
     651 *
     652 * @param $permission A permission to be checked. Currently not used.
     653 *
     654 * @return bool True if the user has proper permissions, false if they do not.
     655 */
    563656function check_import_new_users( $permission ) {
    564657        if ( !is_super_admin() )
    565658                return false;
     
    568661add_filter( 'import_allow_create_users', 'check_import_new_users' );
    569662// See "import_allow_fetch_attachments" and "import_attachment_size_limit" filters too.
    570663
     664/**
     665 * Display a dropdown of available languages.
     666 *
     667 * @since 3.0.0
     668 *
     669 * @param array  $lang_files An array of the language files.
     670 * @param string $current    The current language code.
     671 */
    571672function mu_dropdown_languages( $lang_files = array(), $current = '' ) {
    572673        $flag = false;
    573674        $output = array();
     
    608709        echo implode( "\n\t", $output );
    609710}
    610711
     712/**
     713 * Displays an admin notice to upgrade all sites after a WordPress Core Upgrade.
     714 *
     715 * @since 3.0.0
     716 */
    611717function site_admin_notice() {
    612718        global $wp_db_version;
    613719        if ( !is_super_admin() )
     
    618724add_action( 'admin_notices', 'site_admin_notice' );
    619725add_action( 'network_admin_notices', 'site_admin_notice' );
    620726
     727/**
     728 * Avoids a collision between a site slug and a permalink slug.
     729 *
     730 * In a subdirectory install this will make sure that a site and a post do not use the same subdirectory by checking
     731 * for a site with the same name as a new post.
     732 *
     733 * @since 3.0.0
     734 *
     735 * @param $data array An array of post data.
     736 * @param $postarr An array of posts. Not currently used.
     737 * @return array The new array of post data after checking for collisions.
     738 */
    621739function avoid_blog_page_permalink_collision( $data, $postarr ) {
    622740        if ( is_subdomain_install() )
    623741                return $data;
     
    641759}
    642760add_filter( 'wp_insert_post_data', 'avoid_blog_page_permalink_collision', 10, 2 );
    643761
     762/**
     763 * Handles the display of choosing a users primary site.
     764 *
     765 * This displays the user's primary site and allows the user to choose which site is primary.
     766 * Used in wp-admin/my-sites.php.
     767 *
     768 * @since 3.0.0
     769 */
    644770function choose_primary_blog() {
    645771        ?>
    646772        <table class="form-table">
     
    696822 * Grants Super Admin privileges.
    697823 *
    698824 * @since 3.0.0
     825 *
    699826 * @param int $user_id ID of the user to be granted Super Admin privileges.
    700827 * @return bool True on success, false on failure. This can fail when the user is
    701828 *              already a super admin or when the $super_admins global is defined.
     
    740867 * Revokes Super Admin privileges.
    741868 *
    742869 * @since 3.0.0
     870 *
    743871 * @param int $user_id ID of the user Super Admin privileges to be revoked from.
    744872 * @return bool True on success, false on failure. This can fail when the user's email
    745873 *              is the network admin email or when the $super_admins global is defined.
     
    783911}
    784912
    785913/**
    786  * Whether or not we can edit this network from this page
     914 * Whether or not we can edit this network from this page.
    787915 *
    788  * By default editing of network is restricted to the Network Admin for that site_id this allows for this to be overridden
     916 * By default editing of network is restricted to the Network Admin for that site_id this allows for this to be overridden.
    789917 *
    790918 * @since 3.1.0
    791  * @param integer $site_id The network/site ID to check.
     919 *
     920 * @param  int  $site_id The network/site ID to check.
     921 * @return bool True if network can be edited, otherwise false.
    792922 */
    793923function can_edit_network( $site_id ) {
    794924        global $wpdb;
     
    813943 * Thickbox image paths for Network Admin.
    814944 *
    815945 * @since 3.1.0
     946 *
    816947 * @access private
    817948 */
    818949function _thickbox_path_admin_subfolder() {