Docs: All sorts of improvements and corrections to function and hook docs.

See #57840

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


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

wp-admin/includes/ms.php

@@ -130,12 +130,17 @@ function wpmu_delete_blog( $blog_id, $drop = false ) {
 }
 
 /**
- * Deletes a user from the network and remove from all sites.
+ * Deletes a user and all of their posts from the network.
+ *
+ * This function:
+ *
+ * - Deletes all posts (of all post types) authored by the user on all sites on the network
+ * - Deletes all links owned by the user on all sites on the network
+ * - Removes the user from all sites on the network
+ * - Deletes the user from the database
  *
  * @since 3.0.0
  *
- * @todo Merge with wp_delete_user()?
- *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
  * @param int $id The user ID.

wp-admin/includes/user.php

@@ -324,12 +324,15 @@ function get_users_drafts( $user_id ) {
 }
 
 /**
- * Remove user and optionally reassign posts and links to another user.
+ * Delete user and optionally reassign posts and links to another user.
  *
- * If the $reassign parameter is not assigned to a User ID, then all posts will
+ * Note that on a Multisite installation the user only gets removed from the site
- * be deleted of that user. The action {@see 'delete_user'} that is passed the User ID
+ * and does not get deleted from the database.
+ *
+ * If the `$reassign` parameter is not assigned to a user ID, then all posts will
+ * be deleted of that user. The action {@see 'delete_user'} that is passed the user ID
  * being deleted will be run after the posts are either reassigned or deleted.
- * The user meta will also be deleted that are for that User ID.
+ * The user meta will also be deleted that are for that user ID.
  *
  * @since 2.0.0
  *
@@ -361,7 +364,10 @@ function wp_delete_user( $id, $reassign = null ) {
 	}
 
 	/**
-	 * Fires immediately before a user is deleted from the database.
+	 * Fires immediately before a user is deleted from the site.
+	 *
+	 * Note that on a Multisite installation the user only gets removed from the site
+	 * and does not get deleted from the database.
 	 *
 	 * @since 2.0.0
 	 * @since 5.5.0 Added the `$user` parameter.
@@ -440,7 +446,11 @@ function wp_delete_user( $id, $reassign = null ) {
 	clean_user_cache( $user );
 
 	/**
-	 * Fires immediately after a user is deleted from the database.
+	 * Fires immediately after a user is deleted from the site.
+	 *
+	 * Note that on a Multisite installation the user may not have been deleted from
+	 * the database depending on whether `wp_delete_user()` or `wpmu_delete_user()`
+	 * was called.
 	 *
 	 * @since 2.9.0
 	 * @since 5.5.0 Added the `$user` parameter.

wp-includes/block-template-utils.php

@@ -299,7 +299,7 @@ function _get_block_template_file( $template_type, $slug ) {
  *
  *     @type array  $slug__in     List of slugs to include.
  *     @type array  $slug__not_in List of slugs to skip.
- *     @type string $area         A 'wp_template_part_area' taxonomy value to filter by (for wp_template_part template type only).
+ *     @type string $area         A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only).
  *     @type string $post_type    Post type to get the templates for.
  * }
  *
@@ -755,7 +755,7 @@ function _wp_build_title_and_description_for_taxonomy_block_template( $taxonomy,
  * @access private
  *
  * @param WP_Post $post Template post.
- * @return WP_Block_Template|WP_Error Template.
+ * @return WP_Block_Template|WP_Error Template or error object.
  */
 function _build_block_template_result_from_post( $post ) {
 	$default_template_types = get_default_block_template_types();
@@ -1055,9 +1055,9 @@ function get_block_templates( $query = array(), $template_type = 'wp_template' )
  *
  * @since 5.8.0
  *
- * @param string $id            Template unique identifier (example: theme_slug//template_slug).
+ * @param string $id            Template unique identifier (example: 'theme_slug//template_slug').
- * @param string $template_type Optional. Template type: `'wp_template'` or '`wp_template_part'`.
+ * @param string $template_type Optional. Template type: 'wp_template' or 'wp_template_part'.
- *                              Default `'wp_template'`.
+ *                              Default 'wp_template'.
  * @return WP_Block_Template|null Template.
  */
 function get_block_template( $id, $template_type = 'wp_template' ) {
@@ -1070,8 +1070,8 @@ function get_block_template( $id, $template_type = 'wp_template' ) {
 	 *
 	 * @param WP_Block_Template|null $block_template Return block template object to short-circuit the default query,
 	 *                                               or null to allow WP to run its normal queries.
-	 * @param string                 $id             Template unique identifier (example: theme_slug//template_slug).
+	 * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
-	 * @param string                 $template_type  Template type: `'wp_template'` or '`wp_template_part'`.
+	 * @param string                 $template_type  Template type: 'wp_template' or 'wp_template_part'.
 	 */
 	$block_template = apply_filters( 'pre_get_block_template', null, $id, $template_type );
 	if ( ! is_null( $block_template ) ) {
@@ -1116,8 +1116,8 @@ function get_block_template( $id, $template_type = 'wp_template' ) {
 	 * @since 5.9.0
 	 *
 	 * @param WP_Block_Template|null $block_template The found block template, or null if there isn't one.
-	 * @param string                 $id             Template unique identifier (example: theme_slug//template_slug).
+	 * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
-	 * @param array                  $template_type  Template type: `'wp_template'` or '`wp_template_part'`.
+	 * @param array                  $template_type  Template type: 'wp_template' or 'wp_template_part'.
 	 */
 	return apply_filters( 'get_block_template', $block_template, $id, $template_type );
 }
@@ -1129,9 +1129,9 @@ function get_block_template( $id, $template_type = 'wp_template' ) {
  *
  * @since 5.9.0
  *
- * @param string $id            Template unique identifier (example: theme_slug//template_slug).
+ * @param string $id            Template unique identifier (example: 'theme_slug//template_slug').
- * @param string $template_type Optional. Template type: `'wp_template'` or '`wp_template_part'`.
+ * @param string $template_type Optional. Template type: 'wp_template' or 'wp_template_part'.
- *                              Default `'wp_template'`.
+ *                              Default 'wp_template'.
  * @return WP_Block_Template|null The found block template, or null if there isn't one.
  */
 function get_block_file_template( $id, $template_type = 'wp_template' ) {
@@ -1144,8 +1144,8 @@ function get_block_file_template( $id, $template_type = 'wp_template' ) {
 	 *
 	 * @param WP_Block_Template|null $block_template Return block template object to short-circuit the default query,
 	 *                                               or null to allow WP to run its normal queries.
-	 * @param string                 $id             Template unique identifier (example: theme_slug//template_slug).
+	 * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
-	 * @param string                 $template_type  Template type: `'wp_template'` or '`wp_template_part'`.
+	 * @param string                 $template_type  Template type: 'wp_template' or 'wp_template_part'.
 	 */
 	$block_template = apply_filters( 'pre_get_block_file_template', null, $id, $template_type );
 	if ( ! is_null( $block_template ) ) {
@@ -1178,8 +1178,8 @@ function get_block_file_template( $id, $template_type = 'wp_template' ) {
 	 * @since 5.9.0
 	 *
 	 * @param WP_Block_Template|null $block_template The found block template, or null if there is none.
-	 * @param string                 $id             Template unique identifier (example: theme_slug//template_slug).
+	 * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
-	 * @param string                 $template_type  Template type: `'wp_template'` or '`wp_template_part'`.
+	 * @param string                 $template_type  Template type: 'wp_template' or 'wp_template_part'.
 	 */
 	return apply_filters( 'get_block_file_template', $block_template, $id, $template_type );
 }

wp-includes/class-wp-post-type.php

@@ -410,6 +410,7 @@ final class WP_Post_Type {
 	 *
 	 * @param string       $post_type Post type key.
 	 * @param array|string $args      Optional. Array or string of arguments for registering a post type.
+	 *                                See register_post_type() for information on accepted arguments.
 	 *                                Default empty array.
 	 */
 	public function __construct( $post_type, $args = array() ) {

wp-includes/class-wp-taxonomy.php

@@ -281,6 +281,7 @@ final class WP_Taxonomy {
 	 * @param string       $taxonomy    Taxonomy key, must not exceed 32 characters.
 	 * @param array|string $object_type Name of the object type for the taxonomy object.
 	 * @param array|string $args        Optional. Array or query string of arguments for registering a taxonomy.
+	 *                                  See register_taxonomy() for information on accepted arguments.
 	 *                                  Default empty array.
 	 */
 	public function __construct( $taxonomy, $object_type, $args = array() ) {

wp-includes/class-wp-theme-json-resolver.php

@@ -13,7 +13,7 @@
  *
  * This class is for internal core usage and is not supposed to be used by extenders (plugins and/or themes).
  * This is a low-level API that may need to do breaking changes. Please,
- * use get_global_settings, get_global_styles, and get_global_stylesheet instead.
+ * use get_global_settings(), get_global_styles(), and get_global_stylesheet() instead.
  *
  * @access private
  */
@@ -386,7 +386,7 @@ class WP_Theme_JSON_Resolver {
 
 	/**
 	 * Returns the custom post type that contains the user's origin config
-	 * for the active theme or a void array if none are found.
+	 * for the active theme or an empty array if none are found.
 	 *
 	 * This can also create and return a new draft custom post type.
 	 *

wp-includes/class-wpdb.php

@@ -2556,13 +2556,13 @@ class wpdb {
 	 *
 	 * @param string       $table  Table name.
 	 * @param array        $data   Data to insert (in column => value pairs).
-	 *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
+	 *                             Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
 	 *                             Sending a null value will cause the column to be set to NULL - the corresponding
 	 *                             format is ignored in this case.
-	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
+	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
-	 *                             If string, that format will be used for all of the values in $data.
+	 *                             If string, that format will be used for all of the values in `$data`.
 	 *                             A format is one of '%d', '%f', '%s' (integer, float, string).
-	 *                             If omitted, all values in $data will be treated as strings unless otherwise
+	 *                             If omitted, all values in `$data` will be treated as strings unless otherwise
 	 *                             specified in wpdb::$field_types. Default null.
 	 * @return int|false The number of rows inserted, or false on error.
 	 */
@@ -2586,13 +2586,13 @@ class wpdb {
 	 *
 	 * @param string       $table  Table name.
 	 * @param array        $data   Data to insert (in column => value pairs).
-	 *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
+	 *                             Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
 	 *                             Sending a null value will cause the column to be set to NULL - the corresponding
 	 *                             format is ignored in this case.
-	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
+	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
-	 *                             If string, that format will be used for all of the values in $data.
+	 *                             If string, that format will be used for all of the values in `$data`.
 	 *                             A format is one of '%d', '%f', '%s' (integer, float, string).
-	 *                             If omitted, all values in $data will be treated as strings unless otherwise
+	 *                             If omitted, all values in `$data` will be treated as strings unless otherwise
 	 *                             specified in wpdb::$field_types. Default null.
 	 * @return int|false The number of rows affected, or false on error.
 	 */
@@ -2603,7 +2603,7 @@ class wpdb {
 	/**
 	 * Helper function for insert and replace.
 	 *
-	 * Runs an insert or replace query based on $type argument.
+	 * Runs an insert or replace query based on `$type` argument.
 	 *
 	 * @since 3.0.0
 	 *
@@ -2613,15 +2613,15 @@ class wpdb {
 	 *
 	 * @param string       $table  Table name.
 	 * @param array        $data   Data to insert (in column => value pairs).
-	 *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
+	 *                             Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
 	 *                             Sending a null value will cause the column to be set to NULL - the corresponding
 	 *                             format is ignored in this case.
-	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
+	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
-	 *                             If string, that format will be used for all of the values in $data.
+	 *                             If string, that format will be used for all of the values in `$data`.
 	 *                             A format is one of '%d', '%f', '%s' (integer, float, string).
-	 *                             If omitted, all values in $data will be treated as strings unless otherwise
+	 *                             If omitted, all values in `$data` will be treated as strings unless otherwise
 	 *                             specified in wpdb::$field_types. Default null.
-	 * @param string       $type   Optional. Type of operation. Possible values include 'INSERT' or 'REPLACE'.
+	 * @param string       $type   Optional. Type of operation. Either 'INSERT' or 'REPLACE'.
 	 *                             Default 'INSERT'.
 	 * @return int|false The number of rows affected, or false on error.
 	 */

wp-includes/http.php

@@ -39,6 +39,7 @@ function _wp_http_get_object() {
  *
  * @param string $url  URL to retrieve.
  * @param array  $args Optional. Request arguments. Default empty array.
+ *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  */
 function wp_safe_remote_request( $url, $args = array() ) {
@@ -60,6 +61,7 @@ function wp_safe_remote_request( $url, $args = array() ) {
  *
  * @param string $url  URL to retrieve.
  * @param array  $args Optional. Request arguments. Default empty array.
+ *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  */
 function wp_safe_remote_get( $url, $args = array() ) {
@@ -81,6 +83,7 @@ function wp_safe_remote_get( $url, $args = array() ) {
  *
  * @param string $url  URL to retrieve.
  * @param array  $args Optional. Request arguments. Default empty array.
+ *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  */
 function wp_safe_remote_post( $url, $args = array() ) {
@@ -102,6 +105,7 @@ function wp_safe_remote_post( $url, $args = array() ) {
  *
  * @param string $url  URL to retrieve.
  * @param array  $args Optional. Request arguments. Default empty array.
+ *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  */
 function wp_safe_remote_head( $url, $args = array() ) {
@@ -125,6 +129,7 @@ function wp_safe_remote_head( $url, $args = array() ) {
  *
  * @param string $url  URL to retrieve.
  * @param array  $args Optional. Request arguments. Default empty array.
+ *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error {
  *     The response array or a WP_Error on failure.
  *
@@ -155,6 +160,7 @@ function wp_remote_request( $url, $args = array() ) {
  *
  * @param string $url  URL to retrieve.
  * @param array  $args Optional. Request arguments. Default empty array.
+ *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  */
 function wp_remote_get( $url, $args = array() ) {
@@ -172,6 +178,7 @@ function wp_remote_get( $url, $args = array() ) {
  *
  * @param string $url  URL to retrieve.
  * @param array  $args Optional. Request arguments. Default empty array.
+ *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  */
 function wp_remote_post( $url, $args = array() ) {
@@ -189,6 +196,7 @@ function wp_remote_post( $url, $args = array() ) {
  *
  * @param string $url  URL to retrieve.
  * @param array  $args Optional. Request arguments. Default empty array.
+ *                     See WP_Http::request() for information on accepted arguments.
  * @return array|WP_Error The response or WP_Error on failure.
  */
 function wp_remote_head( $url, $args = array() ) {

wp-includes/plugin.php

@@ -575,7 +575,7 @@ function do_action_ref_array( $hook_name, $args ) {
  *
  * @since 2.5.0
  *
- * @see has_filter() has_action() is an alias of has_filter().
+ * @see has_filter() This function is an alias of has_filter().
  *
  * @param string                      $hook_name The name of the action hook.
  * @param callable|string|array|false $callback  Optional. The callback to check for.
@@ -964,18 +964,7 @@ function _wp_call_all_hook( $args ) {
 }
 
 /**
- * Builds Unique ID for storage and retrieval.
+ * Builds a unique string ID for a hook callback function.
- *
- * The old way to serialize the callback caused issues and this function is the
- * solution. It works by checking for objects and creating a new property in
- * the class to keep track of the object and new objects of the same class that
- * need to be added.
- *
- * It also allows for the removal of actions and filters for objects after they
- * change class properties. It is possible to include the property $wp_filter_id
- * in your class and set it to "null" or a number to bypass the workaround.
- * However this will prevent you from adding new classes and any new classes
- * will overwrite the previous hook by the same class.
  *
  * Functions and static method callbacks are just returned as strings and
  * shouldn't have any speed penalty.

wp-includes/post-template.php

@@ -37,7 +37,8 @@ function get_the_ID() { // phpcs:ignore WordPress.NamingConventions.ValidFunctio
  * @param string $before  Optional. Markup to prepend to the title. Default empty.
  * @param string $after   Optional. Markup to append to the title. Default empty.
  * @param bool   $display Optional. Whether to echo or return the title. Default true for echo.
- * @return void|string Void if `$display` argument is true, current post title if `$display` is false.
+ * @return void|string Void if `$display` argument is true or the title is empty,
+ *                     current post title if `$display` is false.
  */
 function the_title( $before = '', $after = '', $display = true ) {
 	$title = get_the_title();

wp-includes/post.php

@@ -6139,7 +6139,7 @@ function is_local_attachment( $url ) {
  *
  * @param string|array $args             Arguments for inserting an attachment.
  * @param string|false $file             Optional. Filename. Default false.
- * @param int          $parent_post_id   Optional. Parent post ID. Default 0.
+ * @param int          $parent_post_id   Optional. Parent post ID or 0 for no parent. Default 0.
  * @param bool         $wp_error         Optional. Whether to return a WP_Error on failure. Default false.
  * @param bool         $fire_after_hooks Optional. Whether to fire the after insert hooks. Default true.
  * @return int|WP_Error The attachment ID on success. The value 0 or WP_Error on failure.

wp-includes/theme.php

@@ -825,6 +825,8 @@ function switch_theme( $stylesheet ) {
 	/**
 	 * Fires after the theme is switched.
 	 *
+	 * See {@see 'after_switch_theme'}.
+	 *
 	 * @since 1.5.0
 	 * @since 4.5.0 Introduced the `$old_theme` parameter.
 	 *
@@ -3386,13 +3388,14 @@ function check_theme_switched() {
 
 		if ( $old_theme->exists() ) {
 			/**
-			 * Fires on the first WP load after a theme switch if the old theme still exists.
+			 * Fires on the next WP load after the theme has been switched.
 			 *
-			 * This action fires multiple times and the parameters differs
+			 * The parameters differ according to whether the old theme exists or not.
-			 * according to the context, if the old theme exists or not.
+			 * If the old theme is missing, the old name will instead be the slug
-			 * If the old theme is missing, the parameter will be the slug
 			 * of the old theme.
 			 *
+			 * See {@see 'switch_theme'}.
+			 *
 			 * @since 3.3.0
 			 *
 			 * @param string   $old_name  Old theme name.

wp-includes/version.php

@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.3-alpha-55693';
+$wp_version = '6.3-alpha-55694';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.