Make WordPress Core

Changeset 57644


Ignore:
Timestamp:
02/16/2024 09:45:18 PM (3 years ago)
Author:
johnbillion
Message:

Docs: Various improvements and corrections to inline documentation.

See #59651

Location:
trunk/src
Files:
28 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/class-wp-application-passwords-list-table.php

    r55732 r57644  
    147147         * @since 5.6.0
    148148         *
    149          * @param string $which The location of the bulk actions: 'top' or 'bottom'.
     149         * @param string $which The location of the bulk actions: Either 'top' or 'bottom'.
    150150         */
    151151        protected function display_tablenav( $which ) {
  • trunk/src/wp-admin/includes/class-wp-comments-list-table.php

    r57285 r57644  
    438438                 *
    439439                 * @param string $comment_status The comment status name. Default 'All'.
    440                  * @param string $which          The location of the extra table nav markup: 'top' or 'bottom'.
     440                 * @param string $which          The location of the extra table nav markup: Either 'top' or 'bottom'.
    441441                 */
    442442                do_action( 'manage_comments_nav', $comment_status, $which );
  • trunk/src/wp-admin/includes/class-wp-filesystem-base.php

    r56825 r57644  
    837837         *     Array of arrays containing file information. False if unable to list directory contents.
    838838         *
    839          *     @type array $0... {
     839         *     @type array ...$0 {
    840840         *         Array of file information. Note that some elements may not be available on all filesystems.
    841841         *
  • trunk/src/wp-admin/includes/class-wp-filesystem-direct.php

    r55714 r57644  
    600600         *     Array of arrays containing file information. False if unable to list directory contents.
    601601         *
    602          *     @type array $0... {
     602         *     @type array ...$0 {
    603603         *         Array of file information. Note that some elements may not be available on all filesystems.
    604604         *
  • trunk/src/wp-admin/includes/class-wp-filesystem-ftpext.php

    r55714 r57644  
    732732         *     Array of arrays containing file information. False if unable to list directory contents.
    733733         *
    734          *     @type array $0... {
     734         *     @type array ...$0 {
    735735         *         Array of file information. Note that some elements may not be available on all filesystems.
    736736         *
  • trunk/src/wp-admin/includes/class-wp-filesystem-ftpsockets.php

    r55714 r57644  
    626626         *     Array of arrays containing file information. False if unable to list directory contents.
    627627         *
    628          *     @type array $0... {
     628         *     @type array ...$0 {
    629629         *         Array of file information. Note that some elements may not be available on all filesystems.
    630630         *
  • trunk/src/wp-admin/includes/class-wp-filesystem-ssh2.php

    r57263 r57644  
    746746         *     Array of arrays containing file information. False if unable to list directory contents.
    747747         *
    748          *     @type array $0... {
     748         *     @type array ...$0 {
    749749         *         Array of file information. Note that some elements may not be available on all filesystems.
    750750         *
  • trunk/src/wp-admin/includes/class-wp-list-table.php

    r57285 r57644  
    565565         * @since 3.1.0
    566566         *
    567          * @param string $which The location of the bulk actions: 'top' or 'bottom'.
     567         * @param string $which The location of the bulk actions: Either 'top' or 'bottom'.
    568568         *                      This is designated as optional for backward compatibility.
    569569         */
    … …  
    10131013         * @since 3.1.0
    10141014         *
    1015          * @param string $which
     1015         * @param string $which The location of the pagination: Either 'top' or 'bottom'.
    10161016         */
    10171017        protected function pagination( $which ) {
    … …  
    16641664         *
    16651665         * @since 3.1.0
    1666          * @param string $which
     1666         * @param string $which The location of the navigation: Either 'top' or 'bottom'.
    16671667         */
    16681668        protected function display_tablenav( $which ) {
  • trunk/src/wp-admin/includes/class-wp-ms-sites-list-table.php

    r56665 r57644  
    303303         * @global string $mode List table view mode.
    304304         *
    305          * @param string $which The location of the pagination nav markup: 'top' or 'bottom'.
     305         * @param string $which The location of the pagination nav markup: Either 'top' or 'bottom'.
    306306         */
    307307        protected function pagination( $which ) {
    … …  
    320320         * @since 5.3.0
    321321         *
    322          * @param string $which The location of the extra table nav markup: 'top' or 'bottom'.
     322         * @param string $which The location of the extra table nav markup: Either 'top' or 'bottom'.
    323323         */
    324324        protected function extra_tablenav( $which ) {
    … …  
    334334                         * @since 5.3.0
    335335                         *
    336                          * @param string $which The location of the extra table nav markup: 'top' or 'bottom'.
     336                         * @param string $which The location of the extra table nav markup: Either 'top' or 'bottom'.
    337337                         */
    338338                        do_action( 'restrict_manage_sites', $which );
    … …  
    354354                 * @since 5.3.0
    355355                 *
    356                  * @param string $which The location of the extra table nav markup: 'top' or 'bottom'.
     356                 * @param string $which The location of the extra table nav markup: Either 'top' or 'bottom'.
    357357                 */
    358358                do_action( 'manage_sites_extra_tablenav', $which );
  • trunk/src/wp-admin/includes/plugin.php

    r57592 r57644  
    494494
    495495/**
    496  * Returns drop-ins that WordPress uses.
     496 * Returns drop-in plugins that WordPress uses.
    497497 *
    498498 * Includes Multisite drop-ins only when is_multisite()
    499499 *
    500500 * @since 3.0.0
    501  * @return array[] Key is file name. The value is an array, with the first value the
    502  *  purpose of the drop-in and the second value the name of the constant that must be
    503  *  true for the drop-in to be used, or true if no constant is required.
     501 *
     502 * @return array[] {
     503 *     Key is file name. The value is an array of data about the drop-in.
     504 *
     505 *     @type array ...$0 {
     506 *         Data about the drop-in.
     507 *
     508 *         @type string      $0 The purpose of the drop-in.
     509 *         @type string|true $1 Name of the constant that must be true for the drop-in
     510 *                              to be used, or true if no constant is required.
     511 *     }
     512 * }
    504513 */
    505514function _get_dropins() {
  • trunk/src/wp-admin/includes/revision.php

    r56548 r57644  
    8686                 * @param WP_Post $compare_from   The revision post object to compare to or from.
    8787                 * @param string  $context        The context of whether the current revision is the old
    88                  *                                or the new one. Values are 'to' or 'from'.
     88                 *                                or the new one. Either 'to' or 'from'.
    8989                 */
    9090                $content_from = $compare_from ? apply_filters( "_wp_post_revision_field_{$field}", $compare_from->$field, $field, $compare_from, 'from' ) : '';
  • trunk/src/wp-admin/includes/theme.php

    r57382 r57644  
    449449 * @since 2.8.0
    450450 *
    451  * @param string       $action API action to perform: 'query_themes', 'theme_information',
     451 * @param string       $action API action to perform: Accepts 'query_themes', 'theme_information',
    452452 *                             'hot_tags' or 'feature_list'.
    453453 * @param array|object $args   {
  • trunk/src/wp-admin/includes/update.php

    r57084 r57644  
    10771077 * @since 5.5.0
    10781078 *
    1079  * @param string $type The type of update being checked: 'theme' or 'plugin'.
     1079 * @param string $type The type of update being checked: Either 'theme' or 'plugin'.
    10801080 * @return bool True if auto-updates are enabled for `$type`, false otherwise.
    10811081 */
    … …  
    11171117 * @since 5.6.0
    11181118 *
    1119  * @param string    $type   The type of update being checked: 'theme' or 'plugin'.
     1119 * @param string    $type   The type of update being checked: Either 'theme' or 'plugin'.
    11201120 * @param bool|null $update Whether to update. The value of null is internally used
    11211121 *                          to detect whether nothing has hooked into this filter.
  • trunk/src/wp-includes/block-template-utils.php

    r57627 r57644  
    175175
    176176        /**
    177          * Filters the list of template types.
     177         * Filters the list of default template types.
    178178         *
    179179         * @since 5.9.0
    … …  
    249249 * @access private
    250250 *
    251  * @param string $template_type 'wp_template' or 'wp_template_part'.
     251 * @param string $template_type Template type. Either 'wp_template' or 'wp_template_part'.
    252252 * @param string $slug          Template slug.
    253253 * @return array|null {
    … …  
    306306 * @access private
    307307 *
    308  * @param string $template_type 'wp_template' or 'wp_template_part'.
     308 * @param string $template_type Template type. Either 'wp_template' or 'wp_template_part'.
    309309 * @param array  $query {
    310310 *     Arguments to retrieve templates. Optional, empty by default.
    … …  
    521521 *
    522522 * @param array  $template_file Theme file.
    523  * @param string $template_type 'wp_template' or 'wp_template_part'.
     523 * @param string $template_type Template type. Either 'wp_template' or 'wp_template_part'.
    524524 * @return WP_Block_Template Template.
    525525 */
    … …  
    926926 *     @type string   $post_type Post type to get the templates for.
    927927 * }
    928  * @param string $template_type 'wp_template' or 'wp_template_part'.
     928 * @param string $template_type Template type. Either 'wp_template' or 'wp_template_part'.
    929929 * @return WP_Block_Template[] Array of block templates.
    930930 */
    … …  
    947947         *     @type string   $post_type Post type to get the templates for.
    948948         * }
    949          * @param string $template_type 'wp_template' or 'wp_template_part'.
     949         * @param string $template_type Template type. Either 'wp_template' or 'wp_template_part'.
    950950         */
    951951        $templates = apply_filters( 'pre_get_block_templates', null, $query, $template_type );
    … …  
    10521052 *
    10531053 * @param string $id            Template unique identifier (example: 'theme_slug//template_slug').
    1054  * @param string $template_type Optional. Template type: 'wp_template' or 'wp_template_part'.
     1054 * @param string $template_type Optional. Template type. Either 'wp_template' or 'wp_template_part'.
    10551055 *                              Default 'wp_template'.
    10561056 * @return WP_Block_Template|null Template.
    … …  
    10671067         *                                               or null to allow WP to run its normal queries.
    10681068         * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
    1069          * @param string                 $template_type  Template type: 'wp_template' or 'wp_template_part'.
     1069         * @param string                 $template_type  Template type. Either 'wp_template' or 'wp_template_part'.
    10701070         */
    10711071        $block_template = apply_filters( 'pre_get_block_template', null, $id, $template_type );
    … …  
    11131113         * @param WP_Block_Template|null $block_template The found block template, or null if there isn't one.
    11141114         * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
    1115          * @param array                  $template_type  Template type: 'wp_template' or 'wp_template_part'.
     1115         * @param string                 $template_type  Template type. Either 'wp_template' or 'wp_template_part'.
    11161116         */
    11171117        return apply_filters( 'get_block_template', $block_template, $id, $template_type );
    … …  
    11261126 *
    11271127 * @param string $id            Template unique identifier (example: 'theme_slug//template_slug').
    1128  * @param string $template_type Optional. Template type: 'wp_template' or 'wp_template_part'.
     1128 * @param string $template_type Optional. Template type. Either 'wp_template' or 'wp_template_part'.
    11291129 *                              Default 'wp_template'.
    11301130 * @return WP_Block_Template|null The found block template, or null if there isn't one.
    … …  
    11411141         *                                               or null to allow WP to run its normal queries.
    11421142         * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
    1143          * @param string                 $template_type  Template type: 'wp_template' or 'wp_template_part'.
     1143         * @param string                 $template_type  Template type. Either 'wp_template' or 'wp_template_part'.
    11441144         */
    11451145        $block_template = apply_filters( 'pre_get_block_file_template', null, $id, $template_type );
    … …  
    11751175         * @param WP_Block_Template|null $block_template The found block template, or null if there is none.
    11761176         * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
    1177          * @param string                 $template_type  Template type: 'wp_template' or 'wp_template_part'.
     1177         * @param string                 $template_type  Template type. Either 'wp_template' or 'wp_template_part'.
    11781178         */
    11791179        return apply_filters( 'get_block_file_template', $block_template, $id, $template_type );
    … …  
    11851185 * @since 5.9.0
    11861186 *
    1187  * @param string $part The block template part to print. Use "header" or "footer".
     1187 * @param string $part The block template part to print. Either 'header' or 'footer'.
    11881188 */
    11891189function block_template_part( $part ) {
    … …  
    12191219 *
    12201220 * @param string $path The path of the file in the theme.
    1221  * @return Bool Whether this file is in an ignored directory.
     1221 * @return bool Whether this file is in an ignored directory.
    12221222 */
    12231223function wp_is_theme_directory_ignored( $path ) {
    … …  
    13481348 * @since 6.1.0
    13491349 *
    1350  * @param string  $slug           The template slug to be created.
    1351  * @param boolean $is_custom      Optional. Indicates if a template is custom or
     1350 * @param string $slug            The template slug to be created.
     1351 * @param bool   $is_custom       Optional. Indicates if a template is custom or
    13521352 *                                part of the template hierarchy. Default false.
    13531353 * @param string $template_prefix Optional. The template prefix for the created template.
  • trunk/src/wp-includes/blocks.php

    r57627 r57644  
    17581758 *                                 style_handle (name of the stylesheet to be enqueued),
    17591759 *                                 inline_style (string containing the CSS to be added).
     1760 *                                 See WP_Block_Styles_Registry::register().
    17601761 * @return bool True if the block style was registered with success and false otherwise.
    17611762 */
  • trunk/src/wp-includes/class-wp-customize-nav-menus.php

    r56687 r57644  
    938938         *     Post array. Note that post_status is overridden to be `auto-draft`.
    939939         *
    940          * @var string $post_title   Post title. Required.
    941          * @var string $post_type    Post type. Required.
    942          * @var string $post_name    Post name.
    943          * @var string $post_content Post content.
     940         *     @type string $post_title   Post title. Required.
     941         *     @type string $post_type    Post type. Required.
     942         *     @type string $post_name    Post name.
     943         *     @type string $post_content Post content.
    944944         * }
    945945         * @return WP_Post|WP_Error Inserted auto-draft post object or error.
  • trunk/src/wp-includes/class-wp-date-query.php

    r57189 r57644  
    10581058         *
    10591059         * @param string $relation Raw relation key from the query argument.
    1060          * @return string Sanitized relation ('AND' or 'OR').
     1060         * @return string Sanitized relation. Either 'AND' or 'OR'.
    10611061         */
    10621062        public function sanitize_relation( $relation ) {
  • trunk/src/wp-includes/class-wp-http.php

    r57501 r57644  
    612612         * @param string|array $args Optional. Override the defaults.
    613613         * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
    614          *                        A WP_Error instance upon error.
     614         *                        A WP_Error instance upon error. See WP_Http::response() for details.
    615615         */
    616616        public function post( $url, $args = array() ) {
    … …  
    630630         * @param string|array $args Optional. Override the defaults.
    631631         * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
    632          *                        A WP_Error instance upon error.
     632         *                        A WP_Error instance upon error. See WP_Http::response() for details.
    633633         */
    634634        public function get( $url, $args = array() ) {
    … …  
    648648         * @param string|array $args Optional. Override the defaults.
    649649         * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
    650          *                        A WP_Error instance upon error.
     650         *                        A WP_Error instance upon error. See WP_Http::response() for details.
    651651         */
    652652        public function head( $url, $args = array() ) {
  • trunk/src/wp-includes/class-wp-paused-extensions-storage.php

    r54133 r57644  
    1616
    1717        /**
    18          * Type of extension. Used to key extension storage.
     18         * Type of extension. Used to key extension storage. Either 'plugin' or 'theme'.
    1919         *
    2020         * @since 5.2.0
  • trunk/src/wp-includes/class-wp-script-modules.php

    r57593 r57644  
    4545         *                                        Optional. List of dependencies.
    4646         *
    47          *                                        @type string|array $0... {
     47         *                                        @type string|array ...$0 {
    4848         *                                            An array of script module identifiers of the dependencies of this script
    4949         *                                            module. The dependencies can be strings or arrays. If they are arrays,
    … …  
    110110         *                                        Optional. List of dependencies.
    111111         *
    112          *                                        @type string|array $0... {
     112         *                                        @type string|array ...$0 {
    113113         *                                            An array of script module identifiers of the dependencies of this script
    114114         *                                            module. The dependencies can be strings or arrays. If they are arrays,
  • trunk/src/wp-includes/class-wp-site-query.php

    r55988 r57644  
    159159         *     @type string[]        $path__in               Array of paths to include affiliated sites for. Default empty.
    160160         *     @type string[]        $path__not_in           Array of paths to exclude affiliated sites for. Default empty.
    161          *     @type int             $public                 Limit results to public sites. Accepts '1' or '0'. Default empty.
    162          *     @type int             $archived               Limit results to archived sites. Accepts '1' or '0'. Default empty.
    163          *     @type int             $mature                 Limit results to mature sites. Accepts '1' or '0'. Default empty.
    164          *     @type int             $spam                   Limit results to spam sites. Accepts '1' or '0'. Default empty.
    165          *     @type int             $deleted                Limit results to deleted sites. Accepts '1' or '0'. Default empty.
     161         *     @type int             $public                 Limit results to public sites. Accepts 1 or 0. Default empty.
     162         *     @type int             $archived               Limit results to archived sites. Accepts 1 or 0. Default empty.
     163         *     @type int             $mature                 Limit results to mature sites. Accepts 1 or 0. Default empty.
     164         *     @type int             $spam                   Limit results to spam sites. Accepts 1 or 0. Default empty.
     165         *     @type int             $deleted                Limit results to deleted sites. Accepts 1 or 0. Default empty.
    166166         *     @type int             $lang_id                Limit results to a language ID. Default empty.
    167167         *     @type string[]        $lang__in               Array of language IDs to include affiliated sites for. Default empty.
  • trunk/src/wp-includes/class-wp-tax-query.php

    r57239 r57644  
    203203         *
    204204         * @param string $relation Raw relation key from the query argument.
    205          * @return string Sanitized relation ('AND' or 'OR').
     205         * @return string Sanitized relation. Either 'AND' or 'OR'.
    206206         */
    207207        public function sanitize_relation( $relation ) {
  • trunk/src/wp-includes/class-wp-user.php

    r57190 r57644  
    192192         * @global wpdb $wpdb WordPress database abstraction object.
    193193         *
    194          * @param string     $field The field to query against: 'id', 'ID', 'slug', 'email' or 'login'.
     194         * @param string     $field The field to query against: Accepts 'id', 'ID', 'slug', 'email' or 'login'.
    195195         * @param string|int $value The field value.
    196196         * @return object|false Raw user object.
  • trunk/src/wp-includes/comment.php

    r57530 r57644  
    279279 * @param string $post_type    Optional. Post type. Default 'post'.
    280280 * @param string $comment_type Optional. Comment type. Default 'comment'.
    281  * @return string Expected return value is 'open' or 'closed'.
     281 * @return string Either 'open' or 'closed'.
    282282 */
    283283function get_default_comment_status( $post_type = 'post', $comment_type = 'comment' ) {
  • trunk/src/wp-includes/general-template.php

    r57170 r57644  
    13201320 *                            Default '»'.
    13211321 * @param bool   $display     Optional. Whether to display or retrieve title. Default true.
    1322  * @param string $seplocation Optional. Location of the separator ('left' or 'right').
     1322 * @param string $seplocation Optional. Location of the separator (either 'left' or 'right').
    13231323 * @return string|void String when `$display` is false, nothing otherwise.
    13241324 */
    … …  
    14401440         * @param string $title       Page title.
    14411441         * @param string $sep         Title separator.
    1442          * @param string $seplocation Location of the separator ('left' or 'right').
     1442         * @param string $seplocation Location of the separator (either 'left' or 'right').
    14431443         */
    14441444        $title = apply_filters( 'wp_title', $title, $sep, $seplocation );
    … …  
    34643464
    34653465                /**
    3466                  * Filters domains and URLs for resource hints of relation type.
     3466                 * Filters domains and URLs for resource hints of the given relation type.
    34673467                 *
    34683468                 * @since 4.6.0
    … …  
    34843484                 *     }
    34853485                 * }
    3486                  * @param string $relation_type The relation type the URLs are printed for,
    3487                  *                              e.g. 'preconnect' or 'prerender'.
     3486                 * @param string $relation_type The relation type the URLs are printed for. One of
     3487                 *                              'dns-prefetch', 'preconnect', 'prefetch', or 'prerender'.
    34883488                 */
    34893489                $urls = apply_filters( 'wp_resource_hints', $urls, $relation_type );
    … …  
    37583758 * Finds out which editor should be displayed by default.
    37593759 *
    3760  * Works out which of the two editors to display as the current editor for a
     3760 * Works out which of the editors to display as the current editor for a
    37613761 * user. The 'html' setting is for the "Text" editor tab.
    37623762 *
    37633763 * @since 2.5.0
    37643764 *
    3765  * @return string Either 'tinymce', or 'html', or 'test'
     3765 * @return string Either 'tinymce', 'html', or 'test'
    37663766 */
    37673767function wp_default_editor() {
  • trunk/src/wp-includes/post.php

    r57638 r57644  
    16011601 * @param array|string $args     Optional. An array of key => value arguments to match against
    16021602 *                               the post type objects. Default empty array.
    1603  * @param string       $output   Optional. The type of output to return. Accepts post type 'names'
     1603 * @param string       $output   Optional. The type of output to return. Either 'names'
    16041604 *                               or 'objects'. Default 'names'.
    16051605 * @param string       $operator Optional. The logical operation to perform. 'or' means only one
  • trunk/src/wp-includes/script-modules.php

    r57593 r57644  
    4545 *                                        Optional. List of dependencies.
    4646 *
    47  *                                        @type string|array $0... {
     47 *                                        @type string|array ...$0 {
    4848 *                                            An array of script module identifiers of the dependencies of this script
    4949 *                                            module. The dependencies can be strings or arrays. If they are arrays,
    … …  
    8282 *                                        Optional. List of dependencies.
    8383 *
    84  *                                        @type string|array $0... {
     84 *                                        @type string|array ...$0 {
    8585 *                                            An array of script module identifiers of the dependencies of this script
    8686 *                                            module. The dependencies can be strings or arrays. If they are arrays,
  • trunk/src/wp-includes/taxonomy.php

    r57335 r57644  
    273273 * @param array  $args     Optional. An array of `key => value` arguments to match against the taxonomy objects.
    274274 *                         Default empty array.
    275  * @param string $output   Optional. The type of output to return in the array. Accepts either taxonomy 'names'
     275 * @param string $output   Optional. The type of output to return in the array. Either 'names'
    276276 *                         or 'objects'. Default 'names'.
    277277 * @param string $operator Optional. The logical operation to perform. Accepts 'and' or 'or'. 'or' means only
Note: See TracChangeset for help on using the changeset viewer.