Make WordPress Core

Changeset 57644


Ignore:
Timestamp:
02/16/2024 09:45:18 PM (10 months 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.