WordPress.org
Get WordPress

Make WordPress Core

Changeset 54855


Ignore:
Timestamp:
11/17/2022 06:13:47 PM (22 months ago)
Author:
SergeyBiryukov
Message:

Docs: Update various DocBlocks and inline comments per the documentation standards.

Includes minor formatting edits for consistency.

Follow-up to [53/tests], [12179], [12946], [35288], [37884], [38810], [38928], [46596], [48131], [52955], [53548], [53813], [53873], [54118], [54316], [54420], [54421], [54803].

See #56792.

Location:
trunk
Files:
20 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/js/_enqueues/lib/nav-menu.js

    r54316 r54855  
    15581558    });
    15591559
    1560     // Show bulk action
     1560    // Show bulk action.
    15611561    $( document ).on( 'menu-item-added', function() {
    15621562        if ( ! $( '.bulk-actions' ).is( ':visible' ) ) {
    … …  
    15651565    } );
    15661566
    1567     // Hide bulk action
     1567    // Hide bulk action.
    15681568    $( document ).on( 'menu-removing-item', function( e, el ) {
    15691569        var menuElement = $( el ).parents( '#menu-to-edit' );

  • trunk/src/wp-includes/class-wp-list-util.php

    r54133 r54855  
    208208     *
    209209     * @param string|array $orderby       Optional. Either the field name to order by or an array
    210      *                                    of multiple orderby fields as $orderby => $order.
    211      * @param string       $order         Optional. Either 'ASC' or 'DESC'. Only used if $orderby
    212      *                                    is a string.
     210     *                                    of multiple orderby fields as `$orderby => $order`.
     211     *                                    Default empty array.
     212     * @param string       $order         Optional. Either 'ASC' or 'DESC'. Only used if `$orderby`
     213     *                                    is a string. Default 'ASC'.
    213214     * @param bool         $preserve_keys Optional. Whether to preserve keys. Default false.
    214215     * @return array The sorted array.

  • trunk/src/wp-includes/compat.php

    r53365 r54855  
    157157 * Internal compat function to mimic mb_strlen().
    158158 *
    159  * Only understands UTF-8 and 8bit.  All other character sets will be treated as 8bit.
     159 * Only understands UTF-8 and 8bit. All other character sets will be treated as 8bit.
    160160 * For `$encoding === UTF-8`, the `$str` input is expected to be a valid UTF-8 byte
    161161 * sequence. The behavior of this function for invalid inputs is undefined.

  • trunk/src/wp-includes/functions.php

    r54797 r54855  
    935935     *
    936936     * @param string[] $post_links An array of enclosure links.
    937      * @param int      $post_ID    Post ID.
     937     * @param int      $post_id    Post ID.
    938938     */
    939939    $post_links = apply_filters( 'enclosure_links', $post_links, $post->ID );
    … …  
    33313331     *
    33323332     * @param string[] $wp_get_mime_types Mime types keyed by the file extension regex
    3333      *                                 corresponding to those types.
     3333     *                                    corresponding to those types.
    33343334     */
    33353335    return apply_filters(
    … …  
    52015201 * @param array        $list          An array of objects or arrays to sort.
    52025202 * @param string|array $orderby       Optional. Either the field name to order by or an array
    5203  *                                    of multiple orderby fields as $orderby => $order.
    5204  * @param string       $order         Optional. Either 'ASC' or 'DESC'. Only used if $orderby
    5205  *                                    is a string.
     5203 *                                    of multiple orderby fields as `$orderby => $order`.
     5204 *                                    Default empty array.
     5205 * @param string       $order         Optional. Either 'ASC' or 'DESC'. Only used if `$orderby`
     5206 *                                    is a string. Default 'ASC'.
    52065207 * @param bool         $preserve_keys Optional. Whether to preserve keys. Default false.
    52075208 * @return array The sorted array.

  • trunk/src/wp-includes/l10n.php

    r54669 r54855  
    177177 *
    178178 * @since 2.2.0
    179  * @since 5.5.0 Introduced gettext-{$domain} filter.
     179 * @since 5.5.0 Introduced `gettext-{$domain}` filter.
    180180 *
    181181 * @param string $text   Text to translate.
    … …  
    243243 *
    244244 * @since 2.8.0
    245  * @since 5.5.0 Introduced gettext_with_context-{$domain} filter.
     245 * @since 5.5.0 Introduced `gettext_with_context-{$domain}` filter.
    246246 *
    247247 * @param string $text    Text to translate.
    … …  
    464464 *
    465465 * @since 2.8.0
    466  * @since 5.5.0 Introduced ngettext-{$domain} filter.
     466 * @since 5.5.0 Introduced `ngettext-{$domain}` filter.
    467467 *
    468468 * @param string $single The text to be used if the number is singular.
    … …  
    522522 *
    523523 * @since 2.8.0
    524  * @since 5.5.0 Introduced ngettext_with_context-{$domain} filter.
     524 * @since 5.5.0 Introduced `ngettext_with_context-{$domain}` filter.
    525525 *
    526526 * @param string $single  The text to be used if the number is singular.
    … …  
    10231023
    10241024/**
    1025  * Loads the child themes translated strings.
    1026  *
    1027  * If the current locale exists as a .mo file in the child themes
     1025 * Loads the child theme's translated strings.
     1026 *
     1027 * If the current locale exists as a .mo file in the child theme's
    10281028 * root directory, it will be included in the translated strings by the $domain.
    10291029 *
    … …  
    13621362 * @param string $dir A directory to search for language files.
    13631363 *                    Default WP_LANG_DIR.
    1364  * @return string[] An array of language codes or an empty array if no languages are present. Language codes are formed by stripping the .mo extension from the language file names.
     1364 * @return string[] An array of language codes or an empty array if no languages are present.
     1365 *                  Language codes are formed by stripping the .mo extension from the language file names.
    13651366 */
    13661367function get_available_languages( $dir = null ) {

  • trunk/src/wp-includes/load.php

    r54803 r54855  
    13231323 *
    13241324 * @global WP_Textdomain_Registry $wp_textdomain_registry WordPress Textdomain Registry.
    1325  * @global WP_Locale $wp_locale WordPress date and time locale object.
     1325 * @global WP_Locale              $wp_locale              WordPress date and time locale object.
    13261326 */
    13271327function wp_load_translations_early() {
    1328     global $wp_locale, $wp_textdomain_registry;
     1328    global $wp_textdomain_registry, $wp_locale;
    13291329
    13301330    static $loaded = false;

  • trunk/src/wp-includes/post.php

    r54854 r54855  
    15481548 * @global array $wp_post_types List of post types.
    15491549 *
    1550  * @param string       $post_type Post type key. Must not exceed 20 characters and may
    1551  *                                only contain lowercase alphanumeric characters, dashes,
    1552  *                                and underscores. See sanitize_key().
     1550 * @param string       $post_type Post type key. Must not exceed 20 characters and may only contain
     1551 *                                lowercase alphanumeric characters, dashes, and underscores. See sanitize_key().
    15531552 * @param array|string $args {
    15541553 *     Array or string of arguments for registering a post type.
    … …  
    41994198        if ( $update && strtolower( urlencode( $post_name ) ) == $check_name && get_post_field( 'post_name', $post_ID ) == $check_name ) {
    42004199            $post_name = $check_name;
    4201         } else { // new post, or slug has changed.
     4200        } else { // New post, or slug has changed.
    42024201            $post_name = sanitize_title( $post_name );
    42034202        }

  • trunk/src/wp-includes/rest-api/class-wp-rest-server.php

    r54663 r54855  
    554554     *
    555555     * @since 4.4.0
    556      * @since 5.4.0 The $embed parameter can now contain a list of link relations to include.
     556     * @since 5.4.0 The `$embed` parameter can now contain a list of link relations to include.
    557557     *
    558558     * @param WP_REST_Response $response Response object.
    … …  
    678678     *
    679679     * @since 4.4.0
    680      * @since 5.4.0 The $embed parameter can now contain a list of link relations to include.
     680     * @since 5.4.0 The `$embed` parameter can now contain a list of link relations to include.
    681681     *
    682682     * @param array         $data  Data from the request.
    … …  
    760760     *
    761761     * @since 4.4.0
    762      * @since 6.0.0 The $embed parameter can now contain a list of link relations to include
     762     * @since 6.0.0 The `$embed` parameter can now contain a list of link relations to include.
    763763     *
    764764     * @param WP_REST_Response $response Response object.

  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

    r54754 r54855  
    660660        ) {
    661661            /*
    662              * `wp_unique_post_slug()` returns the same
    663              * slug for 'draft' or 'pending' posts.
     662             * `wp_unique_post_slug()` returns the same slug for 'draft' or 'pending' posts.
    664663             *
    665              * To ensure that a unique slug is generated,
    666              * pass the post data with the 'publish' status.
     664             * To ensure that a unique slug is generated, pass the post data with the 'publish' status.
    667665             */
    668666            $prepared_post->post_name = wp_unique_post_slug(
    … …  
    863861
    864862        /*
    865          * `wp_unique_post_slug()` returns the same
    866          * slug for 'draft' or 'pending' posts.
    867          *
    868          * To ensure that a unique slug is generated,
    869          * pass the post data with the 'publish' status.
     863         * `wp_unique_post_slug()` returns the same slug for 'draft' or 'pending' posts.
     864         *
     865         * To ensure that a unique slug is generated, pass the post data with the 'publish' status.
    870866         */
    871867        if ( ! empty( $post->post_name ) && in_array( $post_status, array( 'draft', 'pending' ), true ) ) {
    872868            $post_parent     = ! empty( $post->post_parent ) ? $post->post_parent : 0;
    873             $post->post_name = wp_unique_post_slug( $post->post_name, $post->ID, 'publish', $post->post_type, $post_parent );
     869            $post->post_name = wp_unique_post_slug(
     870                $post->post_name,
     871                $post->ID,
     872                'publish',
     873                $post->post_type,
     874                $post_parent
     875            );
    874876        }
    875877

  • trunk/src/wp-includes/sitemaps/providers/class-wp-sitemaps-posts.php

    r53551 r54855  
    222222                'update_post_term_cache' => false,
    223223                'update_post_meta_cache' => false,
    224                 'ignore_sticky_posts'    => true, // sticky posts will still appear, but they won't be moved to the front.
     224                'ignore_sticky_posts'    => true, // Sticky posts will still appear, but they won't be moved to the front.
    225225            ),
    226226            $post_type

  • trunk/src/wp-includes/taxonomy.php

    r54810 r54855  
    391391 * @global WP_Taxonomy[] $wp_taxonomies Registered taxonomies.
    392392 *
    393  * @param string       $taxonomy    Taxonomy key, must not exceed 32 characters and may only contain lowercase alphanumeric
    394  *                                  characters, dashes, and underscores. See sanitize_key().
     393 * @param string       $taxonomy    Taxonomy key. Must not exceed 32 characters and may only contain
     394 *                                  lowercase alphanumeric characters, dashes, and underscores. See sanitize_key().
    395395 * @param array|string $object_type Object type or array of object types with which the taxonomy should be associated.
    396396 * @param array|string $args        {

  • trunk/src/wp-includes/theme.php

    r54419 r54855  
    35683568        $wp_customize->register_controls();
    35693569
    3570         /** This filter is documented in /wp-includes/class-wp-customize-manager.php */
     3570        /** This filter is documented in wp-includes/class-wp-customize-manager.php */
    35713571        do_action( 'customize_register', $wp_customize );
    35723572    }

  • trunk/tests/phpunit/includes/utils.php

    r53856 r54855  
    460460
    461461/**
    462  * Use to create objects by yourself
     462 * Use to create objects by yourself.
    463463 */
    464464class MockClass extends stdClass {}
    465465
    466466/**
    467  * Drops all tables from the WordPress database
     467 * Drops all tables from the WordPress database.
    468468 */
    469469function drop_tables() {

  • trunk/tests/phpunit/tests/functions/sizeFormat.php

    r52955 r54855  
    1515    public function _data_size_format() {
    1616        return array(
    17             // Invalid values
     17            // Invalid values.
    1818            array( array(), 0, false ),
    1919            array( 'baba', 0, false ),
    … …  
    2121            array( '-1', 0, false ),
    2222            array( -1, 0, false ),
    23             // Bytes
     23            // Bytes.
    2424            array( 0, 0, '0 B' ),
    2525            array( 1, 0, '1 B' ),
    2626            array( 1023, 0, '1,023 B' ),
    27             // Kilobytes
     27            // Kilobytes.
    2828            array( KB_IN_BYTES, 0, '1 KB' ),
    2929            array( KB_IN_BYTES, 2, '1.00 KB' ),
    … …  
    3131            array( 2.5 * KB_IN_BYTES, 2, '2.50 KB' ),
    3232            array( 10 * KB_IN_BYTES, 0, '10 KB' ),
    33             // Megabytes
     33            // Megabytes.
    3434            array( (string) 1024 * KB_IN_BYTES, 2, '1.00 MB' ),
    3535            array( MB_IN_BYTES, 0, '1 MB' ),
    3636            array( 2.5 * MB_IN_BYTES, 0, '3 MB' ),
    3737            array( 2.5 * MB_IN_BYTES, 2, '2.50 MB' ),
    38             // Gigabytes
     38            // Gigabytes.
    3939            array( (string) 1024 * MB_IN_BYTES, 2, '1.00 GB' ),
    4040            array( GB_IN_BYTES, 0, '1 GB' ),
    4141            array( 2.5 * GB_IN_BYTES, 0, '3 GB' ),
    4242            array( 2.5 * GB_IN_BYTES, 2, '2.50 GB' ),
    43             // Terabytes
     43            // Terabytes.
    4444            array( (string) 1024 * GB_IN_BYTES, 2, '1.00 TB' ),
    4545            array( TB_IN_BYTES, 0, '1 TB' ),
    4646            array( 2.5 * TB_IN_BYTES, 0, '3 TB' ),
    4747            array( 2.5 * TB_IN_BYTES, 2, '2.50 TB' ),
    48             // Petabytes
     48            // Petabytes.
    4949            array( (string) 1024 * TB_IN_BYTES, 2, '1.00 PB' ),
    5050            array( PB_IN_BYTES, 0, '1 PB' ),
    5151            array( 2.5 * PB_IN_BYTES, 0, '3 PB' ),
    5252            array( 2.5 * PB_IN_BYTES, 2, '2.50 PB' ),
    53             // Exabytes
     53            // Exabytes.
    5454            array( (string) 1024 * PB_IN_BYTES, 2, '1.00 EB' ),
    5555            array( EB_IN_BYTES, 0, '1 EB' ),
    5656            array( 2.5 * EB_IN_BYTES, 0, '3 EB' ),
    5757            array( 2.5 * EB_IN_BYTES, 2, '2.50 EB' ),
    58             // Zettabytes
     58            // Zettabytes.
    5959            array( (string) 1024 * EB_IN_BYTES, 2, '1.00 ZB' ),
    6060            array( ZB_IN_BYTES, 0, '1 ZB' ),
    6161            array( 2.5 * ZB_IN_BYTES, 0, '3 ZB' ),
    6262            array( 2.5 * ZB_IN_BYTES, 2, '2.50 ZB' ),
    63             // Yottabytes
     63            // Yottabytes.
    6464            array( (string) 1024 * ZB_IN_BYTES, 2, '1.00 YB' ),
    6565            array( YB_IN_BYTES, 0, '1 YB' ),
    6666            array( 2.5 * YB_IN_BYTES, 0, '3 YB' ),
    6767            array( 2.5 * YB_IN_BYTES, 2, '2.50 YB' ),
    68             // Edge values
     68            // Edge values.
    6969            array( TB_IN_BYTES + ( TB_IN_BYTES / 2 ) + MB_IN_BYTES, 1, '1.5 TB' ),
    7070            array( TB_IN_BYTES - MB_IN_BYTES - KB_IN_BYTES, 3, '1,023.999 GB' ),

  • trunk/tests/phpunit/tests/functions/wpListSort.php

    r51667 r54855  
    1313     *
    1414     * @param string|array $orderby Either the field name to order by or an array
    15      *                              of multiple orderby fields as $orderby => $order.
     15     *                              of multiple orderby fields as `$orderby => $order`.
    1616     * @param string       $order   Either 'ASC' or 'DESC'.
    1717     */
    … …  
    338338     *
    339339     * @param string|array $orderby Either the field name to order by or an array
    340      *                              of multiple orderby fields as $orderby => $order.
     340     *                              of multiple orderby fields as `$orderby => $order`.
    341341     * @param string       $order   Either 'ASC' or 'DESC'.
    342342     */

  • trunk/tests/phpunit/tests/functions/wpListUtil.php

    r54663 r54855  
    6565     * @param string $target_key   The key to pluck.
    6666     * @param array  $expected     The expected array.
    67      * @param string $index_key    Optional. Field from the element to use as keys for the new array. Default null.
     67     * @param string $index_key    Optional. Field from the element to use as keys for the new array.
     68     *                             Default null.
    6869     */
    6970    public function test_wp_list_util_pluck( $target_array, $target_key, $expected, $index_key = null ) {
    … …  
    157158     * @param array  $expected      The expected array.
    158159     * @param array  $target_array  The array to create a list from.
    159      * @param array  $orderby       Optional. Either the field name to order by or an array of multiple orderby fields as $orderby => $order.
     160     * @param array  $orderby       Optional. Either the field name to order by or an array
     161     *                              of multiple orderby fields as `$orderby => $order`.
    160162     *                              Default empty array.
    161      * @param string $order         Optional. Either 'ASC' or 'DESC'. Only used if $orderby is a string. Default 'ASC'.
     163     * @param string $order         Optional. Either 'ASC' or 'DESC'. Only used if `$orderby`
     164     *                              is a string. Default 'ASC'.
    162165     * @param bool   $preserve_keys Optional. Whether to preserve keys. Default false.
    163166     */
    … …  
    956959     * @param array  $expected      The expected array.
    957960     * @param array  $target_array  The array to create a list from.
    958      * @param array  $orderby       Optional. Either the field name to order by or an array of multiple orderby fields as $orderby => $order.
     961     * @param array  $orderby       Optional. Either the field name to order by or an array
     962     *                              of multiple orderby fields as `$orderby => $order`.
    959963     *                              Default empty array.
    960      * @param string $order         Optional. Either 'ASC' or 'DESC'. Only used if $orderby is a string. Default 'ASC'.
     964     * @param string $order         Optional. Either 'ASC' or 'DESC'. Only used if `$orderby`
     965     *                              is a string. Default 'ASC'.
    961966     * @param bool   $preserve_keys Optional. Whether to preserve keys. Default false.
    962967     */

  • trunk/tests/phpunit/tests/functions/wpNonceField.php

    r54420 r54855  
    1515     */
    1616    public function test_wp_nonce_field() {
    17 
    1817        wp_nonce_field();
    1918        $this->expectOutputRegex( '#^<input type="hidden" id="_wpnonce" name="_wpnonce" value=".{10}" /><input type="hidden" name="_wp_http_referer" value="" />$#' );
    … …  
    2524     * @dataProvider data_wp_nonce_field
    2625     *
    27      * @param int|string $action Action name.
    28      * @param string     $name Nonce name.
    29      * @param bool       $referer Whether to set the referer field fior validation.
    30      * @param string     $expected_reg_exp The expected regular expression.
     26     * @param int|string $action          Action name.
     27     * @param string     $name            Nonce name.
     28     * @param bool       $referer         Whether to set the referer field for validation.
     29     * @param string     $expected_regexp The expected regular expression.
    3130     */
    32     public function test_wp_nonce_field_return( $action, $name, $referer, $expected_reg_exp ) {
    33 
    34         $this->assertMatchesRegularExpression( $expected_reg_exp, wp_nonce_field( $action, $name, $referer, false ) );
     31    public function test_wp_nonce_field_return( $action, $name, $referer, $expected_regexp ) {
     32        $this->assertMatchesRegularExpression( $expected_regexp, wp_nonce_field( $action, $name, $referer, false ) );
    3533    }
    3634
    … …  
    4139     */
    4240    public function data_wp_nonce_field() {
    43 
    4441        return array(
    4542            'default'     => array(
    46                 'action'           => - 1,
    47                 'name'             => '_wpnonce',
    48                 'referer'          => true,
    49                 'expected_reg_exp' => '#^<input type="hidden" id="_wpnonce" name="_wpnonce" value=".{10}" /><input type="hidden" name="_wp_http_referer" value="" />$#',
     43                'action'          => -1,
     44                'name'            => '_wpnonce',
     45                'referer'         => true,
     46                'expected_regexp' => '#^<input type="hidden" id="_wpnonce" name="_wpnonce" value=".{10}" /><input type="hidden" name="_wp_http_referer" value="" />$#',
    5047            ),
    5148            'nonce_name'  => array(
    52                 'action'           => - 1,
    53                 'name'             => 'nonce_name',
    54                 'referer'          => true,
    55                 'expected_reg_exp' => '#^<input type="hidden" id="nonce_name" name="nonce_name" value=".{10}" /><input type="hidden" name="_wp_http_referer" value="" />$#',
     49                'action'          => -1,
     50                'name'            => 'nonce_name',
     51                'referer'         => true,
     52                'expected_regexp' => '#^<input type="hidden" id="nonce_name" name="nonce_name" value=".{10}" /><input type="hidden" name="_wp_http_referer" value="" />$#',
    5653            ),
    5754            'action_name' => array(
    58                 'action'           => 'action_name',
    59                 'name'             => '_wpnonce',
    60                 'referer'          => true,
    61                 'expected_reg_exp' => '#^<input type="hidden" id="_wpnonce" name="_wpnonce" value="' . wp_create_nonce( 'action_name' ) . '" /><input type="hidden" name="_wp_http_referer" value="" />$#',
     55                'action'          => 'action_name',
     56                'name'            => '_wpnonce',
     57                'referer'         => true,
     58                'expected_regexp' => '#^<input type="hidden" id="_wpnonce" name="_wpnonce" value="' . wp_create_nonce( 'action_name' ) . '" /><input type="hidden" name="_wp_http_referer" value="" />$#',
    6259            ),
    6360            'no_referer'  => array(
    64                 'action'           => - 1,
    65                 'name'             => '_wpnonce',
    66                 'referer'          => false,
    67                 'expected_reg_exp' => '#^<input type="hidden" id="_wpnonce" name="_wpnonce" value=".{10}" />$#',
     61                'action'          => -1,
     62                'name'            => '_wpnonce',
     63                'referer'         => false,
     64                'expected_regexp' => '#^<input type="hidden" id="_wpnonce" name="_wpnonce" value=".{10}" />$#',
    6865            ),
    6966            '& in name'   => array(
    70                 'action'           => - 1,
    71                 'name'             => 'a&b',
    72                 'referer'          => false,
    73                 'expected_reg_exp' => '#^<input type="hidden" id="a\&amp;b" name="a\&amp;b" value=".{10}" />$#',
     67                'action'          => -1,
     68                'name'            => 'a&b',
     69                'referer'         => false,
     70                'expected_regexp' => '#^<input type="hidden" id="a\&amp;b" name="a\&amp;b" value=".{10}" />$#',
    7471            ),
    7572        );

  • trunk/tests/phpunit/tests/functions/wpRefererField.php

    r54449 r54855  
    1515     */
    1616    public function test_wp_referer_field() {
     17        $_SERVER['REQUEST_URI'] = '/test/';
    1718
    18         $_SERVER['REQUEST_URI'] = '/test/';
    1919        wp_referer_field();
    2020        $this->expectOutputString( '<input type="hidden" name="_wp_http_referer" value="/test/" />' );
    … …  
    2525     */
    2626    public function test_wp_referer_field_return() {
    27 
    2827        $_SERVER['REQUEST_URI'] = '/test/';
    2928

  • trunk/tests/phpunit/tests/rest-api/rest-posts-controller.php

    r54396 r54855  
    15301530    /**
    15311531     * @ticket 55592
     1532     *
    15321533     * @covers WP_REST_Posts_Controller::get_items
    15331534     * @covers ::update_post_thumbnail_cache
    … …  
    15671568    /**
    15681569     * @ticket 55593
     1570     *
    15691571     * @covers WP_REST_Posts_Controller::get_items
    15701572     * @covers ::update_post_parent_caches

  • trunk/tests/phpunit/tests/theme/wpThemeJson.php

    r54821 r54855  
    30273027
    30283028    /**
    3029      * Testing that dynamic properties in theme.json return the value they refrence,
     3029     * Testing that dynamic properties in theme.json return the value they reference,
    30303030     * e.g. array( 'ref' => 'styles.color.background' ) => "#ffffff".
    30313031     *
Note: See TracChangeset for help on using the changeset viewer.