Upstream
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

Part 1/2.

See #37318.

Built from https://develop.svn.wordpress.org/trunk@38121


git-svn-id: http://core.svn.wordpress.org/trunk@38062 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Drew Jaynes 2016-07-20 16:57:32 +00:00
parent 1ce9a3d800
commit 6cc13f0c54
16 changed files with 108 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
wp-includes/category-template.php
View File

@ -352,7 +352,7 @@ function category_description( $category = 0 ) {
* @type string|array $taxonomy Name of the category or categories to retrieve. Default 'category'.
* @type bool $hide_if_empty True to skip generating markup if no categories are found.
* Default false (create select element even if no categories are found).
* @type bool $required Whether the <select> element should have the HTML5 'required' attribute.
* @type bool $required Whether the `<select>` element should have the HTML5 'required' attribute.
* Default false.
* }
* @return string HTML content only if 'echo' argument is 0.

7
wp-includes/class-wp-comment-query.php
View File

@ -905,7 +905,8 @@ class WP_Comment_Query {
}
/**
* Populates found_comments and max_num_pages properties for the current query if the limit clause was used.
* Populates found_comments and max_num_pages properties for the current
* query if the limit clause was used.
*
* @since 4.6.0
* @access private
@ -921,8 +922,8 @@ class WP_Comment_Query {
*
* @since 4.4.0
*
* @param string $found_comments_query SQL query. Default 'SELECT FOUND_ROWS()'.
* @param WP_Comment_Query $comment_query The `WP_Comment_Query` instance.
* @param string $found_comments_query SQL query. Default 'SELECT FOUND_ROWS()'.
* @param WP_Comment_Query $comment_query The `WP_Comment_Query` instance.
*/
$found_comments_query = apply_filters( 'found_comments_query', 'SELECT FOUND_ROWS()', $this );

22
wp-includes/class-wp-customize-manager.php
View File

