WordPress.org

Make WordPress Core

Changeset 38121


Ignore:
Timestamp:
07/20/2016 04:56:21 PM (4 years ago)
Author:
DrewAPicture
Message:

Docs: Fix formatting, tense, verb conjugation, and other syntax for wp-includes/* elements introduced or changed in 4.6.

Part 1/2.

See #37318.

Location:
trunk/src/wp-includes
Files:
15 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/category-template.php

    r37985 r38121  
    353353 *     @type bool         $hide_if_empty     True to skip generating markup if no categories are found.
    354354 *                                           Default false (create select element even if no categories are found).
    355  *     @type bool         $required          Whether the <select> element should have the HTML5 'required' attribute.
     355 *     @type bool         $required          Whether the `<select>` element should have the HTML5 'required' attribute.
    356356 *                                           Default false.
    357357 * }
  • trunk/src/wp-includes/class-wp-comment-query.php

    r38117 r38121  
    906906
    907907    /**
    908      * Populates found_comments and max_num_pages properties for the current query if the limit clause was used.
     908     * Populates found_comments and max_num_pages properties for the current
     909     * query if the limit clause was used.
    909910     *
    910911     * @since 4.6.0
     
    922923             * @since 4.4.0
    923924             *
    924              * @param string $found_comments_query SQL query. Default 'SELECT FOUND_ROWS()'.
    925              * @param WP_Comment_Query $comment_query The `WP_Comment_Query` instance.
     925             * @param string           $found_comments_query SQL query. Default 'SELECT FOUND_ROWS()'.
     926             * @param WP_Comment_Query $comment_query        The `WP_Comment_Query` instance.
    926927             */
    927928            $found_comments_query = apply_filters( 'found_comments_query', 'SELECT FOUND_ROWS()', $this );
  • trunk/src/wp-includes/class-wp-customize-manager.php

    r38028 r38121  
    652652
    653653    /**
    654      * Return the sanitized value for a given setting from the request's POST data.
    655      *
    656      * @since 3.4.0
    657      * @since 4.1.1 Introduced `$default` parameter.
    658      * @since 4.6.0 Return `$default` when setting post value is invalid.
     654     * Returns the sanitized value for a given setting from the request's POST data.
     655     *
     656     * @since 3.4.0
     657     * @since 4.1.1 Introduced the `$default` parameter.
     658     * @since 4.6.0 `$default` is now returned early when the setting post value is invalid.
     659     * @access public
     660     *
    659661     * @see WP_REST_Server::dispatch()
    660662     * @see WP_Rest_Request::sanitize_params()
     
    988990
    989991    /**
    990      * Validate setting values.
     992     * Validates setting values.
    991993     *
    992994     * Sanitization is applied to the values before being passed for validation.
     
    996998     * @since 4.6.0
    997999     * @access public
     1000     *
    9981001     * @see WP_REST_Request::has_valid_params()
    9991002     * @see WP_Customize_Setting::validate()
     
    10271030
    10281031    /**
    1029      * Prepare setting validity for exporting to the client (JS).
     1032     * Prepares setting validity for exporting to the client (JS).
    10301033     *
    10311034     * Converts `WP_Error` instance into array suitable for passing into the
     
    10361039     *
    10371040     * @param true|WP_Error $validity Setting validity.
    1038      * @return true|array If `$validity` was `WP_Error` then array mapping the error
    1039      *                    codes to their respective `message` and `data` to pass
    1040      *                    into the `wp.customize.Notification` JS model.
     1041     * @return true|array If `$validity` was a WP_Error, the error codes will be array-mapped
     1042     *                    to their respective `message` and `data` to pass into the
     1043     *                    `wp.customize.Notification` JS model.
    10411044     */
    10421045    public function prepare_setting_validity_for_js( $validity ) {
     
    10811084         * Fires before save validation happens.
    10821085         *
    1083          * Plugins can add just-in-time `customize_validate_{$setting_id}` filters
     1086         * Plugins can add just-in-time {@see 'customize_validate_{$this->ID}'} filters
    10841087         * at this point to catch any settings registered after `customize_register`.
     1088         * The dynamic portion of the hook name, `$this->ID` referrs to the setting ID.
    10851089         *
    10861090         * @since 4.6.0
  • trunk/src/wp-includes/class-wp-customize-setting.php

    r37982 r38121  
    465465
    466466    /**
    467      * Check user capabilities and theme supports, and then save
     467     * Checks user capabilities and theme supports, and then saves
    468468     * the value of the setting.
    469469     *
    470470     * @since 3.4.0
    471471     * @since 4.6.0 Return the result of updating the value.
     472     * @access public
    472473     *
    473474     * @return false|void False if cap check fails or value isn't set or is invalid.
     
    529530
    530531    /**
    531      * Validate an input.
     532     * Validates an input.
    532533     *
    533534     * @since 4.6.0
    534535     * @access public
     536     *
    535537     * @see WP_REST_Request::has_valid_params()
    536538     *
    537539     * @param mixed $value Value to validate.
    538      * @return true|WP_Error
     540     * @return true|WP_Error True if the input was validated, otherwise WP_Error.
    539541     */
    540542    public function validate( $value ) {
     
    549551
    550552        /**
    551          * Validate a Customize setting value.
     553         * Validates a Customize setting value.
    552554         *
    553555         * Plugins should amend the `$validity` object via its `WP_Error::add()` method.
     556         *
     557         * The dynamic portion of the hook name, `$this->ID`, refers to the setting ID.
    554558         *
    555559         * @since 4.6.0
     
    696700             * Filters a Customize setting value not handled as a theme_mod or option.
    697701             *
    698              * The dynamic portion of the hook name, `$this->id_date['base']`, refers to
    699              * the base slug of the setting name.
     702             * The dynamic portion of the hook name, `$id_base`, refers to
     703             * the base slug of the setting name, initialized from `$this->id_data['base']`.
    700704             *
    701705             * For settings handled as theme_mods or options, see those corresponding
     
    703707             *
    704708             * @since 3.4.0
    705              * @since 4.6.0 Added the `$this` setting instance as the second param.
     709             * @since 4.6.0 Added the `$this` setting instance as the second parameter.
    706710             *
    707711             * @param mixed                $default The setting default value. Default empty.
     
    751755
    752756    /**
    753      * Get the data to export to the client via JSON.
     757     * Retrieves the data to export to the client via JSON.
    754758     *
    755759     * @since 4.6.0
     760     * @access public
    756761     *
    757762     * @return array Array of parameters passed to JavaScript.
  • trunk/src/wp-includes/class-wp-site.php

    r37923 r38121  
    302302
    303303    /**
    304      * Retrieve the details for this site.
     304     * Retrieves the details for this site.
    305305     *
    306306     * This method is used internally to lazy-load the extended properties of a site.
  • trunk/src/wp-includes/class-wp-theme.php

    r37946 r38121  
    13321332
    13331333    /**
    1334      * Enable a theme for all sites on the current network.
     1334     * Enables a theme for all sites on the current network.
    13351335     *
    13361336     * @since 4.6.0
    1337      *
     1337     * @access public
    13381338     * @static
    1339      * @access public
    13401339     *
    13411340     * @param string|array $stylesheets Stylesheet name or array of stylesheet names.
     
    13591358
    13601359    /**
    1361      * Disable a theme for all sites on the current network.
     1360     * Disables a theme for all sites on the current network.
    13621361     *
    13631362     * @since 4.6.0
    1364      *
     1363     * @access public
    13651364     * @static
    1366      * @access public
    13671365     *
    13681366     * @param string|array $stylesheets Stylesheet name or array of stylesheet names.
  • trunk/src/wp-includes/class-wp-widget-factory.php

    r37333 r38121  
    5454     * @since 4.6.0
    5555     * @access private
     56     * @var array
     57     *
    5658     * @see WP_Widget_Factory::hash_object()
    57      *
    58      * @var array
    5959     */
    6060    private $hashed_class_counts = array();
    6161
    6262    /**
    63      * Hash an object, doing fallback of `spl_object_hash()` if not available.
     63     * Hashes an object, doing fallback of `spl_object_hash()` if not available.
    6464     *
    6565     * This can be eliminated in favor of straight spl_object_hash() when 5.3
     
    9494     *
    9595     * @since 2.8.0
    96      * @since 4.6.0 The `$widget` param can also be an instance object of `WP_Widget` instead of just a `WP_Widget` subclass name.
     96     * @since 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object
     97     *              instead of simply a `WP_Widget` subclass name.
    9798     * @access public
    9899     *
     
    111112     *
    112113     * @since 2.8.0
    113      * @since 4.6.0 The `$widget` param can also be an instance object of `WP_Widget` instead of just a `WP_Widget` subclass name.
     114     * @since 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object
     115     *              instead of simply a `WP_Widget` subclass name.
    114116     * @access public
    115117     *
  • trunk/src/wp-includes/comment-template.php

    r38018 r38121  
    139139 *
    140140 * @since 0.71
    141  * @since 4.6.0 The `$comment` parameter was added.
     141 * @since 4.6.0 Added the `$comment` parameter.
    142142 *
    143143 * @param string         $linktext Optional. Text to display instead of the comment author's email address.
     
    163163 *
    164164 * @since 2.7.0
    165  * @since 4.6.0 The `$comment` parameter was added.
     165 * @since 4.6.0 Added the `$comment` parameter.
    166166 *
    167167 * @param string         $linktext Optional. Text to display instead of the comment author's email address.
     
    359359 *
    360360 * @since 1.5.0
    361  * @since 4.6.0 The `$comment` parameter was added.
     361 * @since 4.6.0 Added the `$comment` parameter.
    362362 *
    363363 * @param string         $linktext Optional. The text to display instead of the comment
     
    397397 *
    398398 * @since 0.71
    399  * @since 4.6.0 The `$comment` parameter was added.
     399 * @since 4.6.0 Added the `$comment` parameter.
    400400 *
    401401 * @param string         $linktext Optional. Text to display instead of the comment author's
  • trunk/src/wp-includes/comment.php

    r38098 r38121  
    20362036     *
    20372037     * @since 1.2.0
    2038      * @since 4.6.0 The `$data` parameter was added.
     2038     * @since 4.6.0 Added the `$data` parameter.
    20392039     *
    20402040     * @param int   $comment_ID The comment ID.
  • trunk/src/wp-includes/compat.php

    r37750 r38121  
    518518
    519519    /**
    520      * Register a function to be autoloaded.
     520     * Registers a function to be autoloaded.
    521521     *
    522522     * @since 4.6.0
    523523     *
    524524     * @param callable $autoload_function The function to register.
    525      * @param boolean $throw Should the function throw an exception if the function isn't callable?
    526      * @param boolean $prepend Should we prepend the function to the stack?
     525     * @param bool     $throw             Optional. Whether the function should throw an exception
     526     *                                    if the function isn't callable. Default true.
     527     * @param bool     $prepend           Whether the function should be prepended to the stack.
     528     *                                    Default false.
    527529     */
    528530    function spl_autoload_register( $autoload_function, $throw = true, $prepend = false ) {
     
    547549
    548550    /**
    549      * Unregister an autoloader function.
     551     * Unregisters an autoloader function.
    550552     *
    551553     * @since 4.6.0
    552554     *
    553555     * @param callable $function The function to unregister.
    554      * @return boolean True if the function was unregistered, false if it could not be.
     556     * @return bool True if the function was unregistered, false if it could not be.
    555557     */
    556558    function spl_autoload_unregister( $function ) {
     
    567569
    568570    /**
    569      * Get the registered autoloader functions.
     571     * Retrieves the registered autoloader functions.
    570572     *
    571573     * @since 4.6.0
  • trunk/src/wp-includes/formatting.php

    r38087 r38121  
    14921492 *
    14931493 * @since 1.2.1
    1494  * @since 4.6.0 Locale support was added for `de_CH`, `de_CH_informal`, and `ca`.
     1494 * @since 4.6.0 Added locale support for `de_CH`, `de_CH_informal`, and `ca`.
    14951495 *
    14961496 * @param string $string Text that might have accent characters
     
    49234923
    49244924/**
    4925  * Print inline Emoji dection script
     4925 * Prints inline Emoji dection script
    49264926 *
    49274927 * @ignore
     
    49294929 * @access private
    49304930 *
    4931  * @global string $wp_version
     4931 * @global string $wp_version WordPress version string.
    49324932 */
    49334933function _print_emoji_detection_script() {
  • trunk/src/wp-includes/functions.php

    r38095 r38121  
    24392439
    24402440/**
    2441  * Retrieve list of common file extensions and their types.
     2441 * Retrieves the list of common file extensions and their types.
    24422442 *
    24432443 * @since 4.6.0
     
    31193119
    31203120/**
    3121  * Check that a JSONP callback is a valid JavaScript callback.
     3121 * Checks that a JSONP callback is a valid JavaScript callback.
    31223122 *
    31233123 * Only allows alphanumeric characters and the dot character in callback
     
    39033903 * Marks a deprecated action or filter hook as deprecated and throws a notice.
    39043904 *
    3905  * Use the 'deprecated_hook_run' action to get the backtrace describing where the
    3906  * deprecated hook was called.
    3907  *
    3908  * Default behavior is to trigger a user error if WP_DEBUG is true.
     3905 * Use the {@see 'deprecated_hook_run'} action to get the backtrace describing where
     3906 * the deprecated hook was called.
     3907 *
     3908 * Default behavior is to trigger a user error if `WP_DEBUG` is true.
    39093909 *
    39103910 * This function is called by the do_action_deprecated() and apply_filters_deprecated()
     
    39333933
    39343934    /**
    3935      * Filter whether to trigger deprecated hook errors.
     3935     * Filters whether to trigger deprecated hook errors.
    39363936     *
    39373937     * @since 4.6.0
     
    53655365 * @since 4.6.0
    53665366 *
    5367  * @param string $context  Context in which the function is called.
    5368  *                         Either 'admin', 'image' or an arbitrary other context.
    5369  *                         Defaults to 'admin'.
    5370  *                         If an arbitrary context is passed, the similarly arbitrary
    5371  *                         "{$context}_memory_limit" filter will be invoked.
     5367 * @param string $context Optional. Context in which the function is called. Accepts either 'admin',
     5368 *                        'image', or an arbitrary other context. If an arbitrary context is passed,
     5369 *                        the similarly arbitrary {@see '{$context}_memory_limit'} filter will be
     5370 *                        invoked. Default 'admin'.
    53725371 * @return bool|int|string The limit that was set or false on failure.
    53735372 */
     
    53945393             * Filters the maximum memory limit available for administration screens.
    53955394             *
    5396              * This only applies to administrators, who may require more memory for tasks like updates.
    5397              * Memory limits when processing images (uploaded or edited by users of any role) are
    5398              * handled separately.
     5395             * This only applies to administrators, who may require more memory for tasks
     5396             * like updates. Memory limits when processing images (uploaded or edited by
     5397             * users of any role) are handled separately.
    53995398             *
    5400              * The WP_MAX_MEMORY_LIMIT constant specifically defines the maximum memory limit available
    5401              * when in the administration back end. The default is 256M (256 megabytes
    5402              * of memory) or the original `memory_limit` php.ini value if this is higher.
     5399             * The `WP_MAX_MEMORY_LIMIT` constant specifically defines the maximum memory
     5400             * limit available when in the administration back end. The default is 256M
     5401             * (256 megabytes of memory) or the original `memory_limit` php.ini value if
     5402             * this is higher.
    54035403             *
    54045404             * @since 3.0.0
    5405              * @since 4.6.0 The default takes the original `memory_limit` into account.
     5405             * @since 4.6.0 The default now takes the original `memory_limit` into account.
    54065406             *
    5407              * @param int|string $filtered_limit The maximum WordPress memory limit.
    5408              *                                   Accepts an integer (bytes), or a shorthand string
    5409              *                                   notation, such as '256M'.
     5407             * @param int|string $filtered_limit The maximum WordPress memory limit. Accepts an integer
     5408             *                                   (bytes), or a shorthand string notation, such as '256M'.
    54105409             */
    54115410            $filtered_limit = apply_filters( 'admin_memory_limit', $filtered_limit );
     
    54175416             *
    54185417             * @since 3.5.0
    5419              * @since 4.6.0 The default takes the original `memory_limit` into account.
     5418             * @since 4.6.0 The default now takes the original `memory_limit` into account.
    54205419             *
    54215420             * @param int|string $filtered_limit Maximum memory limit to allocate for images.
    5422              *                                   Default WP_MAX_MEMORY_LIMIT or the original
    5423              *                                   php.ini memory_limit, whichever is higher.
     5421             *                                   Default `WP_MAX_MEMORY_LIMIT` or the original
     5422             *                                   php.ini `memory_limit`, whichever is higher.
    54245423             *                                   Accepts an integer (bytes), or a shorthand string
    54255424             *                                   notation, such as '256M'.
     
    54395438             *
    54405439             * @param int|string $filtered_limit Maximum memory limit to allocate for images.
    5441              *                                   Default 256M or the original php.ini memory_limit,
    5442              *                                   whichever is higher.
    5443              *                                   Accepts an integer (bytes), or a shorthand string
    5444              *                                   notation, such as '256M'.
     5440             *                                   Default '256M' or the original php.ini `memory_limit`,
     5441             *                                   whichever is higher. Accepts an integer (bytes), or a
     5442             *                                   shorthand string notation, such as '256M'.
    54455443             */
    54465444            $filtered_limit = apply_filters( "{$context}_memory_limit", $filtered_limit );
  • trunk/src/wp-includes/general-template.php

    r38100 r38121  
    22562256 *
    22572257 * @since 2.1.0
    2258  * @since 4.6.0 The `$post` parameter was added.
     2258 * @since 4.6.0 Added the `$post` parameter.
    22592259 *
    22602260 * @param string      $d    Optional. PHP date format defaults to the date_format option if not specified.
     
    22782278     *
    22792279     * @since 2.1.0
    2280      * @since 4.6.0 The `$post` parameter was added.
     2280     * @since 4.6.0 Added the `$post` parameter.
    22812281     *
    22822282     * @param string  $the_time The formatted date.
     
    24092409 *
    24102410 * @since 2.0.0
    2411  * @since 4.6.0 The `$post` parameter was added.
     2411 * @since 4.6.0 Added the `$post` parameter.
    24122412 *
    24132413 * @param string      $d     Optional. Format to use for retrieving the time the post
     
    24332433     *
    24342434     * @since 2.0.0
    2435      * @since 4.6.0 The `$post` parameter was added.
     2435     * @since 4.6.0 Added the `$post` parameter.
    24362436     *
    24372437     * @param string $the_time The formatted time.
     
    27892789
    27902790/**
    2791  * Prints resource hints to browsers for pre-fetching, pre-rendering and pre-connecting to web sites.
    2792  *
    2793  * Gives hints to browsers to prefetch specific pages or render them in the background,
    2794  * to perform DNS lookups or to begin the connection handshake (DNS, TCP, TLS) in the background.
     2791 * Prints resource hints to browsers for pre-fetching, pre-rendering
     2792 * and pre-connecting to web sites.
     2793 *
     2794 * Gives hints to browsers to prefetch specific pages or render them
     2795 * in the background, to perform DNS lookups or to begin the connection
     2796 * handshake (DNS, TCP, TLS) in the background.
    27952797 *
    27962798 * These performance improving indicators work by using `<link rel"…">`.
     
    28522854
    28532855/**
    2854  * Returns a list of unique hosts of all enqueued scripts and styles.
     2856 * Retrieves a list of unique hosts of all enqueued scripts and styles.
    28552857 *
    28562858 * @since 4.6.0
  • trunk/src/wp-includes/kses.php

    r37931 r38121  
    17091709     *
    17101710     * @since 2.8.1
    1711      * @since 4.4.0 `min-height`, `max-height`, `min-width`, and `max-width` were added.
    1712      * @since 4.6.0 `list-style-type` was added.
     1711     * @since 4.4.0 Added support for `min-height`, `max-height`, `min-width`, and `max-width`.
     1712     * @since 4.6.0 Added support for `list-style-type`.
    17131713     *
    17141714     * @param array $attr List of allowed CSS attributes.
  • trunk/src/wp-includes/l10n.php

    r37985 r38121  
    665665
    666666/**
    667  * Load a plugin's translated strings.
     667 * Loads a plugin's translated strings.
    668668 *
    669669 * If the path is not given then it will be the root of the plugin directory.
     
    675675 *
    676676 * @param string $domain          Unique identifier for retrieving translated strings
    677  * @param string $deprecated      Use the $plugin_rel_path parameter instead.
     677 * @param string $deprecated      Optional. Use the $plugin_rel_path parameter instead. Defaukt false.
    678678 * @param string $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR where the .mo file resides.
    679679 *                                Default false.
     
    717717 *
    718718 * @param string $domain             Text domain. Unique identifier for retrieving translated strings.
    719  * @param string $mu_plugin_rel_path Relative to WPMU_PLUGIN_DIR directory in which the .mo file resides.
    720  *                                   Default empty string.
     719 * @param string $mu_plugin_rel_path Optional. Relative to `WPMU_PLUGIN_DIR` directory in which the .mo
     720 *                                   file resides. Default empty string.
    721721 * @return bool True when textdomain is successfully loaded, false otherwise.
    722722 */
     
    800800
    801801/**
    802  * Just in time loading of plugin and theme textdomains.
    803  *
    804  * When a textdomain is encountered for the first time, we try to load the translation file
    805  * from wp-content/languages, removing the need to call `load_plugin_texdomain()` or
    806  * `load_theme_texdomain()`. Holds a cached list of available .mo files to improve performance.
     802 * Loads plugin and theme textdomains just-in-time.
     803 *
     804 * When a textdomain is encountered for the first time, we try to load
     805 * the translation file from `wp-content/languages`, removing the need
     806 * to call load_plugin_texdomain() or load_theme_texdomain().
     807 *
     808 * Holds a cached list of available .mo files to improve performance.
    807809 *
    808810 * @since 4.6.0
Note: See TracChangeset for help on using the changeset viewer.