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

Part 2/2.

Fixes #37318.

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


git-svn-id: http://core.svn.wordpress.org/trunk@38066 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/link-template.php

@@ -3597,7 +3597,7 @@ function wp_get_canonical_url( $post = null ) {
  * Outputs rel=canonical for singular queries.
  *
  * @since 2.9.0
- * @since 4.6.0 Adjusted to use `wp_get_canonical_url()`.
+ * @since 4.6.0 Adjusted to use wp_get_canonical_url().
  */
 function rel_canonical() {
 	if ( ! is_singular() ) {

wp-includes/meta.php

@@ -1097,7 +1097,6 @@ function registered_meta_key_exists( $object_type, $meta_key ) {
  *
  * @param string $object_type The type of object.
  * @param string $meta_key    The meta key.
- *
  * @return bool True if successful. False if the meta key was not registered.
  */
 function unregister_meta_key( $object_type, $meta_key ) {
@@ -1133,7 +1132,6 @@ function unregister_meta_key( $object_type, $meta_key ) {
  * @since 4.6.0
  *
  * @param string $object_type The type of object. Post, comment, user, term.
- *
  * @return array List of registered meta keys.
  */
 function get_registered_meta_keys( $object_type ) {
@@ -1155,7 +1153,6 @@ function get_registered_meta_keys( $object_type ) {
  * @param int    $object_id   ID of the object the metadata is for.
  * @param string $meta_key    Optional. Registered metadata key. If not specified, retrieve all registered
  *                            metadata for the specified object.
- *
  * @return mixed A single value or array of values for a key if specified. An array of all registered keys
  *               and values for an object ID if not.
  */

wp-includes/ms-blogs.php

@@ -462,7 +462,7 @@ function clean_blog_cache( $blog ) {
 	 * @since 4.6.0
 	 *
 	 * @param int     $id              Blog ID.
-	 * @param WP_Site $blog
+	 * @param WP_Site $blog            Site object.
 	 * @param string  $domain_path_key md5 hash of domain and path.
 	 */
 	do_action( 'clean_site_cache', $blog_id, $blog, $domain_path_key );
@@ -520,7 +520,6 @@ function get_site( &$site = null ) {
  * @access private
  *
  * @see update_site_cache()
- *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
  * @param array $ids ID list.
@@ -1089,7 +1088,7 @@ function get_networks( $args = array() ) {
  *
  * @global WP_Network $current_site
  *
- * @param WP_Network|int|null $network Network to retrieve.
+ * @param WP_Network|int|null $network Network to retrieve, passed by reference.
  * @return WP_Network|null The network object or null if not found.
  */
 function get_network( &$network = null ) {

wp-includes/ms-load.php

@@ -137,7 +137,7 @@ function get_network_by_path( $domain, $path, $segments = null ) {
  *
  * @since 3.9.0
  * @since 4.4.0 Converted to leverage WP_Network
- * @since 4.6.0 Converted to use `get_network()`
+ * @since 4.6.0 Converted to use get_network()
  *
  * @param object|int $network The network's database row or ID.
  * @return WP_Network|false Object containing network information if found, false if not.
@@ -283,7 +283,8 @@ function get_site_by_path( $domain, $path, $segments = null ) {
  *
  * @param string $domain    The requested domain.
  * @param string $path      The requested path.
- * @param bool   $subdomain Whether a subdomain (true) or subdirectory (false) configuration.
+ * @param bool   $subdomain Optional. Whether a subdomain (true) or subdirectory (false) configuration.
+ *                          Default false.
  * @return bool|string True if bootstrap successfully populated `$current_blog` and `$current_site`.
  *                     False if bootstrap could not be properly completed.
  *                     Redirect URL if parts exist, but the request as a whole can not be fulfilled.

wp-includes/plugin.php

@@ -669,8 +669,8 @@ function remove_all_actions($tag, $priority = false) {
  * @param string $tag         The name of the filter hook.
  * @param array  $args        Array of additional function arguments to be passed to apply_filters().
  * @param string $version     The version of WordPress that deprecated the hook.
- * @param string $replacement Optional. The hook that should have been used.
+ * @param string $replacement Optional. The hook that should have been used. Default false.
- * @param string $message     Optional. A message regarding the change.
+ * @param string $message     Optional. A message regarding the change. Default null.
  */
 function apply_filters_deprecated( $tag, $args, $version, $replacement = false, $message = null ) {
 	if ( ! has_filter( $tag ) ) {
@@ -1003,7 +1003,7 @@ function _wp_filter_build_unique_id($tag, $function, $priority) {
 }
 
 /**
- * Back up global variables used for actions and filters.
+ * Backs up global variables used for actions and filters.
  *
  * Prevents redefinition of these globals in advanced-cache.php from accidentally
  * destroying existing data.
@@ -1016,11 +1016,14 @@ function _wp_filter_build_unique_id($tag, $function, $priority) {
  * @global array $merged_filters    Merges the filter hooks using this function.
  * @global array $wp_current_filter Stores the list of current filters with the current one last.
  * @staticvar array $backup_globals Backed up globals.
+ *
  * @return array the staticvar from the first time it is set.
  */
 function _backup_plugin_globals(){
 	global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter;
+
 	static $backup_globals = array();
+
 	if ( empty( $backup_globals ) ) {
 		$backup_globals = array(
 			'backup_wp_filter'         => $wp_filter,
@@ -1033,7 +1036,7 @@ function _backup_plugin_globals(){
 }
 
 /**
- * Safely restore backed up global variables used for actions and filters.
+ * Safely restores backed up global variables used for actions and filters.
  *
  * @since 4.6.0
  * @access private
@@ -1046,7 +1049,9 @@ function _backup_plugin_globals(){
  */
 function _restore_plugin_globals(){
 	global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter;
+
 	$backup_globals = _backup_plugin_globals();
+
 	if ( $wp_filter !== $backup_globals['backup_wp_filter'] ){
 		$wp_filter = array_merge_recursive( $wp_filter, $backup_globals['backup_wp_filter'] );
 	}

wp-includes/post.php

@@ -4316,7 +4316,7 @@ function _page_traverse_name( $page_id, &$children, &$result ){
  * Sub pages will be in the "directory" under the parent page post name.
  *
  * @since 1.5.0
- * @since 4.6.0 The $page parameter is optional.
+ * @since 4.6.0 Converted the `$page` parameter to optional.
  *
  * @param WP_Post|object|int $page Optional. Page ID or WP_Post object. Default is global $post.
  * @return string|false Page URI, false on error.
@@ -4955,7 +4955,7 @@ function wp_get_attachment_url( $post_id = 0 ) {
  *
  * @since 4.6.0
  *
- * @param int $post_id Optional. Attachment ID. Default 0.
+ * @param int $post_id Optional. Attachment ID. Default is the ID of the global `$post`.
  * @return string|false False on failure. Attachment caption on success.
  */
 function wp_get_attachment_caption( $post_id = 0 ) {

wp-includes/query.php

@@ -1473,7 +1473,7 @@ class WP_Query {
 	 * @since 4.5.0 Removed the `$comments_popup` parameter.
 	 *              Introduced the `$comment_status` and `$ping_status` parameters.
 	 *              Introduced `RAND(x)` syntax for `$orderby`, which allows an integer seed value to random sorts.
-	 * @since 4.6.0 Added 'post_name__in' support for `$orderby`. Introduced `$lazy_load_term_meta`.
+	 * @since 4.6.0 Added 'post_name__in' support for `$orderby`. Introduced the `$lazy_load_term_meta` argument.
 	 * @access public
 	 *
 	 * @param string|array $query {

wp-includes/script-loader.php

@@ -918,6 +918,7 @@ function wp_just_in_time_script_localization() {
  * @since 4.6.0
  *
  * @link http://api.jqueryui.com/datepicker/#options
+ *
  * @global WP_Locale $wp_locale The WordPress date and time locale object.
  */
 function wp_localize_jquery_ui_datepicker() {

wp-includes/taxonomy.php

@@ -1225,7 +1225,7 @@ function get_terms( $args = array(), $deprecated = '' ) {
 	 * Filters the found terms.
 	 *
 	 * @since 2.3.0
-	 * @since 4.6.0 Added `$term_query`.
+	 * @since 4.6.0 Added the `$term_query` parameter.
 	 *
 	 * @param array         $terms      Array of found terms.
 	 * @param array         $taxonomies An array of taxonomies.

wp-includes/user.php

@@ -2333,16 +2333,18 @@ function register_new_user( $user_login, $user_email ) {
 }
 
 /**
- * Initiate email notifications related to the creation of new users.
+ * Initiates email notifications related to the creation of new users.
  *
  * Notifications are sent both to the site admin and to the newly created user.
  *
  * @since 4.4.0
- * @since 4.6.0 The `$notify` parameter accepts 'user' for sending notification only to the user created.
+ * @since 4.6.0 Converted the `$notify` parameter to accept 'user' for sending
+ *              notifications only to the user created.
  *
  * @param int    $user_id ID of the newly created user.
- * @param string $notify  Optional. Type of notification that should happen. Accepts 'admin' or an empty string
+ * @param string $notify  Optional. Type of notification that should happen. Accepts 'admin'
- *                        (admin only), 'user', or 'both' (admin and user). Default 'both'.
+ *                        or an empty string (admin only), 'user', or 'both' (admin and user).
+ *                        Default 'both'.
  */
 function wp_send_new_user_notifications( $user_id, $notify = 'both' ) {
 	wp_new_user_notification( $user_id, null, $notify );

wp-includes/version.php

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

wp-includes/wp-db.php

@@ -756,15 +756,15 @@ class wpdb {
 	}
 
 	/**
-	 * Given a charset and collation, determine the best charset and collation to use.
+	 * Determines the best charset and collation to use given a charset and collation.
 	 *
 	 * For example, when able, utf8mb4 should be used instead of utf8.
 	 *
 	 * @since 4.6.0
+	 * @access public
 	 *
 	 * @param string $charset The character set to check.
 	 * @param string $collate The collation to check.
-	 *
 	 * @return array The most appropriate character set and collation to use.
 	 */
 	public function determine_charset( $charset, $collate ) {
@@ -3236,8 +3236,8 @@ class wpdb {
 	 * Determine if a database supports a particular feature.
 	 *
 	 * @since 2.7.0
-	 * @since 4.1.0 Support was added for the 'utf8mb4' feature.
+	 * @since 4.1.0 Added support for the 'utf8mb4' feature.
-	 * @since 4.6.0 Support was added for the 'utf8mb4_520' feature.
+	 * @since 4.6.0 Added support for the 'utf8mb4_520' feature.
 	 *
 	 * @see wpdb::db_version()
 	 *