Make WordPress Core

Changeset 48576


Ignore:
Timestamp:
07/23/2020 07:37:57 AM (4 years ago)
Author:
johnbillion
Message:

Docs: Further corrections and improvements to various inline docblocks.

See #49572

Location:
trunk
Files:
18 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/class-wp-site-health.php

    r48560 r48576  
    160160         *     An associative array of test result data.
    161161         *
    162          *     @param string $label       A label describing the test, and is used as a header in the output.
    163          *     @param string $status      The status of the test, which can be a value of `good`, `recommended` or `critical`.
    164          *     @param array  $badge {
     162         *     @type string $label       A label describing the test, and is used as a header in the output.
     163         *     @type string $status      The status of the test, which can be a value of `good`, `recommended` or `critical`.
     164         *     @type array  $badge {
    165165         *         Tests are put into categories which have an associated badge shown, these can be modified and assigned here.
    166166         *
    167          *         @param string $label The test label, for example `Performance`.
    168          *         @param string $color Default `blue`. A string representing a color to use for the label.
     167         *         @type string $label The test label, for example `Performance`.
     168         *         @type string $color Default `blue`. A string representing a color to use for the label.
    169169         *     }
    170          *     @param string $description A more descriptive explanation of what the test looks for, and why it is important for the end user.
    171          *     @param string $actions     An action to direct the user to where they can resolve the issue, if one exists.
    172          *     @param string $test        The name of the test being ran, used as a reference point.
     170         *     @type string $description A more descriptive explanation of what the test looks for, and why it is important for the end user.
     171         *     @type string $actions     An action to direct the user to where they can resolve the issue, if one exists.
     172         *     @type string $test        The name of the test being ran, used as a reference point.
    173173         * }
    174174         */
     
    954954         *
    955955         * @param array $modules {
    956          *     An associated array of modules to test for.
     956         *     An associative array of modules to test for.
    957957         *
    958          *     array $module {
    959          *         An associated array of module properties used during testing.
     958         *     @type array ...$0 {
     959         *         An associative array of module properties used during testing.
    960960         *         One of either `$function` or `$extension` must be provided, or they will fail by default.
    961961         *
    962          *         string $function     Optional. A function name to test for the existence of.
    963          *         string $extension    Optional. An extension to check if is loaded in PHP.
    964          *         string $constant     Optional. A constant name to check for to verify an extension exists.
    965          *         string $class        Optional. A class name to check for to verify an extension exists.
    966          *         bool   $required     Is this a required feature or not.
    967          *         string $fallback_for Optional. The module this module replaces as a fallback.
     962         *         @type string $function     Optional. A function name to test for the existence of.
     963         *         @type string $extension    Optional. An extension to check if is loaded in PHP.
     964         *         @type string $constant     Optional. A constant name to check for to verify an extension exists.
     965         *         @type string $class        Optional. A class name to check for to verify an extension exists.
     966         *         @type bool   $required     Is this a required feature or not.
     967         *         @type string $fallback_for Optional. The module this module replaces as a fallback.
    968968         *     }
    969969         * }
     
    23432343     */
    23442344    function detect_plugin_theme_auto_update_issues() {
     2345        /** This filter is documented in wp-admin/includes/class-wp-automatic-updater.php */
    23452346        $test_plugins_enabled   = apply_filters( 'auto_update_plugin', true );
     2347        /** This filter is documented in wp-admin/includes/class-wp-automatic-updater.php */
    23462348        $test_themes_enabled    = apply_filters( 'auto_update_theme', true );
    23472349        $ui_enabled_for_plugins = wp_is_auto_update_enabled_for_type( 'plugin' );
  • trunk/src/wp-admin/includes/comment.php

    r48223 r48576  
    2222 * @param string $comment_date   Date of the comment.
    2323 * @param string $timezone       Timezone. Accepts 'blog' or 'gmt'. Default 'blog'.
    24  * @return mixed Comment post ID on success.
     24 * @return string|null Comment post ID on success.
    2525 */
    2626function comment_exists( $comment_author, $comment_date, $timezone = 'blog' ) {
  • trunk/src/wp-admin/includes/template.php

    r48574 r48576  
    15431543 * @since 2.7.0
    15441544 *
    1545  * @global $wp_settings_sections Storage array of all settings sections added to admin pages.
     1545 * @global array $wp_settings_sections Storage array of all settings sections added to admin pages.
    15461546 *
    15471547 * @param string   $id       Slug-name to identify the section. Used in the 'id' attribute of tags.
     
    16021602 * @since 4.2.0 The `$class` argument was added.
    16031603 *
    1604  * @global $wp_settings_fields Storage array of settings fields and info about their pages/sections.
     1604 * @global array $wp_settings_fields Storage array of settings fields and info about their pages/sections.
    16051605 *
    16061606 * @param string   $id       Slug-name to identify the field. Used in the 'id' attribute of tags.
     
    16671667 * add_settings_section() and add_settings_field()
    16681668 *
    1669  * @global $wp_settings_sections Storage array of all settings sections added to admin pages.
    1670  * @global $wp_settings_fields Storage array of settings fields and info about their pages/sections.
     1669 * @global array $wp_settings_sections Storage array of all settings sections added to admin pages.
     1670 * @global array $wp_settings_fields Storage array of settings fields and info about their pages/sections.
    16711671 * @since 2.7.0
    16721672 *
     
    17051705 * rather than directly.
    17061706 *
    1707  * @global $wp_settings_fields Storage array of settings fields and their pages/sections.
     1707 * @global array $wp_settings_fields Storage array of settings fields and their pages/sections.
    17081708 *
    17091709 * @since 2.7.0
  • trunk/src/wp-includes/author-template.php

    r48200 r48576  
    1616 * @since 1.5.0
    1717 *
    18  * @global object $authordata The current author's DB object.
     18 * @global WP_User $authordata The current author's data.
    1919 *
    2020 * @param string $deprecated Deprecated.
     
    3333     * @since 2.9.0
    3434     *
    35      * @param string $authordata->display_name The author's display name.
     35     * @param string|null $display_name The author's display name.
    3636     */
    3737    return apply_filters( 'the_author', is_object( $authordata ) ? $authordata->display_name : null );
     
    100100         * @since 2.8.0
    101101         *
    102          * @param string $last_user->display_name The author's display name.
     102         * @param string $display_name The author's display name.
    103103         */
    104104        return apply_filters( 'the_modified_author', $last_user->display_name );
     
    153153 * @since 2.8.0
    154154 *
    155  * @global object $authordata The current author's DB object.
     155 * @global WP_User $authordata The current author's data.
    156156 *
    157157 * @param string    $field   Optional. The user field to retrieve. Default empty.
     
    288288 * @since 4.4.0
    289289 *
    290  * @global object $authordata The current author's DB object.
     290 * @global WP_User $authordata The current author's data.
    291291 *
    292292 * @return string An HTML link to the author page, or an empty string if $authordata isn't defined.
  • trunk/src/wp-includes/class-wp-comment-query.php

    r48275 r48576  
    2929     *
    3030     * @since 3.5.0
    31      * @var object WP_Meta_Query
     31     * @var WP_Meta_Query A meta query instance.
    3232     */
    3333    public $meta_query = false;
     
    7070     *
    7171     * @since 3.7.0
    72      * @var object WP_Date_Query
     72     * @var WP_Date_Query A date query instance.
    7373     */
    7474    public $date_query = false;
  • trunk/src/wp-includes/class-wp-customize-manager.php

    r48573 r48576  
    46904690     *     Mapping of 'panel', 'section', 'control' to the ID which should be autofocused.
    46914691     *
    4692      *     @type string [$control] ID for control to be autofocused.
    4693      *     @type string [$section] ID for section to be autofocused.
    4694      *     @type string [$panel]    ID for panel to be autofocused.
     4692     *     @type string $control ID for control to be autofocused.
     4693     *     @type string $section ID for section to be autofocused.
     4694     *     @type string $panel   ID for panel to be autofocused.
    46954695     * }
    46964696     */
     
    47074707     *     Mapping of 'panel', 'section', 'control' to the ID which should be autofocused.
    47084708     *
    4709      *     @type string [$control] ID for control to be autofocused.
    4710      *     @type string [$section] ID for section to be autofocused.
    4711      *     @type string [$panel]    ID for panel to be autofocused.
     4709     *     @type string $control ID for control to be autofocused.
     4710     *     @type string $section ID for section to be autofocused.
     4711     *     @type string $panel   ID for panel to be autofocused.
    47124712     * }
    47134713     */
  • trunk/src/wp-includes/class-wp-customize-widgets.php

    r48299 r48576  
    566566     * @since 3.9.0
    567567     *
    568      * @global $wp_registered_widget_controls
     568     * @global array $wp_registered_widget_controls
    569569     *
    570570     * @param string $widget_id Widget ID.
  • trunk/src/wp-includes/class-wp-http-cookie.php

    r47808 r48576  
    245245     *
    246246     * @return array {
    247      *    List of attributes.
    248      *
    249      *    @type string|int|null $expires When the cookie expires. Unix timestamp or formatted date.
    250      *    @type string          $path    Cookie URL path.
    251      *    @type string          $domain  Cookie domain.
     247     *     List of attributes.
     248     *
     249     *     @type string|int|null $expires When the cookie expires. Unix timestamp or formatted date.
     250     *     @type string          $path    Cookie URL path.
     251     *     @type string          $domain  Cookie domain.
    252252     * }
    253253     */
  • trunk/src/wp-includes/class-wp-image-editor-gd.php

    r48110 r48576  
    454454        chmod( $filename, $perms );
    455455
    456         /**
    457          * Filters the name of the saved image file.
    458          *
    459          * @since 2.6.0
    460          *
    461          * @param string $filename Name of the file.
    462          */
    463456        return array(
    464457            'path'      => $filename,
     458            /**
     459             * Filters the name of the saved image file.
     460             *
     461             * @since 2.6.0
     462             *
     463             * @param string $filename Name of the file.
     464             */
    465465            'file'      => wp_basename( apply_filters( 'image_make_intermediate_size', $filename ) ),
    466466            'width'     => $this->size['width'],
  • trunk/src/wp-includes/class-wp-query.php

    r48563 r48576  
    3838     *
    3939     * @since 3.1.0
    40      * @var object WP_Tax_Query
     40     * @var WP_Tax_Query A taxonomy query instance.
    4141     */
    4242    public $tax_query;
     
    4646     *
    4747     * @since 3.2.0
    48      * @var object WP_Meta_Query
     48     * @var WP_Meta_Query A meta query instance.
    4949     */
    5050    public $meta_query = false;
     
    5454     *
    5555     * @since 3.7.0
    56      * @var object WP_Date_Query
     56     * @var WP_Date_Query A date query instance.
    5757     */
    5858    public $date_query = false;
  • trunk/src/wp-includes/class-wp-site-query.php

    r48104 r48576  
    6060     *
    6161     * @since 4.6.0
    62      * @var object WP_Date_Query
     62     * @var WP_Date_Query A date query instance.
    6363     */
    6464    public $date_query = false;
  • trunk/src/wp-includes/class-wp-term-query.php

    r48562 r48576  
    3030     *
    3131     * @since 4.6.0
    32      * @var object WP_Meta_Query
     32     * @var WP_Meta_Query A meta query instance.
    3333     */
    3434    public $meta_query = false;
  • trunk/src/wp-includes/class-wp-text-diff-renderer-table.php

    r47550 r48576  
    338338     * @param array $final Lines of the final version of the text.
    339339     * @return array {
    340      *    Array containing results of comparing the original text to the final text.
    341      *
    342      *    @type array $orig_matches  Associative array of original matches. Index == row
    343      *                               number of `$orig`, value == corresponding row number
    344      *                               of that same line in `$final` or 'x' if there is no
    345      *                               corresponding row (indicating it is a deleted line).
    346      *    @type array $final_matches Associative array of final matches. Index == row
    347      *                               number of `$final`, value == corresponding row number
    348      *                               of that same line in `$orig` or 'x' if there is no
    349      *                               corresponding row (indicating it is a new line).
    350      *    @type array $orig_rows     Associative array of interleaved rows of `$orig` with
    351      *                               blanks to keep matches aligned with side-by-side diff
    352      *                               of `$final`. A value >= 0 corresponds to index of `$orig`.
    353      *                               Value < 0 indicates a blank row.
    354      *    @type array $final_rows    Associative array of interleaved rows of `$final` with
    355      *                               blanks to keep matches aligned with side-by-side diff
    356      *                               of `$orig`. A value >= 0 corresponds to index of `$final`.
    357      *                               Value < 0 indicates a blank row.
     340     *     Array containing results of comparing the original text to the final text.
     341     *
     342     *     @type array $orig_matches  Associative array of original matches. Index == row
     343     *                                number of `$orig`, value == corresponding row number
     344     *                                of that same line in `$final` or 'x' if there is no
     345     *                                corresponding row (indicating it is a deleted line).
     346     *     @type array $final_matches Associative array of final matches. Index == row
     347     *                                number of `$final`, value == corresponding row number
     348     *                                of that same line in `$orig` or 'x' if there is no
     349     *                                corresponding row (indicating it is a new line).
     350     *     @type array $orig_rows     Associative array of interleaved rows of `$orig` with
     351     *                                blanks to keep matches aligned with side-by-side diff
     352     *                                of `$final`. A value >= 0 corresponds to index of `$orig`.
     353     *                                Value < 0 indicates a blank row.
     354     *     @type array $final_rows    Associative array of interleaved rows of `$final` with
     355     *                                blanks to keep matches aligned with side-by-side diff
     356     *                                of `$orig`. A value >= 0 corresponds to index of `$final`.
     357     *                                Value < 0 indicates a blank row.
    358358     * }
    359359     */
  • trunk/src/wp-includes/comment.php

    r48575 r48576  
    10061006 * @global WP_Query $wp_query WordPress Query object.
    10071007 *
    1008  * @param WP_Comment[] $comments Optional. Array of WP_Comment objects. Defaults to $wp_query->comments.
     1008 * @param WP_Comment[] $comments Optional. Array of WP_Comment objects. Defaults to `$wp_query->comments`.
    10091009 * @param int          $per_page Optional. Comments per page.
    10101010 * @param bool         $threaded Optional. Control over flat or threaded comments.
  • trunk/src/wp-includes/rest-api/class-wp-rest-server.php

    r48452 r48576  
    493493     *     Data with sub-requests embedded.
    494494     *
    495      *     @type array [$_links]    Links.
    496      *     @type array [$_embedded] Embeddeds.
     495     *     @type array $_links    Links.
     496     *     @type array $_embedded Embeddeds.
    497497     * }
    498498     */
     
    617617     *     Data with sub-requests embedded.
    618618     *
    619      *     @type array [$_links]    Links.
    620      *     @type array [$_embedded] Embeddeds.
     619     *     @type array $_links    Links.
     620     *     @type array $_embedded Embeddeds.
    621621     * }
    622622     */
  • trunk/src/wp-includes/theme.php

    r48573 r48576  
    30203020 * @see add_theme_support()
    30213021 *
    3022  * @global $_wp_registered_theme_features
     3022 * @global array $_wp_registered_theme_features
    30233023 *
    30243024 * @param string $feature The name uniquely identifying the feature. See add_theme_support()
     
    31573157 * @since 5.5.0
    31583158 *
    3159  * @global $_wp_registered_theme_features
     3159 * @global array $_wp_registered_theme_features
    31603160 *
    31613161 * @return array[] List of theme features, keyed by their name.
     
    31763176 * @since 5.5.0
    31773177 *
    3178  * @global $_wp_registered_theme_features
     3178 * @global array $_wp_registered_theme_features
    31793179 *
    31803180 * @param string $feature The feature name. See add_theme_support() for the list
  • trunk/tests/phpunit/tests/admin/includesCommunityEvents.php

    r47198 r48576  
    153153
    154154    /**
    155      * Test: With a valid response, get_events() should return an associated array containing a location array and
     155     * Test: With a valid response, get_events() should return an associative array containing a location array and
    156156     * an events array with individual events that have formatted time and date.
    157157     *
  • trunk/tests/phpunit/tests/formatting/EscXml.php

    r48072 r48576  
    2222     *
    2323     * @return array {
    24      *    @type string $source   The source string to be escaped.
    25      *    @type string $expected The expected escaped value of `$source`.
     24     *     @type string $source   The source string to be escaped.
     25     *     @type string $expected The expected escaped value of `$source`.
    2626     * }
    2727     */
     
    9292     *
    9393     * @return array {
    94      *    @type string $source   The source string to be escaped.
    95      *    @type string $expected The expected escaped value of `$source`.
     94     *     @type string $source   The source string to be escaped.
     95     *     @type string $expected The expected escaped value of `$source`.
    9696     * }
    9797     */
Note: See TracChangeset for help on using the changeset viewer.