@ -651,11 +651,13 @@ final class WP_Customize_Manager {
}
/**
* Return the sanitized value for a given setting from the request's POST data.
* Returns the sanitized value for a given setting from the request's POST data.
*
* @since 3.4.0
* @since 4.1.1 Introduced `$default` parameter.
* @since 4.6.0 Return `$default` when setting post value is invalid.
* @since 4.1.1 Introduced the `$default` parameter.
* @since 4.6.0 `$default` is now returned early when the setting post value is invalid.
* @access public
*
* @see WP_REST_Server::dispatch()
* @see WP_Rest_Request::sanitize_params()
* @see WP_Rest_Request::has_valid_params()
@ -987,7 +989,7 @@ final class WP_Customize_Manager {
}
/**
* Validate setting values.
* Validates setting values.
*
* Sanitization is applied to the values before being passed for validation.
* Validation is skipped for unregistered settings or for values that are
@ -995,6 +997,7 @@ final class WP_Customize_Manager {
*
* @since 4.6.0
* @access public
*
* @see WP_REST_Request::has_valid_params()
* @see WP_Customize_Setting::validate()
*
@ -1026,7 +1029,7 @@ final class WP_Customize_Manager {
}
/**
* Prepare setting validity for exporting to the client (JS).
* Prepares setting validity for exporting to the client (JS).
*
* Converts `WP_Error` instance into array suitable for passing into the
* `wp.customize.Notification` JS model.
@ -1035,9 +1038,9 @@ final class WP_Customize_Manager {
* @access public
*
* @param true|WP_Error $validity Setting validity.
* @return true|array If `$validity` was `WP_Error` then array mapping the error
* codes to their respective `message` and `data` to pass
* into the `wp.customize.Notification` JS model.
* @return true|array If `$validity` was a WP_Error, the error codes will be array-mapped
* to their respective `message` and `data` to pass into the
* `wp.customize.Notification` JS model.
*/
public function prepare_setting_validity_for_js( $validity ) {
if ( is_wp_error( $validity ) ) {
@ -1080,8 +1083,9 @@ final class WP_Customize_Manager {
/**
* Fires before save validation happens.
*
* Plugins can add just-in-time `customize_validate_{$setting_id}` filters
* Plugins can add just-in-time {@see 'customize_validate_{$this->ID}'} filters
* at this point to catch any settings registered after `customize_register`.
* The dynamic portion of the hook name, `$this->ID` referrs to the setting ID.
*
* @since 4.6.0
*

21
wp-includes/class-wp-customize-setting.php
View File

@ -464,11 +464,12 @@ class WP_Customize_Setting {
}
/**
* Check user capabilities and theme supports, and then save
* Checks user capabilities and theme supports, and then saves
* the value of the setting.
*
* @since 3.4.0
* @since 4.6.0 Return the result of updating the value.
* @access public
*
* @return false|void False if cap check fails or value isn't set or is invalid.
*/
@ -528,14 +529,15 @@ class WP_Customize_Setting {
}
/**
* Validate an input.
* Validates an input.
*
* @since 4.6.0
* @access public
*
* @see WP_REST_Request::has_valid_params()
*
* @param mixed $value Value to validate.
* @return true|WP_Error
* @return true|WP_Error True if the input was validated, otherwise WP_Error.
*/
public function validate( $value ) {
if ( is_wp_error( $value ) ) {
@ -548,10 +550,12 @@ class WP_Customize_Setting {
$validity = new WP_Error();
/**
* Validate a Customize setting value.
* Validates a Customize setting value.
*
* Plugins should amend the `$validity` object via its `WP_Error::add()` method.
*
* The dynamic portion of the hook name, `$this->ID`, refers to the setting ID.
*
* @since 4.6.0
*
* @param WP_Error $validity Filtered from `true` to `WP_Error` when invalid.
@ -695,14 +699,14 @@ class WP_Customize_Setting {
/**
* Filters a Customize setting value not handled as a theme_mod or option.
*
* The dynamic portion of the hook name, `$this->id_date['base']`, refers to
* the base slug of the setting name.
* The dynamic portion of the hook name, `$id_base`, refers to
* the base slug of the setting name, initialized from `$this->id_data['base']`.
*
* For settings handled as theme_mods or options, see those corresponding
* functions for available hooks.
*
* @since 3.4.0
* @since 4.6.0 Added the `$this` setting instance as the second param.
* @since 4.6.0 Added the `$this` setting instance as the second parameter.
*
* @param mixed $default The setting default value. Default empty.
* @param WP_Customize_Setting $this The setting instance.
@ -750,9 +754,10 @@ class WP_Customize_Setting {
}
/**
* Get the data to export to the client via JSON.
* Retrieves the data to export to the client via JSON.
*
* @since 4.6.0
* @access public
*
* @return array Array of parameters passed to JavaScript.
*/

2
wp-includes/class-wp-site.php
View File

@ -301,7 +301,7 @@ final class WP_Site {
}
/**
* Retrieve the details for this site.
* Retrieves the details for this site.
*
* This method is used internally to lazy-load the extended properties of a site.
*

10
wp-includes/class-wp-theme.php
View File

@ -1331,12 +1331,11 @@ final class WP_Theme implements ArrayAccess {
}
/**
* Enable a theme for all sites on the current network.
* Enables a theme for all sites on the current network.
*
* @since 4.6.0
*
* @static
* @access public
* @static
*
* @param string|array $stylesheets Stylesheet name or array of stylesheet names.
*/
@ -1358,12 +1357,11 @@ final class WP_Theme implements ArrayAccess {
}
/**
* Disable a theme for all sites on the current network.
* Disables a theme for all sites on the current network.
*
* @since 4.6.0
*
* @static
* @access public
* @static
*
* @param string|array $stylesheets Stylesheet name or array of stylesheet names.
*/

12
wp-includes/class-wp-widget-factory.php
View File

@ -53,14 +53,14 @@ class WP_Widget_Factory {
*
* @since 4.6.0
* @access private
* @see WP_Widget_Factory::hash_object()
*
* @var array
*
* @see WP_Widget_Factory::hash_object()
*/
private $hashed_class_counts = array();
/**
* Hash an object, doing fallback of `spl_object_hash()` if not available.
* Hashes an object, doing fallback of `spl_object_hash()` if not available.
*
* This can be eliminated in favor of straight spl_object_hash() when 5.3
* is the minimum requirement for PHP.
@ -93,7 +93,8 @@ class WP_Widget_Factory {
* Registers a widget subclass.
*
* @since 2.8.0
* @since 4.6.0 The `$widget` param can also be an instance object of `WP_Widget` instead of just a `WP_Widget` subclass name.
* @since 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object
* instead of simply a `WP_Widget` subclass name.
* @access public
*
* @param string|WP_Widget $widget Either the name of a `WP_Widget` subclass or an instance of a `WP_Widget` subclass.
@ -110,7 +111,8 @@ class WP_Widget_Factory {
* Un-registers a widget subclass.
*
* @since 2.8.0
* @since 4.6.0 The `$widget` param can also be an instance object of `WP_Widget` instead of just a `WP_Widget` subclass name.
* @since 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object
* instead of simply a `WP_Widget` subclass name.
* @access public
*
* @param string|WP_Widget $widget Either the name of a `WP_Widget` subclass or an instance of a `WP_Widget` subclass.

8
wp-includes/comment-template.php
View File

@ -138,7 +138,7 @@ function comment_author_email( $comment_ID = 0 ) {
* address and use it for their own means good and bad.
*
* @since 0.71
* @since 4.6.0 The `$comment` parameter was added.
* @since 4.6.0 Added the `$comment` parameter.
*
* @param string $linktext Optional. Text to display instead of the comment author's email address.
* Default empty.
@ -162,7 +162,7 @@ function comment_author_email_link( $linktext = '', $before = '', $after = '', $
* address and use it for their own means good and bad.
*
* @since 2.7.0
* @since 4.6.0 The `$comment` parameter was added.
* @since 4.6.0 Added the `$comment` parameter.
*
* @param string $linktext Optional. Text to display instead of the comment author's email address.
* Default empty.
@ -358,7 +358,7 @@ function comment_author_url( $comment_ID = 0 ) {
* in the order of $before, link, and finally $after.
*
* @since 1.5.0
* @since 4.6.0 The `$comment` parameter was added.
* @since 4.6.0 Added the `$comment` parameter.
*
* @param string $linktext Optional. The text to display instead of the comment
* author's email address. Default empty.
@ -396,7 +396,7 @@ function get_comment_author_url_link( $linktext = '', $before = '', $after = '',
* Displays the HTML link of the url of the author of the current comment.
*
* @since 0.71
* @since 4.6.0 The `$comment` parameter was added.
* @since 4.6.0 Added the `$comment` parameter.
*
* @param string $linktext Optional. Text to display instead of the comment author's
* email address. Default empty.

2
wp-includes/comment.php
View File

@ -2035,7 +2035,7 @@ function wp_update_comment($commentarr) {
* The hook also fires immediately before comment status transition hooks are fired.
*
* @since 1.2.0
* @since 4.6.0 The `$data` parameter was added.
* @since 4.6.0 Added the `$data` parameter.
*
* @param int $comment_ID The comment ID.
* @param array $data Comment data.

14
wp-includes/compat.php
View File

@ -517,13 +517,15 @@ if ( ! function_exists( 'spl_autoload_register' ) ):
}
/**
* Register a function to be autoloaded.
* Registers a function to be autoloaded.
*
* @since 4.6.0
*
* @param callable $autoload_function The function to register.
* @param boolean $throw Should the function throw an exception if the function isn't callable?
* @param boolean $prepend Should we prepend the function to the stack?
* @param bool $throw Optional. Whether the function should throw an exception
* if the function isn't callable. Default true.
* @param bool $prepend Whether the function should be prepended to the stack.
* Default false.
*/
function spl_autoload_register( $autoload_function, $throw = true, $prepend = false ) {
if ( $throw && ! is_callable( $autoload_function ) ) {
@ -546,12 +548,12 @@ if ( ! function_exists( 'spl_autoload_register' ) ):
}
/**
* Unregister an autoloader function.
* Unregisters an autoloader function.
*
* @since 4.6.0
*
* @param callable $function The function to unregister.
* @return boolean True if the function was unregistered, false if it could not be.
* @return bool True if the function was unregistered, false if it could not be.
*/
function spl_autoload_unregister( $function ) {
global $_wp_spl_autoloaders;
@ -566,7 +568,7 @@ if ( ! function_exists( 'spl_autoload_register' ) ):
}
/**
* Get the registered autoloader functions.
* Retrieves the registered autoloader functions.
*
* @since 4.6.0
*

6
wp-includes/formatting.php
View File

@ -1491,7 +1491,7 @@ function utf8_uri_encode( $utf8_string, $length = 0 ) {
* | U+00B7 | l·l | ll | Flown dot (between two Ls) |
*
* @since 1.2.1
* @since 4.6.0 Locale support was added for `de_CH`, `de_CH_informal`, and `ca`.
* @since 4.6.0 Added locale support for `de_CH`, `de_CH_informal`, and `ca`.
*
* @param string $string Text that might have accent characters
* @return string Filtered string with replaced "nice" characters.
@ -4922,13 +4922,13 @@ function print_emoji_detection_script() {
}
/**
* Print inline Emoji dection script
* Prints inline Emoji dection script
*
* @ignore
* @since 4.6.0
* @access private
*
* @global string $wp_version
* @global string $wp_version WordPress version string.
*/
function _print_emoji_detection_script() {
global $wp_version;

54
wp-includes/functions.php
View File

@ -2438,7 +2438,7 @@ function wp_get_mime_types() {
}
/**
* Retrieve list of common file extensions and their types.
* Retrieves the list of common file extensions and their types.
*
* @since 4.6.0
*
@ -3118,7 +3118,7 @@ function wp_send_json_error( $data = null ) {
}
/**
* Check that a JSONP callback is a valid JavaScript callback.
* Checks that a JSONP callback is a valid JavaScript callback.
*
* Only allows alphanumeric characters and the dot character in callback
* function names. This helps to mitigate XSS attacks caused by directly
@ -3902,10 +3902,10 @@ function _deprecated_argument( $function, $version, $message = null ) {
/**
* Marks a deprecated action or filter hook as deprecated and throws a notice.
*
* Use the 'deprecated_hook_run' action to get the backtrace describing where the
* deprecated hook was called.
* Use the {@see 'deprecated_hook_run'} action to get the backtrace describing where
* the deprecated hook was called.
*
* Default behavior is to trigger a user error if WP_DEBUG is true.
* Default behavior is to trigger a user error if `WP_DEBUG` is true.
*
* This function is called by the do_action_deprecated() and apply_filters_deprecated()
* functions, and so generally does not need to be called directly.
@ -3932,7 +3932,7 @@ function _deprecated_hook( $hook, $version, $replacement = null, $message = null
do_action( 'deprecated_hook_run', $hook, $replacement, $version, $message );
/**
* Filter whether to trigger deprecated hook errors.
* Filters whether to trigger deprecated hook errors.
*
* @since 4.6.0
*
@ -5364,11 +5364,10 @@ function mysql_to_rfc3339( $date_string ) {
*
* @since 4.6.0
*
* @param string $context Context in which the function is called.
* Either 'admin', 'image' or an arbitrary other context.
* Defaults to 'admin'.
* If an arbitrary context is passed, the similarly arbitrary
* "{$context}_memory_limit" filter will be invoked.
* @param string $context Optional. Context in which the function is called. Accepts either 'admin',
* 'image', or an arbitrary other context. If an arbitrary context is passed,
* the similarly arbitrary {@see '{$context}_memory_limit'} filter will be
* invoked. Default 'admin'.
* @return bool|int|string The limit that was set or false on failure.
*/
function wp_raise_memory_limit( $context = 'admin' ) {
@ -5393,20 +5392,20 @@ function wp_raise_memory_limit( $context = 'admin' ) {
/**
* Filters the maximum memory limit available for administration screens.
*
* This only applies to administrators, who may require more memory for tasks like updates.
* Memory limits when processing images (uploaded or edited by users of any role) are
* handled separately.
* This only applies to administrators, who may require more memory for tasks
* like updates. Memory limits when processing images (uploaded or edited by
* users of any role) are handled separately.
*
* The WP_MAX_MEMORY_LIMIT constant specifically defines the maximum memory limit available
* when in the administration back end. The default is 256M (256 megabytes
* of memory) or the original `memory_limit` php.ini value if this is higher.
* The `WP_MAX_MEMORY_LIMIT` constant specifically defines the maximum memory
* limit available when in the administration back end. The default is 256M
* (256 megabytes of memory) or the original `memory_limit` php.ini value if
* this is higher.
*
* @since 3.0.0
* @since 4.6.0 The default takes the original `memory_limit` into account.
* @since 4.6.0 The default now takes the original `memory_limit` into account.
*
* @param int|string $filtered_limit The maximum WordPress memory limit.
* Accepts an integer (bytes), or a shorthand string
* notation, such as '256M'.
* @param int|string $filtered_limit The maximum WordPress memory limit. Accepts an integer
* (bytes), or a shorthand string notation, such as '256M'.
*/
$filtered_limit = apply_filters( 'admin_memory_limit', $filtered_limit );
break;
@ -5416,11 +5415,11 @@ function wp_raise_memory_limit( $context = 'admin' ) {
* Filters the memory limit allocated for image manipulation.
*
* @since 3.5.0
* @since 4.6.0 The default takes the original `memory_limit` into account.
* @since 4.6.0 The default now takes the original `memory_limit` into account.
*
* @param int|string $filtered_limit Maximum memory limit to allocate for images.
* Default WP_MAX_MEMORY_LIMIT or the original
* php.ini memory_limit, whichever is higher.
* Default `WP_MAX_MEMORY_LIMIT` or the original
* php.ini `memory_limit`, whichever is higher.
* Accepts an integer (bytes), or a shorthand string
* notation, such as '256M'.
*/
@ -5438,10 +5437,9 @@ function wp_raise_memory_limit( $context = 'admin' ) {
* @since 4.6.0
*
* @param int|string $filtered_limit Maximum memory limit to allocate for images.
* Default 256M or the original php.ini memory_limit,
* whichever is higher.
* Accepts an integer (bytes), or a shorthand string
* notation, such as '256M'.
* Default '256M' or the original php.ini `memory_limit`,
* whichever is higher. Accepts an integer (bytes), or a
* shorthand string notation, such as '256M'.
*/
$filtered_limit = apply_filters( "{$context}_memory_limit", $filtered_limit );
break;

18
wp-includes/general-template.php
View File

@ -2255,7 +2255,7 @@ function the_modified_date( $d = '', $before = '', $after = '', $echo = true ) {
* Retrieve the date on which the post was last modified.
*
* @since 2.1.0
* @since 4.6.0 The `$post` parameter was added.
* @since 4.6.0 Added the `$post` parameter.
*
* @param string $d Optional. PHP date format defaults to the date_format option if not specified.
* @param int|WP_Post $post Optional. Post ID or WP_Post object. Default current post.
@ -2277,7 +2277,7 @@ function get_the_modified_date( $d = '', $post = null ) {
* Filters the date a post was last modified.
*
* @since 2.1.0
* @since 4.6.0 The `$post` parameter was added.
* @since 4.6.0 Added the `$post` parameter.
*
* @param string $the_time The formatted date.
* @param string $d PHP date format. Defaults to value specified in
@ -2408,7 +2408,7 @@ function the_modified_time($d = '') {
* Retrieve the time at which the post was last modified.
*
* @since 2.0.0
* @since 4.6.0 The `$post` parameter was added.
* @since 4.6.0 Added the `$post` parameter.
*
* @param string $d Optional. Format to use for retrieving the time the post
* was modified. Either 'G', 'U', or php date format defaults
@ -2432,7 +2432,7 @@ function get_the_modified_time( $d = '', $post = null ) {
* Filters the localized time a post was last modified.
*
* @since 2.0.0
* @since 4.6.0 The `$post` parameter was added.
* @since 4.6.0 Added the `$post` parameter.
*
* @param string $the_time The formatted time.
* @param string $d Format to use for retrieving the time the post was
@ -2788,10 +2788,12 @@ function wp_site_icon() {
}
/**
* Prints resource hints to browsers for pre-fetching, pre-rendering and pre-connecting to web sites.
* Prints resource hints to browsers for pre-fetching, pre-rendering
* and pre-connecting to web sites.
*
* Gives hints to browsers to prefetch specific pages or render them in the background,
* to perform DNS lookups or to begin the connection handshake (DNS, TCP, TLS) in the background.
* Gives hints to browsers to prefetch specific pages or render them
* in the background, to perform DNS lookups or to begin the connection
* handshake (DNS, TCP, TLS) in the background.
*
* These performance improving indicators work by using `<link rel"…">`.
*
@ -2851,7 +2853,7 @@ function wp_resource_hints() {
}
/**
* Returns a list of unique hosts of all enqueued scripts and styles.
* Retrieves a list of unique hosts of all enqueued scripts and styles.
*
* @since 4.6.0
*

4
wp-includes/kses.php
View File

@ -1708,8 +1708,8 @@ function safecss_filter_attr( $css, $deprecated = '' ) {
* Filters list of allowed CSS attributes.
*
* @since 2.8.1
* @since 4.4.0 `min-height`, `max-height`, `min-width`, and `max-width` were added.
* @since 4.6.0 `list-style-type` was added.
* @since 4.4.0 Added support for `min-height`, `max-height`, `min-width`, and `max-width`.
* @since 4.6.0 Added support for `list-style-type`.
*
* @param array $attr List of allowed CSS attributes.
*/

18
wp-includes/l10n.php
View File

@ -664,7 +664,7 @@ function load_default_textdomain( $locale = null ) {
}
/**
* Load a plugin's translated strings.
* Loads a plugin's translated strings.
*
* If the path is not given then it will be the root of the plugin directory.
*
@ -674,7 +674,7 @@ function load_default_textdomain( $locale = null ) {
* @since 4.6.0 The function now tries to load the .mo file from the languages directory first.
*
* @param string $domain Unique identifier for retrieving translated strings
* @param string $deprecated Use the $plugin_rel_path parameter instead.
* @param string $deprecated Optional. Use the $plugin_rel_path parameter instead. Defaukt false.
* @param string $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR where the .mo file resides.
* Default false.
* @return bool True when textdomain is successfully loaded, false otherwise.
@ -716,8 +716,8 @@ function load_plugin_textdomain( $domain, $deprecated = false, $plugin_rel_path
* @since 4.6.0 The function now tries to load the .mo file from the languages directory first.
*
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
* @param string $mu_plugin_rel_path Relative to WPMU_PLUGIN_DIR directory in which the .mo file resides.
* Default empty string.
* @param string $mu_plugin_rel_path Optional. Relative to `WPMU_PLUGIN_DIR` directory in which the .mo
* file resides. Default empty string.
* @return bool True when textdomain is successfully loaded, false otherwise.
*/
function load_muplugin_textdomain( $domain, $mu_plugin_rel_path = '' ) {
@ -799,11 +799,13 @@ function load_child_theme_textdomain( $domain, $path = false ) {
}
/**
* Just in time loading of plugin and theme textdomains.
* Loads plugin and theme textdomains just-in-time.
*
* When a textdomain is encountered for the first time, we try to load the translation file
* from wp-content/languages, removing the need to call `load_plugin_texdomain()` or
* `load_theme_texdomain()`. Holds a cached list of available .mo files to improve performance.
* When a textdomain is encountered for the first time, we try to load
* the translation file from `wp-content/languages`, removing the need
* to call load_plugin_texdomain() or load_theme_texdomain().
*
* Holds a cached list of available .mo files to improve performance.
*
* @since 4.6.0
* @access private

2
wp-includes/version.php
View File

@ -4,7 +4,7 @@
*
* @global string $wp_version
*/
$wp_version = '4.6-beta3-38120';
$wp_version = '4.6-beta3-38121';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.